pi-mega-compact 0.13.4 → 0.13.6

package/extensions/dashboard-client/src/tabs/WikiTab.tsx

@@ -0,0 +1,222 @@
+/**
+ * dashboard-client/src/tabs/WikiTab.tsx — Wiki Revival (W3): wiki landing list.
+ *
+ * Replaces TopicsTab in the App registry (TopicsTab.tsx kept, unused). Renders
+ * the wiki index: each auto-categorized topic with its resolved label (edited
+ * badge when user-renamed), member count, curation badges (label/merge/split),
+ * and a click-to-open that pushes a client-side page state to WikiPage.
+ *
+ * Styling is Tailwind + shadcn (Card, Badge, Button) — no legacy CSS classes.
+ */
+
+import type React from "react";
+import { useCallback, useMemo, useState } from "react";
+import { useApi } from "../hooks/useApi";
+import { fetchWikiIndex } from "../api/client";
+import type { WikiIndexEntry, WikiIndexResponse } from "@contracts";
+import { Badge } from "../components/ui/badge";
+import { Button } from "../components/ui/button";
+import { Toggle } from "../components/ui/toggle";
+import WikiPage from "./WikiTab/WikiPage";
+import TopicEvolutionView from "./WikiTab/TopicEvolutionView";
+
+type WikiView = "list" | "evolution";
+
+const KIND_BADGES: Record<string, "default" | "accent" | "warning"> = {
+	label: "accent",
+	merge: "warning",
+	split: "default",
+};
+
+function fmtTs(ms: number | null): string {
+	if (!ms) return "—";
+	return new Date(ms).toLocaleString();
+}
+
+function ViewToggle({
+	view,
+	onChange,
+}: {
+	view: WikiView;
+	onChange: (v: WikiView) => void;
+}): React.ReactElement {
+	return (
+		<div className="flex gap-1">
+			<Toggle pressed={view === "list"} onClick={() => onChange("list")}>
+				Topics
+			</Toggle>
+			<Toggle
+				pressed={view === "evolution"}
+				onClick={() => onChange("evolution")}
+			>
+				Evolution
+			</Toggle>
+		</div>
+	);
+}
+
+interface RowProps {
+	entry: WikiIndexEntry;
+	onOpen: (id: string) => void;
+}
+
+function TopicRow({ entry, onOpen }: RowProps): React.ReactElement {
+	return (
+		<tr className="border-b border-border/60 last:border-0 hover:bg-bg-elevated/40">
+			<td className="py-2 pr-3">
+				<div className="flex items-center gap-2">
+					<span className="font-medium text-foreground">{entry.label}</span>
+					{entry.edited && <Badge variant="outline">edited</Badge>}
+				</div>
+			</td>
+			<td className="py-2 pr-3 text-sm text-muted-foreground">
+				{entry.memoryCount}
+			</td>
+			<td className="py-2 pr-3">
+				<div className="flex flex-wrap gap-1">
+					{entry.overrideKinds.map((k) => (
+						<Badge key={k} variant={KIND_BADGES[k] ?? "default"}>
+							{k}
+						</Badge>
+					))}
+				</div>
+			</td>
+			<td className="py-2 pr-3 text-xs text-muted-foreground">
+				{fmtTs(entry.lastUpdated)}
+			</td>
+			<td className="py-2 text-right">
+				<Button
+					variant="outline"
+					size="sm"
+					onClick={() => onOpen(entry.id)}
+				>
+					Open
+				</Button>
+			</td>
+		</tr>
+	);
+}
+
+export default function WikiTab(): React.ReactElement {
+	const { data, loading, error } = useApi<WikiIndexResponse>(
+		useCallback(() => fetchWikiIndex(), []),
+		{ pollInterval: 30_000 },
+	);
+	const [view, setView] = useState<WikiView>("list");
+	const [query, setQuery] = useState("");
+	const [openId, setOpenId] = useState<string | null>(null);
+
+	const filtered = useMemo(() => {
+		if (!data) return [];
+		const q = query.trim().toLowerCase();
+		if (!q) return data.topics;
+		return data.topics.filter((t) =>
+			t.label.toLowerCase().includes(q),
+		);
+	}, [data, query]);
+
+	if (openId) {
+		return <WikiPage topicId={openId} onBack={() => setOpenId(null)} />;
+	}
+
+	if (view === "evolution") {
+		return (
+			<div className="flex flex-col gap-3">
+				<ViewToggle view={view} onChange={setView} />
+				<TopicEvolutionView />
+			</div>
+		);
+	}
+
+	if (error && !data) {
+		return (
+			<div className="rounded-lg border border-border bg-bg-card p-6 text-sm text-danger">
+				Error loading wiki: {error.message}
+			</div>
+		);
+	}
+	if (loading && !data) {
+		return (
+			<div className="rounded-lg border border-border bg-bg-card p-6 text-sm text-muted-foreground">
+				Loading wiki…
+			</div>
+		);
+	}
+	if (!data) {
+		return (
+			<div className="rounded-lg border border-border bg-bg-card p-6 text-sm text-muted-foreground">
+				No wiki data available.
+			</div>
+		);
+	}
+	if (data.totalTopics === 0) {
+		return (
+			<div className="rounded-lg border border-border bg-bg-card p-6 text-sm text-muted-foreground">
+				<h3 className="mb-2 font-heading text-base text-foreground">Wiki</h3>
+				<p>
+					No topics yet. Topics are auto-generated after every Nth compaction
+					from real memory embeddings (k-means + TF-IDF).
+				</p>
+				<p className="mt-2">Check back after a few more compaction cycles.</p>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col gap-4">
+			<div className="flex flex-wrap items-end justify-between gap-2">
+				<div className="flex items-center gap-3">
+					<ViewToggle view={view} onChange={setView} />
+					<div>
+						<h2 className="font-heading text-lg font-semibold">Wiki</h2>
+						<p className="text-sm text-muted-foreground">
+							{data.totalTopics} topic{data.totalTopics !== 1 ? "s" : ""} ·{" "}
+							{data.totalMemories} assigned memori
+							{data.totalMemories !== 1 ? "es" : "y"}
+							{data.lastRebuildAt != null && (
+								<> · last rebuild {fmtTs(data.lastRebuildAt)}</>
+							)}
+						</p>
+					</div>
+				</div>
+				<input
+					type="search"
+					placeholder="Filter topics by label…"
+					aria-label="Filter topics by label"
+					value={query}
+					onChange={(e) => setQuery(e.target.value)}
+					className="w-64 rounded-md border border-border bg-bg-elevated/50 px-3 py-2 text-sm outline-none transition-colors focus:border-primary"
+				/>
+			</div>
+
+			<div className="overflow-x-auto rounded-lg border border-border bg-bg-card">
+				<table className="w-full table-fixed text-sm">
+					<thead>
+						<tr className="border-b border-border text-left text-xs uppercase text-muted-foreground">
+							<th className="w-1/3 px-4 py-2 font-medium">Label</th>
+							<th className="w-16 py-2 font-medium">Memories</th>
+							<th className="w-40 py-2 font-medium">Badges</th>
+							<th className="w-40 py-2 font-medium">Last updated</th>
+							<th className="w-20 py-2" />
+						</tr>
+					</thead>
+					<tbody>
+						{filtered.map((t) => (
+							<TopicRow key={t.id} entry={t} onOpen={setOpenId} />
+						))}
+						{filtered.length === 0 && (
+							<tr>
+								<td
+									colSpan={5}
+									className="px-4 py-6 text-center text-muted-foreground"
+								>
+									No topics match "{query}".
+								</td>
+							</tr>
+						)}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	);
+}

package/extensions/dashboard-client/src/tabs/registry.ts

@@ -0,0 +1,57 @@
+import type { LucideIcon } from "lucide-react";
+import {
+  LayoutGrid,
+  Database,
+  MessagesSquare,
+  GitBranch,
+  HeartPulse,
+  FolderGit2,
+  ScrollText,
+  Settings,
+  BarChart3,
+  BookOpen,
+  Wrench,
+  Network,
+} from "lucide-react";
+
+export type TabId =
+  | "overview"
+  | "repos"
+  | "events"
+  | "setup"
+  | "metrics"
+  | "cache"
+  | "sessions"
+  | "wiki"
+  | "turns"
+  | "maintenance"
+  | "memory-map"
+  | "health";
+
+export interface TabDef {
+  id: TabId;
+  label: string;
+  icon: LucideIcon;
+}
+
+export const PRIMARY_TABS: TabDef[] = [
+  { id: "overview", label: "Overview", icon: LayoutGrid },
+  { id: "cache", label: "Cache", icon: Database },
+  { id: "sessions", label: "Sessions", icon: MessagesSquare },
+  { id: "turns", label: "Turns", icon: GitBranch },
+  { id: "health", label: "Health", icon: HeartPulse },
+];
+
+export const ADVANCED_TABS: TabDef[] = [
+  { id: "repos", label: "Repos", icon: FolderGit2 },
+  { id: "events", label: "Events", icon: ScrollText },
+  { id: "setup", label: "Setup", icon: Settings },
+  { id: "metrics", label: "Metrics", icon: BarChart3 },
+  { id: "wiki", label: "Wiki", icon: BookOpen },
+  { id: "maintenance", label: "Maintenance", icon: Wrench },
+  { id: "memory-map", label: "Memory Map", icon: Network },
+];
+
+export const ADVANCED_TAB_IDS: ReadonlySet<TabId> = new Set(
+  ADVANCED_TABS.map((t) => t.id),
+);

package/extensions/dashboard-client/src/utils/cn.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** Combine className inputs then de-duplicate/merge conflicting Tailwind classes. */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/extensions/dashboard-client/tailwind.config.js

@@ -0,0 +1,46 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: ["class"],
+  content: ["./index.html", "./src/**/*.{ts,tsx}"],
+  theme: {
+    container: {
+      center: true,
+      padding: "1.5rem",
+      screens: { "2xl": "1600px" },
+    },
+    extend: {
+      colors: {
+        background: "hsl(var(--bg))",
+        "bg-card": "hsl(var(--bg-card))",
+        "bg-elevated": "hsl(var(--bg-elevated))",
+        border: "hsl(var(--border))",
+        foreground: "hsl(var(--foreground))",
+        muted: { DEFAULT: "hsl(var(--muted))", foreground: "hsl(var(--foreground))" },
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(222 47% 5%)",
+          glow: "hsl(var(--primary-glow))",
+        },
+        success: "hsl(var(--success))",
+        warning: "hsl(var(--warning))",
+        danger: "hsl(var(--danger))",
+        accent: { DEFAULT: "hsl(var(--accent))", foreground: "hsl(222 47% 5%)" },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      fontFamily: {
+        sans: ['Inter', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+        mono: ['"JetBrains Mono"', 'ui-monospace', 'monospace'],
+        heading: ['"JetBrains Mono"', 'ui-monospace', 'monospace'],
+      },
+      boxShadow: {
+        glow: "0 0 20px -4px hsl(var(--primary-glow) / 0.5)",
+        panel: "0 8px 30px -12px hsl(var(--bg) / 0.6)",
+      },
+    },
+  },
+  plugins: [],
+};

package/extensions/dashboard-server/api-contracts/core.ts

@@ -205,6 +205,65 @@ export interface SseRecallInject {
   tokens: number;
 }
 
+/**
+ * SSE event emitted on a recall pass when HyDE was considered (H1). Streamed
+ * via `GET /api/events`. Mirrors the metrics carried up from the recall core's
+ * `HydeInvocationInfo`.
+ */
+export interface SseHydeExecuted {
+  /** Discriminator. Always `'hyde_executed'`. */
+  type: 'hyde_executed';
+  /** ISO 8601 timestamp of the event. */
+  ts: string;
+  /** Session identifier the recall ran in. */
+  sessionId: string;
+  /** True when HyDE ran (hypothetical doc generated + embedded + searched). */
+  ran: boolean;
+  /** True when HyDE was considered but explicitly skipped. */
+  skipped: boolean;
+  /** Human-readable reason: "ran" | "disabled" | "no-llm" | "generation-failed". */
+  reason: string;
+  /** The hypothetical answer document the LLM produced (truncated). */
+  hypotheticalDoc: string;
+  /** ms spent generating + embedding the hypothetical doc (0 when skipped). */
+  generationMs: number;
+  /** Hit count from the raw-query search before fusion. */
+  rawHitCount: number;
+  /** Hit count from the hypothetical-doc search before fusion. */
+  hydeHitCount: number;
+  /** Hit count of the RRF-fused result actually injected. */
+  fusedHitCount: number;
+  /** Lift = fusedHitCount / max(1, rawHitCount). */
+  lift: number;
+}
+
+/**
+ * SSE event emitted per recall pass with the recall-quality metrics (H1).
+ * Streamed via `GET /api/events`.
+ */
+export interface SseRecallMetrics {
+  /** Discriminator. Always `'recall_metrics'`. */
+  type: 'recall_metrics';
+  /** ISO 8601 timestamp of the event. */
+  ts: string;
+  /** Session identifier the recall ran in. */
+  sessionId: string;
+  /** Number of hits injected for the turn. */
+  hitCount: number;
+  /** Weighted composite recall-quality score (0–1). */
+  score: number;
+  /** Whether the recall quality passed its thresholds. */
+  pass: boolean;
+  /** Relevance breakdown (0–1). */
+  relevance: number;
+  /** Coverage breakdown (0–1). */
+  coverage: number;
+  /** Diversity breakdown (0–1). */
+  diversity: number;
+  /** Specificity breakdown (0–1). */
+  specificity: number;
+}
+
 /**
  * SSE event emitted when anchor messages are updated.
  *

package/extensions/dashboard-server/api-contracts/endpoints/registry.ts

@@ -24,6 +24,7 @@ import type {
 	RagSettingsRequest,
 	RagSettingsResponsePost,
 } from "../rag-settings.js";
+import type { RagMetricsResponse } from "../rag-metrics.js";
 import type {
 	TurnsResponse,
 	ConversationTurnsResponse,
@@ -42,6 +43,16 @@ import type {
 	SchemaHealthResponse,
 } from "../maintenance.js";
 import type { CacheStripesResponse } from "../cache-stripes.js";
+import type {
+	WikiIndexResponse,
+	WikiPageResponse,
+	TopicEvolutionResponse,
+	TopicTimelineResponse,
+	RenameTopicRequest,
+	MergeTopicsRequest,
+	SplitTopicRequest,
+	CurationResult,
+} from "../wiki.js";
 import type {
 	GameScoreRow,
 	GameScoresQuery,
@@ -262,6 +273,64 @@ export const ENDPOINTS = {
 		description: "Member memories assigned to a wiki topic (drill-down).",
 	} as const satisfies EndpointDef<"GET", undefined, TopicMemoriesResponse>,
 
+	// ─── Wiki Revival (W2) ───────────────────────────────────────────
+
+	/** GET /api/wiki/index — wiki landing page with resolved labels. */
+	wikiIndex: {
+		method: "GET",
+		path: "/api/wiki/index",
+		description:
+			"Wiki index: auto-categorized topics with resolved (override-aware) labels.",
+	} as const satisfies EndpointDef<"GET", undefined, WikiIndexResponse>,
+
+	/** GET /api/wiki/topic/:topicId — single topic page + provenance. */
+	wikiTopic: {
+		method: "GET",
+		path: "/api/wiki/topic/:topicId",
+		description:
+			"Single wiki topic page: summary, key memories, and memory provenance.",
+	} as const satisfies EndpointDef<"GET", undefined, WikiPageResponse>,
+
+	/** PUT /api/wiki/topic/:topicId/label — rename a topic (user curation). */
+	renameTopic: {
+		method: "PUT",
+		path: "/api/wiki/topic/:topicId/label",
+		description:
+			"Rename a wiki topic (persists a label override; emits wiki_topic_renamed).",
+	} as const satisfies EndpointDef<"PUT", RenameTopicRequest, CurationResult>,
+
+	/** POST /api/wiki/merge — merge one topic into another. */
+	mergeTopics: {
+		method: "POST",
+		path: "/api/wiki/merge",
+		description:
+			"Merge source topic into target (reassigns memories; emits wiki_topics_merged).",
+	} as const satisfies EndpointDef<"POST", MergeTopicsRequest, CurationResult>,
+
+	/** POST /api/wiki/topic/:topicId/split — split listed memories into a new topic. */
+	splitTopic: {
+		method: "POST",
+		path: "/api/wiki/topic/:topicId/split",
+		description:
+			"Split listed member memories into a new topic (emits wiki_topic_split).",
+	} as const satisfies EndpointDef<"POST", SplitTopicRequest, CurationResult>,
+
+	/** GET /api/wiki/topic/:topicId/timeline — per-topic time buckets. */
+	topicTimeline: {
+		method: "GET",
+		path: "/api/wiki/topic/:topicId/timeline",
+		description:
+			"Per-topic memory-assignment timeline buckets for charts.",
+	} as const satisfies EndpointDef<"GET", undefined, TopicTimelineResponse>,
+
+	/** GET /api/wiki/evolution — node/edge D3 evolution graph. */
+	topicEvolution: {
+		method: "GET",
+		path: "/api/wiki/evolution",
+		description:
+			"Topic evolution nodes + edges + time buckets from topic_evolution.",
+	} as const satisfies EndpointDef<"GET", undefined, TopicEvolutionResponse>,
+
 	// ─── S49B Maintenance Tab ─────────────────────────────────────────
 
 	/** GET /api/maintenance — DB stats (table row counts + storage). */
@@ -380,4 +449,14 @@ export const ENDPOINTS = {
 		description:
 			"Update RAG feature flag states by writing _DISABLED env vars to .mega-compact.env.",
 	} as const satisfies EndpointDef<"POST", RagSettingsRequest, RagSettingsResponsePost>,
+
+	// ─── RAG Metrics (Sprint H2) ──────────────────────────────────────
+
+	/** GET /api/rag-metrics — HyDE + recall-quality telemetry aggregates. */
+	ragMetrics: {
+		method: "GET",
+		path: "/api/rag-metrics",
+		description:
+			"HyDE invocation + recall-quality telemetry: flags, totals, recent turns, and daily series.",
+	} as const satisfies EndpointDef<"GET", undefined, RagMetricsResponse>,
 } as const;

