@remnic/core 1.1.12 → 1.1.14

package/src/reasoning-trace-recall.ts

@@ -0,0 +1,201 @@
+/**
+ * Reasoning-trace recall boost (issue #564 PR 3).
+ *
+ * Pure helpers for:
+ * - detecting whether a user query looks like a problem-solving ask
+ *   ("how do I…", "step by step", etc.)
+ * - boosting stored reasoning_trace memories within a result list when that
+ *   condition matches.
+ *
+ * Callers gate these helpers behind the `recallReasoningTraceBoostEnabled`
+ * config flag (default false); the helpers themselves are also no-ops when
+ * `enabled` is false so they can be safely chained into the recall pipeline.
+ */
+
+/**
+ * Heuristic: does the incoming query read like the user wants a stored
+ * solution chain (reasoning trace)?
+ *
+ * Positive signals:
+ *  - starts with "how do I", "how can I", "how would I", "how to"
+ *  - contains "step by step", "walk me through", "work through"
+ *  - contains "reasoning", "think through", "figure out", "debug"
+ *  - explicitly mentions "trace" or "chain of thought"
+ *
+ * This is intentionally conservative — the boost is OFF by default, so false
+ * negatives are cheap, but false positives would shift retrieval for ordinary
+ * queries on an opt-in install.
+ */
+export function looksLikeProblemSolvingQuery(query: string): boolean {
+  if (typeof query !== "string") return false;
+  const q = query.trim().toLowerCase();
+  if (q.length === 0) return false;
+
+  // Starts-with patterns.
+  const startsWithPatterns = [
+    /^how\s+do\s+i\b/,
+    /^how\s+can\s+i\b/,
+    /^how\s+would\s+i\b/,
+    /^how\s+should\s+i\b/,
+    /^how\s+to\b/,
+    /^what'?s?\s+the\s+best\s+way\s+to\b/,
+    /^can\s+you\s+walk\s+me\s+through\b/,
+    /^walk\s+me\s+through\b/,
+    /^help\s+me\s+debug\b/,
+    /^help\s+me\s+figure\s+out\b/,
+    /^why\s+(does|is|did)\b/,
+  ];
+  for (const re of startsWithPatterns) {
+    if (re.test(q)) return true;
+  }
+
+  // Anywhere-in-string phrases. These mirror the doc-comment's stated
+  // positive signals: broader variants ("work through", "figure out",
+  // "debug this") are included so "how do I debug this" doesn't have to
+  // lean on the `help me debug` starts-with entry alone, and so queries
+  // like "work through the problem" or "figure out why it broke" trigger
+  // the heuristic as the docstring claims.
+  const phrases = [
+    "step by step",
+    "step-by-step",
+    "work through",
+    "walk through",
+    "walk me through",
+    "reason through",
+    "think through",
+    "figure out",
+    "chain of thought",
+    "reasoning trace",
+    "solution chain",
+    "troubleshoot",
+    "debug this",
+    "debug the",
+    " debug ",
+  ];
+  for (const phrase of phrases) {
+    if (q.includes(phrase)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Minimal shape the boost helper needs to read from a recall result. Matches
+ * QmdSearchResult as of issue #564 but kept structural so tests and future
+ * callers don't have to import orchestrator-level types.
+ */
+export interface BoostableResult {
+  path: string;
+  score: number;
+  docid?: string;
+}
+
+/**
+ * Path-based marker for memories that live in the dedicated
+ * reasoning-traces/ subtree. Using a path segment keeps this cheap: no
+ * frontmatter parsing or extra I/O is needed.
+ */
+export function isReasoningTracePath(candidatePath: string): boolean {
+  if (typeof candidatePath !== "string") return false;
+  // Match "/reasoning-traces/" as a full path segment to avoid false
+  // positives like "my-reasoning-traces-notes/".
+  return /(^|[\\/])reasoning-traces([\\/]|$)/.test(candidatePath);
+}
+
+/**
+ * Default additive boost applied to a reasoning_trace candidate when the
+ * current query looks like a problem-solving ask.
+ *
+ * Chosen to be roughly the same magnitude as the existing CATEGORY_BOOSTS
+ * entry for reasoning_trace (0.09 in importance scoring), keeping the signal
+ * visible but not overwhelming stronger lexical/vector matches.
+ */
+export const DEFAULT_REASONING_TRACE_BOOST = 0.15;
+
+export interface ApplyReasoningTraceBoostOptions {
+  enabled: boolean;
+  query: string;
+  boost?: number;
+}
+
+/**
+ * Apply a score boost to results whose path sits under reasoning-traces/
+ * when the query looks like a problem-solving ask. Returns a new array;
+ * the input array is not mutated.
+ *
+ * Ordering policy: the helper walks the results in order, boosts every
+ * matching reasoning trace in place, then promotes each boosted trace
+ * upward PAST any non-boosted neighbor whose score is strictly lower
+ * than the trace's boosted score. Non-matching results keep their
+ * incoming relative order — so reranker-driven path ordering and any
+ * other upstream nudges on non-trace items are preserved. We do NOT
+ * re-sort the full list, which would wipe out rerank priority on
+ * non-trace items (whose numeric scores may have been left stale by the
+ * rerank pass). This matters because MMR runs immediately after and
+ * truncates to a topN window — globally re-sorting would silently drop
+ * reranker-promoted items below the cutoff.
+ *
+ * No-ops (returns a copy of the input unchanged) when:
+ *  - `enabled` is false,
+ *  - `query` is empty / not a problem-solving ask,
+ *  - the result list contains no reasoning-trace paths.
+ *
+ * Note on legacy paths: this helper intentionally only matches paths
+ * under the dedicated `reasoning-traces/` subtree introduced by PR 3.
+ * Historical reasoning_trace memories (if any) written before that
+ * subtree existed were routed to `facts/<date>/` and are NOT
+ * boost-eligible. Operators upgrading across that boundary should run
+ * the migration CLI or rewrite old paths before enabling the boost.
+ */
+export function applyReasoningTraceBoost<R extends BoostableResult>(
+  results: readonly R[],
+  options: ApplyReasoningTraceBoostOptions,
+): R[] {
+  if (!options.enabled) return [...results];
+  if (!Array.isArray(results) || results.length === 0) return [...results];
+  if (!looksLikeProblemSolvingQuery(options.query)) return [...results];
+
+  const boostAmount =
+    typeof options.boost === "number" && Number.isFinite(options.boost) && options.boost >= 0
+      ? options.boost
+      : DEFAULT_REASONING_TRACE_BOOST;
+
+  // Step 1: boost the scores of matching traces, preserving positions.
+  const boosted: R[] = [];
+  let changed = false;
+  for (const r of results) {
+    if (isReasoningTracePath(r.path)) {
+      changed = true;
+      const baseScore = typeof r.score === "number" && Number.isFinite(r.score) ? r.score : 0;
+      boosted.push({ ...r, score: baseScore + boostAmount } as R);
+    } else {
+      boosted.push(r);
+    }
+  }
+  if (!changed) return boosted;
+
+  // Step 2: promote each boosted trace upward past any non-trace neighbor
+  // whose score is strictly lower than the boosted score. Non-trace items
+  // never move past each other, so reranker-driven ordering on non-trace
+  // items is preserved.
+  const out = boosted.slice();
+  for (let i = 0; i < out.length; i++) {
+    if (!isReasoningTracePath(out[i].path)) continue;
+    const trace = out[i];
+    const traceScore =
+      typeof trace.score === "number" && Number.isFinite(trace.score) ? trace.score : 0;
+    let j = i;
+    while (j > 0) {
+      const prev = out[j - 1];
+      if (isReasoningTracePath(prev.path)) break; // don't reorder traces vs each other
+      const prevScore =
+        typeof prev.score === "number" && Number.isFinite(prev.score) ? prev.score : 0;
+      if (prevScore >= traceScore) break;
+      out[j] = prev;
+      j -= 1;
+    }
+    if (j !== i) out[j] = trace;
+  }
+
+  return out;
+}

package/src/reasoning-trace-types.ts

@@ -0,0 +1,235 @@
+/**
+ * Reasoning-trace memory structural types (issue #564).
+ *
+ * Captures stored solution chains / chain-of-thought the user walked through
+ * to solve a problem. Traces have an ordered list of steps, a final answer,
+ * and an optional observed outcome.
+ */
+
+export interface ReasoningTraceStep {
+  /** 1-based ordinal within the trace. */
+  order: number;
+  /** Human-readable description of what happened at this step. */
+  description: string;
+}
+
+export interface ReasoningTraceStructuredData {
+  steps: ReasoningTraceStep[];
+  finalAnswer: string;
+  /** Optional confirmation of how the answer played out in practice. */
+  observedOutcome?: string;
+}
+
+/** Normalize loose extraction JSON into ReasoningTraceStep records. */
+export function normalizeReasoningTraceSteps(raw: unknown): ReasoningTraceStep[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ReasoningTraceStep[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    const s = raw[i];
+    let description = "";
+    let orderRaw: unknown;
+    if (typeof s === "string") {
+      description = s.trim();
+    } else if (s && typeof s === "object") {
+      const o = s as Record<string, unknown>;
+      if (typeof o.description === "string") description = o.description.trim();
+      else if (typeof o.intent === "string") description = o.intent.trim();
+      else if (typeof o.step === "string") description = o.step.trim();
+      else if (typeof o.text === "string") description = o.text.trim();
+      orderRaw = o.order;
+    }
+    if (!description) continue;
+    const order =
+      typeof orderRaw === "number" && Number.isFinite(orderRaw)
+        ? Math.max(1, Math.floor(orderRaw))
+        : i + 1;
+    out.push({ order, description });
+  }
+  return out;
+}
+
+/**
+ * Normalize a loose reasoningTrace object (e.g. coming back from the LLM) to
+ * a strict ReasoningTraceStructuredData shape. Returns null when the data is
+ * clearly incomplete (no steps or no final answer).
+ */
+export function normalizeReasoningTrace(raw: unknown): ReasoningTraceStructuredData | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o = raw as Record<string, unknown>;
+  const steps = normalizeReasoningTraceSteps(o.steps);
+  const finalAnswer =
+    typeof o.finalAnswer === "string"
+      ? o.finalAnswer.trim()
+      : typeof o.final_answer === "string"
+      ? (o.final_answer as string).trim()
+      : "";
+  // Prompts describe reasoning_trace as requiring ≥2 ordered steps + a final
+  // answer. Rejecting one-step payloads here keeps the category semantically
+  // distinct from ordinary `decision` facts and prevents malformed traces
+  // from sneaking through loose local/direct extraction JSON.
+  if (steps.length < 2 || finalAnswer.length === 0) return null;
+  const observedRaw =
+    typeof o.observedOutcome === "string"
+      ? o.observedOutcome
+      : typeof o.observed_outcome === "string"
+      ? (o.observed_outcome as string)
+      : undefined;
+  const observedOutcome = observedRaw?.trim();
+  return {
+    steps,
+    finalAnswer,
+    observedOutcome: observedOutcome && observedOutcome.length > 0 ? observedOutcome : undefined,
+  };
+}
+
+/**
+ * Serialize a normalized reasoning trace into a human-readable markdown body.
+ * Output shape mirrors the procedure body format: ## Step N sections followed
+ * by final answer and optional observed outcome.
+ */
+export function buildReasoningTraceMarkdownBody(trace: ReasoningTraceStructuredData): string {
+  const sorted = [...trace.steps].sort((a, b) => a.order - b.order);
+  const lines: string[] = [];
+  for (const step of sorted) {
+    const n = Number.isFinite(step.order) ? Math.max(1, Math.floor(step.order)) : 1;
+    lines.push(`## Step ${n}`);
+    lines.push("");
+    lines.push(step.description.trim());
+    lines.push("");
+  }
+  lines.push("## Final Answer");
+  lines.push("");
+  lines.push(trace.finalAnswer.trim());
+  lines.push("");
+  if (trace.observedOutcome && trace.observedOutcome.trim().length > 0) {
+    lines.push("## Observed Outcome");
+    lines.push("");
+    lines.push(trace.observedOutcome.trim());
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+/**
+ * Combine a short title with the structured trace body. The title becomes the
+ * one-line content of the stored memory, and the full body is appended below.
+ */
+export function buildReasoningTracePersistBody(
+  title: string,
+  trace: ReasoningTraceStructuredData,
+): string {
+  const head = typeof title === "string" ? title.trim() : "";
+  const body = buildReasoningTraceMarkdownBody(trace);
+  if (!head) return body;
+  return `${head}\n\n${body}`.trimEnd() + "\n";
+}
+
+const STEP_HEADER_RE = /^##\s+Step\s+(\d+)\s*$/im;
+const FINAL_HEADER_RE = /^##\s+Final Answer\s*$/im;
+const OBSERVED_HEADER_RE = /^##\s+Observed Outcome\s*$/im;
+
+/**
+ * Best-effort parse of a reasoning-trace markdown body back into structured
+ * data. Returns null when the document does not look like a reasoning trace.
+ */
+export function parseReasoningTraceFromBody(content: string): ReasoningTraceStructuredData | null {
+  const text = content.replace(/\r\n/g, "\n").trim();
+  if (!text) return null;
+  const stepMatches = [...text.matchAll(new RegExp(STEP_HEADER_RE.source, "gim"))];
+  const finalMatch = FINAL_HEADER_RE.exec(text);
+  if (stepMatches.length === 0 || !finalMatch) return null;
+
+  const observedMatch = OBSERVED_HEADER_RE.exec(text);
+
+  const steps: ReasoningTraceStep[] = [];
+  for (let i = 0; i < stepMatches.length; i++) {
+    const m = stepMatches[i];
+    const order = Number.parseInt(m[1] ?? String(i + 1), 10);
+    const start = (m.index ?? 0) + m[0].length;
+    const nextStepStart =
+      i + 1 < stepMatches.length ? stepMatches[i + 1].index ?? text.length : text.length;
+    const end = Math.min(nextStepStart, finalMatch.index ?? text.length);
+    const block = text.slice(start, end).trim();
+    const description = block.split("\n").map((l) => l.trim()).filter((l) => l.length > 0).join(" ");
+    if (!description) continue;
+    steps.push({
+      order: Number.isFinite(order) ? order : i + 1,
+      description,
+    });
+  }
+
+  // Honor the >=2 ordered-steps invariant enforced everywhere else in the
+  // pipeline (prompts, normalizer, schema). A single-step manually-edited
+  // or corrupt file should not round-trip back in as a reasoning_trace.
+  if (steps.length < 2) return null;
+
+  const finalStart = (finalMatch.index ?? 0) + finalMatch[0].length;
+  const finalEnd = observedMatch?.index ?? text.length;
+  const finalAnswer = text
+    .slice(finalStart, finalEnd)
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .join(" ")
+    .trim();
+  if (!finalAnswer) return null;
+
+  let observedOutcome: string | undefined;
+  if (observedMatch) {
+    const obsStart = (observedMatch.index ?? 0) + observedMatch[0].length;
+    const raw = text
+      .slice(obsStart)
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+      .join(" ")
+      .trim();
+    if (raw) observedOutcome = raw;
+  }
+
+  return { steps, finalAnswer, observedOutcome };
+}
+
+/**
+ * Heuristic detector for whether a user message contains a chain-of-thought /
+ * solution trace that should be extracted. This is intentionally conservative:
+ * we require at least two explicitly-ordered steps and some form of final
+ * answer / resolution. Used by the extraction pipeline to decide whether to
+ * even consider emitting a reasoning_trace fact, so false positives are more
+ * costly than false negatives.
+ */
+export function looksLikeReasoningTrace(message: string): boolean {
+  if (typeof message !== "string") return false;
+  const text = message.trim();
+  if (text.length < 80) return false;
+
+  // Count lines that carry at least one step marker, not the total number of
+  // marker matches. Summing across multiple regexes can let a single line
+  // contribute two "steps" (e.g. "Step 1: First,…" matches both patterns),
+  // which weakens the "false positives > false negatives" bias. Per-line
+  // counting keeps the gate symmetric with real step structure.
+  const stepMarkerRes = [
+    /\bstep\s+\d+\s*[:.\-]/i,
+    /^\s*\d+[.)]\s+\S/,
+    /^\s*(first|second|third|fourth|finally|then|next)\b[,:]/i,
+  ];
+  const lines = text.split(/\r?\n/);
+  let stepCount = 0;
+  for (const line of lines) {
+    if (stepMarkerRes.some((re) => re.test(line))) {
+      stepCount += 1;
+      if (stepCount >= 2) break;
+    }
+  }
+  if (stepCount < 2) return false;
+
+  // Final-answer / resolution marker. Split into two checks so the trailing
+  // `\b` on the word-final alternatives doesn't accidentally require a word
+  // character after `answer:` / `result:` (both end in a non-word `:`).
+  const wordFinalMarker =
+    /\b(final answer|so the answer|therefore|conclusion|in the end|ended up|picked|chose)\b/i;
+  const colonMarker = /\b(answer:|result:)/i;
+  if (!wordFinalMarker.test(text) && !colonMarker.test(text)) return false;
+
+  return true;
+}

package/src/recall-audit-anomaly.test.ts

@@ -0,0 +1,246 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { RecallAuditEntry } from "./recall-audit.js";
+import {
+  DEFAULT_ANOMALY_DETECTOR_CONFIG,
+  detectRecallAnomalies,
+  normalizeQueryText,
+} from "./recall-audit-anomaly.js";
+
+function makeEntry(
+  overrides: Partial<RecallAuditEntry> & { ts: string },
+): RecallAuditEntry {
+  return {
+    ts: overrides.ts,
+    sessionKey: overrides.sessionKey ?? "session-a",
+    agentId: overrides.agentId ?? "agent-a",
+    trigger: overrides.trigger ?? "test",
+    queryText: overrides.queryText ?? "hello",
+    candidateMemoryIds: overrides.candidateMemoryIds ?? [],
+    summary: overrides.summary ?? null,
+    injectedChars: overrides.injectedChars ?? 0,
+    toggleState: overrides.toggleState ?? "enabled",
+    latencyMs: overrides.latencyMs,
+    plannerMode: overrides.plannerMode,
+    requestedMode: overrides.requestedMode,
+    fallbackUsed: overrides.fallbackUsed,
+  };
+}
+
+function tsAt(epochMs: number): string {
+  return new Date(epochMs).toISOString();
+}
+
+test("normalizeQueryText lowercases, collapses whitespace, trims", () => {
+  assert.equal(normalizeQueryText("  Hello\tWorld\n"), "hello world");
+  assert.equal(normalizeQueryText(""), "");
+  assert.equal(normalizeQueryText("ALREADY  SPACED"), "already spaced");
+});
+
+test("disabled detector returns zero flags but still reports window count", () => {
+  const entries = [
+    makeEntry({ ts: tsAt(1_000), queryText: "a" }),
+    makeEntry({ ts: tsAt(2_000), queryText: "a" }),
+  ];
+  const result = detectRecallAnomalies({
+    entries,
+    now: 10_000,
+    config: { enabled: false, windowMs: 60_000, repeatQueryLimit: 1 },
+  });
+  assert.equal(result.flags.length, 0);
+  assert.equal(result.windowEntryCount, 2);
+});
+
+test("repeat-query flag fires on bursts of the same normalized query", () => {
+  const entries: RecallAuditEntry[] = [];
+  for (let i = 0; i < 10; i++) {
+    entries.push(
+      makeEntry({ ts: tsAt(1_000 + i * 100), queryText: "ALEX" }),
+    );
+  }
+  const result = detectRecallAnomalies({
+    entries,
+    now: 5_000,
+    config: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 5,
+      namespaceWalkLimit: 100,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  const repeat = result.flags.find((f) => f.kind === "repeat-query");
+  assert.ok(repeat, "repeat-query flag must fire");
+  assert.equal(repeat.signal, "alex");
+  assert.equal(repeat.entryIndices.length, 10);
+});
+
+test("namespace-walk fires when candidate IDs span > namespaceWalkLimit namespaces", () => {
+  const entries = [
+    makeEntry({
+      ts: tsAt(1_000),
+      candidateMemoryIds: ["victim/mem-1", "other/mem-2"],
+    }),
+    makeEntry({
+      ts: tsAt(2_000),
+      candidateMemoryIds: ["third/mem-3", "fourth/mem-4"],
+    }),
+  ];
+  const result = detectRecallAnomalies({
+    entries,
+    now: 10_000,
+    config: {
+      enabled: true,
+      windowMs: 60_000,
+      namespaceWalkLimit: 3,
+      repeatQueryLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  const walk = result.flags.find((f) => f.kind === "namespace-walk");
+  assert.ok(walk, "namespace-walk flag must fire");
+  assert.equal(walk.severity, "alert");
+  assert.equal(walk.signal, 4);
+});
+
+test("high-cardinality-return fires on a single huge response", () => {
+  const bigList = Array.from({ length: 120 }, (_, i) => `victim/mem-${i}`);
+  const entries = [
+    makeEntry({
+      ts: tsAt(1_000),
+      queryText: "dump",
+      candidateMemoryIds: bigList,
+    }),
+  ];
+  const result = detectRecallAnomalies({
+    entries,
+    now: 5_000,
+    config: {
+      enabled: true,
+      windowMs: 60_000,
+      highCardinalityReturnLimit: 100,
+      repeatQueryLimit: 1_000,
+      namespaceWalkLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  const hc = result.flags.find((f) => f.kind === "high-cardinality-return");
+  assert.ok(hc, "high-cardinality-return must fire");
+  assert.equal(hc.signal, 120);
+});
+
+test("rapid-fire fires on too many entries in the window", () => {
+  const entries: RecallAuditEntry[] = [];
+  for (let i = 0; i < 40; i++) {
+    entries.push(makeEntry({ ts: tsAt(1_000 + i), queryText: `q-${i}` }));
+  }
+  const result = detectRecallAnomalies({
+    entries,
+    now: 5_000,
+    config: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 1_000,
+      namespaceWalkLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 30,
+    },
+  });
+  const rf = result.flags.find((f) => f.kind === "rapid-fire");
+  assert.ok(rf, "rapid-fire flag must fire");
+  assert.equal(rf.signal, 40);
+});
+
+test("entries outside the window are ignored", () => {
+  const entries: RecallAuditEntry[] = [];
+  // 20 old entries (outside window), 2 new entries (inside).
+  for (let i = 0; i < 20; i++) {
+    entries.push(makeEntry({ ts: tsAt(0 + i), queryText: "old" }));
+  }
+  entries.push(makeEntry({ ts: tsAt(10_000), queryText: "new" }));
+  entries.push(makeEntry({ ts: tsAt(11_000), queryText: "new" }));
+  const result = detectRecallAnomalies({
+    entries,
+    now: 12_000,
+    config: {
+      enabled: true,
+      windowMs: 5_000, // <- covers 7_000..12_000 only
+      repeatQueryLimit: 1,
+      namespaceWalkLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  assert.equal(result.windowEntryCount, 2);
+  // The repeat-query flag fires on "new" (2 repeats > limit 1), not on "old".
+  const flag = result.flags.find((f) => f.kind === "repeat-query");
+  assert.ok(flag);
+  assert.equal(flag.signal, "new");
+});
+
+test("invalid ts entries are skipped silently", () => {
+  const entries = [
+    makeEntry({ ts: "not-a-date", queryText: "a" }),
+    makeEntry({ ts: tsAt(1_000), queryText: "a" }),
+  ];
+  const result = detectRecallAnomalies({
+    entries,
+    now: 5_000,
+    config: { ...DEFAULT_ANOMALY_DETECTOR_CONFIG, enabled: true },
+  });
+  assert.equal(result.windowEntryCount, 1);
+});
+
+test("flags are sorted by severity then kind for deterministic output", () => {
+  const entries: RecallAuditEntry[] = [];
+  // Trigger alert (namespace-walk) + warn (repeat-query + rapid-fire).
+  for (let i = 0; i < 10; i++) {
+    entries.push(
+      makeEntry({
+        ts: tsAt(1_000 + i),
+        queryText: "same",
+        candidateMemoryIds: [`ns-${i}/mem`],
+      }),
+    );
+  }
+  const result = detectRecallAnomalies({
+    entries,
+    now: 5_000,
+    config: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 5,
+      namespaceWalkLimit: 3,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 5,
+    },
+  });
+  assert.ok(result.flags.length >= 2);
+  // alert comes before warn.
+  const severities = result.flags.map((f) => f.severity);
+  const firstWarn = severities.indexOf("warn");
+  const lastAlert = severities.lastIndexOf("alert");
+  if (firstWarn >= 0 && lastAlert >= 0) {
+    assert.ok(lastAlert < firstWarn, "alerts must precede warns");
+  }
+});
+
+test("invalid config values are replaced by defaults", () => {
+  const entries = [makeEntry({ ts: tsAt(1_000) })];
+  const result = detectRecallAnomalies({
+    entries,
+    now: 2_000,
+    config: {
+      enabled: true,
+      windowMs: Number.NaN,
+      repeatQueryLimit: -1,
+      namespaceWalkLimit: 0,
+      highCardinalityReturnLimit: Number.POSITIVE_INFINITY,
+      rapidFireLimit: Number.NaN,
+    },
+  });
+  assert.equal(result.windowMs, DEFAULT_ANOMALY_DETECTOR_CONFIG.windowMs);
+});