package/extensions/dashboard-server/api-contracts/index.ts

@@ -20,6 +20,8 @@ export type {
 	SsePressureLifted,
 	SseCheckpointPersisted,
 	SseRecallInject,
+	SseHydeExecuted,
+	SseRecallMetrics,
 	SseAnchorsUpdated,
 	SseConfigUpdated,
 	SseConfigPreset,
@@ -98,6 +100,8 @@ import type {
 	SsePressureLifted,
 	SseCheckpointPersisted,
 	SseRecallInject,
+	SseHydeExecuted,
+	SseRecallMetrics,
 	SseAnchorsUpdated,
 	SseConfigUpdated,
 	SseConfigPreset,
@@ -107,6 +111,13 @@ import type {
 	SseSessionSample,
 } from "./core.js";
 
+import type {
+	SseWikiRebuilt,
+	SseWikiTopicRenamed,
+	SseWikiTopicsMerged,
+	SseWikiTopicSplit,
+} from "./wiki.js";
+
 // Endpoints registry (Sprint A1)
 export type {
 	VersionResponse,
@@ -124,6 +135,7 @@ export type {
 	PerfPercentile,
 	PerfAverage,
 	PerfLatest,
+	CacheHitSample,
 	PerfCacheHit,
 	PerfDiag,
 	PerfQuery,
@@ -169,12 +181,18 @@ export type SseEvent =
 	| SseCrewPresenceChanged
 	| SseCrewTurnChanged
 	| SseCrewBanditChosen
+	| SseHydeExecuted
+	| SseRecallMetrics
 	| SseGameRitualStart
 	| SseGameRitualStage
 	| SseGameRitualEnd
 	| SseGameModeChanged
 	| SseGameRender
-	| SseSessionSample;
+	| SseSessionSample
+	| SseWikiRebuilt
+	| SseWikiTopicRenamed
+	| SseWikiTopicsMerged
+	| SseWikiTopicSplit;
 
 // S49B — maintenance tab API
 export type {
@@ -233,10 +251,38 @@ export type {
 	CacheStripesResponse,
 } from "./cache-stripes.js";
 
-// RAG Settings — feature flag toggles (B6)
+// RAG Settings — comprehensive adjustable settings (B6)
 export type {
+	SettingState,
+	SettingsResponse,
+	SettingsUpdateRequest,
+	SettingsResponsePost,
 	RagFlagState,
 	RagSettingsResponse,
 	RagSettingsRequest,
 	RagSettingsResponsePost,
 } from "./rag-settings.js";
+
+// RAG metrics — HyDE + recall-quality aggregations (H1/H2)
+export type { RagMetricsResponse } from "./rag-metrics.js";
+
+// W2 — wiki revival: curation + provenance
+export type {
+	WikiIndexEntry,
+	WikiIndexResponse,
+	MemoryProvenance,
+	WikiPageResponse,
+	RenameTopicRequest,
+	MergeTopicsRequest,
+	SplitTopicRequest,
+	TopicTimelineResponse,
+	TopicEvolutionResponse,
+	TopicEvolutionNode,
+	TopicEvolutionEdge,
+	SseWikiRebuilt,
+	SseWikiTopicRenamed,
+	SseWikiTopicsMerged,
+	SseWikiTopicSplit,
+	WikiSseEvent,
+} from "./wiki.js";
+export type { CurationResult, OverrideKind, WikiCurationStore } from "../../../src/wiki/curation.js";

package/extensions/dashboard-server/api-contracts/rag-metrics.ts

@@ -0,0 +1,22 @@
+/**
+ * api-contracts/rag-metrics.ts — GET /api/rag-metrics response + HyDE/recall SSE
+ * event contracts (H1/H2).
+ */
+import type { TurnTelemetryRow, DailyTelemetry } from "../../../src/store/turns/hydeStore.js";
+
+export interface RagMetricsResponse {
+	flags: {
+		hydeEnabled: boolean;
+		recallMetricsEnabled: boolean;
+	};
+	totals: {
+		telemetryTurns: number;
+		hydeRanTurns: number;
+		avgLift: number;
+		avgScore: number | null;
+		avgGenerationMs: number;
+		recentPassRate: number;
+	};
+	recent: TurnTelemetryRow[];
+	daily: DailyTelemetry[];
+}