Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
54.9 KB
Raw Blame
/**
 * Bounded, fail-closed, audited prompt-time recall (theme A, t_2ce46130).
 *
 * The pure decision core behind the opt-in UserPromptSubmit recall-inject
 * hook. Given a user prompt and a retriever, it decides whether to inject a
 * small bounded brief of relevance-matched vault notes, to abstain (the
 * prompt is empty, nothing matched, or the top match is below the
 * confidence floor), or to report an error (the retriever threw or blew the
 * fixed time budget). Every outcome is an EXPLICIT, audit-worthy decision -
 * an abstain is a deliberate, recorded choice, never a silent fallback.
 *
 * Deliberately I/O-free and retriever-agnostic: the caller supplies a
 * {@link RecallRetriever}, so the decision logic (caps, floor, time budget,
 * brief rendering) is unit-testable without a vault. {@link
 * defaultRecallRetriever} wires the existing cross-vault search (which
 * already consults every {@link RecallSource}); this module adds NO new
 * retriever. The brief's orientation line reuses {@link deriveRecallHint}
 * over {@link RecallHintInput}.
 */

import { deriveRecallHint, type RecallHintInput } from "../search/recall-hint.ts";
import { searchAcrossVaults } from "../search/cross-vault.ts";
import type { SurfacingGateReason } from "../search/surfacing-gate.ts";
import {
  computeSurfacingKey,
  SURFACING_ADMISSION_FLOORS,
  type SurfacingKeyDecision,
} from "../search/surfacing-key.ts";
import { RECALL_CHANNEL } from "./recall-telemetry.ts";
import type { RetrievalDegradationCode } from "../search/retrieval-trail.ts";
import type { RecallSource } from "./portability/recall-sources.ts";
import { LOCAL_ORIGIN } from "./portability/origins.ts";
import { fenceUntrustedContent, neutralizeSingleLine } from "./untrusted-source.ts";
import { budgetCutLine } from "../agent-context/budget-line.ts";
import { RECALL_INJECT_ANY_MIN, RECALL_INJECT_NOTE_MIN } from "../decision-model/questions.ts";
import { estimateTokens } from "./text/tokenizer.ts";
import type { RecallSliceSpec } from "./types.ts";

/** `origin` label stamped on the recall brief's untrusted-content fence. */
const RECALL_FENCE_ORIGIN = "recall-inject";

/** Hard cap on notes carried in a single brief. */
export const RECALL_INJECT_MAX_NOTES = 4;

/** Hard cap on the rendered brief size, in characters. */
export const RECALL_INJECT_MAX_CHARS = 900;

/** Fixed wall-clock budget for the retrieval step, in milliseconds. */
export const RECALL_INJECT_TIME_BUDGET_MS = 2_500;

/**
 * Match-quality floor ([0,1]) below which the retrieved material is too
 * weak to be worth injecting, so the hook abstains.
 *
 * Compared against {@link RecallResultSet.idfWeightedCoverage} - the share
 * of the prompt's IDF mass the retrieved notes actually cover - and NOT
 * against a result score. A score cannot carry a floor here: the keyword
 * lane is min-max normalised within the candidate set, so whenever that
 * lane is non-empty the top row's score sits at or above the configured
 * `keywordWeight` (`DEFAULT_KEYWORD_WEIGHT`, 0.6; 0.65 measured on a
 * freshly written keyword-only vault) no matter how well it matched, and
 * the bottom row's at zero no matter how well IT matched.
 * Against that number this constant measured which rows the filter stack
 * had removed - it abstained hardest exactly when a visibility or owner
 * scope had just taken the pool's best row, which is the one moment the
 * survivors were still a genuine match.
 *
 * The value is unchanged at 0.35 because it is the quantity that was
 * wrong, not the bound: a brief is worth injecting once the notes cover
 * about a third of what was asked, which sits below
 * `COMPLETENESS_PARTIAL_THRESHOLD` (0.4) - this gate filters noise, it
 * does not demand a complete retrieval.
 *
 * Owned by `SURFACING_ADMISSION_FLOORS.hook` (`surfacing-key.ts`), the
 * shared calculator's hook member, so the gate's diagnostic grading and
 * this floor cannot drift apart; this export keeps the name and value
 * every caller and config test pins.
 */
export const RECALL_INJECT_CONFIDENCE_FLOOR = SURFACING_ADMISSION_FLOORS.hook;

/** One relevance-matched note, narrowed to exactly what the brief needs. */
export interface RecallCandidate {
  readonly path: string;
  readonly title: string | null;
  /** Normalized recall score in [0,1]. */
  readonly score: number;
  readonly searchType: string;
  readonly startLine: number;
  readonly endLine: number;
  /** Cross-vault origin label (a {@link RecallSource} alias), when present. */
  readonly origin?: RecallSource["alias"];
  /**
   * The matched chunk's text. Never rendered into the brief; read only by
   * the optional decision-model filter, which sends it (after the privacy
   * rules) when the `recall_inject` use is not `off`.
   */
  readonly content?: string;
}

/** A retriever's returned candidates plus the ranked pool they came from. */
export interface RecallResultSet {
  readonly candidates: ReadonlyArray<RecallCandidate>;
  readonly total: number;
  /**
   * Absolute match quality of this retrieval in `[0,1]`: the share of the
   * query's IDF mass the candidates cover
   * (`SearchOutcome.idfWeightedCoverage`). Required, so a retriever cannot
   * leave the floor with nothing to read and no consumer can fall back to
   * a rank position.
   *
   * `null` when the retrieval had no IDF mass to weigh - the prompt
   * carried no word characters, or the corpus is empty. Nullable rather
   * than optional for the same reason: an absent field would be a
   * retriever that forgot to report, and this is a retriever reporting
   * that there is nothing to report.
   */
  readonly idfWeightedCoverage: number | null;
  /**
   * Why the retrieval narrowed, as the search trail's codes. Absent or
   * empty when nothing did. A hook resolves to remote reach, so a gated
   * query embed (`semantic-cost-unpriced`) lands here instead of being
   * dropped with the rest of the trail.
   */
  readonly degraded?: ReadonlyArray<RetrievalDegradationCode>;
}

/** Relevance retriever: maps a query to a candidate set. */
export type RecallRetriever = (query: string) => Promise<RecallResultSet>;

/** What one operator-declared slice narrows the default retrieval to. */
export interface RecallRetrieverFilter {
  readonly limit?: number;
  /** Vault-relative path prefix. */
  readonly pathPrefix?: string;
  /** Frontmatter `type` values; empty means no class filter. */
  readonly types?: ReadonlyArray<string>;
}

/** What one slice did in a sliced decision; names and counts only. */
export interface RecallSliceOutcome {
  readonly name: string;
  /**
   * `inject` means the slice's material cleared its floor and was not
   * already shown; `notes` can still be 0 when the global caps left it no
   * room. Any other value is the reason the slice was omitted.
   */
  readonly outcome: "inject" | RecallAbstainReason;
  readonly notes: number;
}

export interface RecallInjectOptions {
  readonly maxNotes?: number;
  readonly maxChars?: number;
  readonly timeBudgetMs?: number;
  readonly confidenceFloor?: number;
  /**
   * The optional decision-model filter (issue #213, Part 9). Absent (the
   * default, and whenever the `recall_inject` use is `off`) leaves every
   * decision exactly as it was. Consulted only on an `inject` decision,
   * inside what is left of {@link timeBudgetMs}.
   */
  readonly decisionFilter?: RecallInjectFilter;
  /**
   * The longest the decision filter may still wait, read when it is
   * consulted: the hook passes what is left of half its process ceiling
   * (`decisionWaitMs`), so a hung provider gives way while the brief can
   * still be emitted. The filter waits the smaller of this and what is
   * left of {@link timeBudgetMs}; absent, only the time budget bounds it.
   */
  readonly decisionWaitLeftMs?: () => number;
  /**
   * Notes this session was already shown, as {@link recallInjectNoteKey} values
   * (origin, path and line span). Absent or empty filters nothing. Applied
   * after the floor check, so the set never moves a floor verdict.
   */
  readonly alreadyInjected?: ReadonlySet<string>;
  /**
   * Vault-relative paths the SessionStart digest actually emitted. Matched
   * on the path alone, any span, because the digest delivers whole notes,
   * and only for candidates from the active vault, the one the digest reads.
   */
  readonly activeDigestPaths?: ReadonlySet<string>;
  /**
   * Operator-declared slices, in declared order. Used only together with
   * {@link sliceRetriever}; absent or empty takes the single implicit
   * relevance slice through the `retriever` argument, byte for byte.
   */
  readonly slices?: ReadonlyArray<RecallSliceSpec>;
  /** Builds the retriever for one slice, asked for at most `limit` notes. */
  readonly sliceRetriever?: (slice: RecallSliceSpec, limit: number) => RecallRetriever;
  /** Clock for the time budget (tests). */
  readonly now?: () => number;
}

/** The two modes in which the decision-model filter runs at all. */
export type RecallInjectFilterMode = "shadow" | "enforce";

/** What the filter is asked: the prompt and the notes the brief carries. */
export interface RecallInjectFilterInput {
  readonly query: string;
  /** The notes actually rendered into today's brief, in brief order. */
  readonly notes: ReadonlyArray<RecallCandidate>;
  /**
   * What is left of the retrieval time budget. The filter spends at most
   * `min(decision_model_hook_budget_ms, remainingMs)`; the core also cuts
   * it off at `remainingMs`, so the total budget never grows.
   */
  readonly remainingMs: number;
}

/** The filter's answer for one brief; never a thrown error. */
export type RecallInjectFilterVerdict =
  /** Not active after all (e.g. no provider): no request, no field. */
  | { readonly status: "off" }
  /** Nothing could be sent (every note private or unresolvable). */
  | { readonly status: "not_sent"; readonly mode: RecallInjectFilterMode }
  | {
      readonly status: "ok";
      readonly mode: RecallInjectFilterMode;
      readonly latencyMs: number;
      /** `helps_<k>` per note in brief order; null when not sent or invalid. */
      readonly helps: ReadonlyArray<number | null>;
      /** Whether each note was sent at all. */
      readonly sent: ReadonlyArray<boolean>;
      /** `inject_any`; null when invalid. */
      readonly injectAny: number | null;
    }
  | {
      readonly status: "degraded";
      readonly mode: RecallInjectFilterMode;
      /** A decision-model degrade reason (closed set), for the local audit only. */
      readonly reason: string;
      readonly latencyMs: number;
    };

export interface RecallInjectFilter {
  readonly mode: RecallInjectFilterMode;
  run(input: RecallInjectFilterInput): Promise<RecallInjectFilterVerdict>;
}

/**
 * What the decision-model filter did to one decision. Numbers and closed
 * classifications only; never prompt or note text.
 */
export interface RecallInjectDecisionModelInfo {
  readonly mode: RecallInjectFilterMode;
  /** `ok` (an answer arrived), `not_sent`, or `degraded`. */
  readonly outcome: "ok" | "not_sent" | "degraded";
  /** The degrade reason; carried to the local audit line only. */
  readonly degradeReason?: string;
  /** Time the filter added to this prompt, in milliseconds. */
  readonly latencyMs: number;
  /** Notes removed from the brief (in shadow: notes enforce would remove). */
  readonly notesDropped: number;
  /** Whether the brief was withheld (in shadow: whether enforce would withhold it). */
  readonly abstained: boolean;
  /** Estimated brief tokens before and after enforcement; enforce only, when it changed. */
  readonly tokensBefore?: number;
  readonly tokensAfter?: number;
  /** Brief characters removed in enforce; 0 otherwise. */
  readonly charsRemoved: number;
}

/**
 * Why the hook injected nothing.
 *
 * `unmeasurable_quality` is the fourth member and the one that is not a
 * judgement about the material: the floor reads a match quality, and for
 * a prompt with no IDF mass to weigh there is no quality to compare. The
 * hook abstains, because injecting on a measurement that did not happen
 * is the false fire the floor exists to prevent - but the reason says
 * which of the two it was, since the repairs differ (a weak match is a
 * corpus problem, an unmeasurable one is a prompt or an empty index).
 */
export type RecallAbstainReason =
  | "empty_prompt"
  | "no_matches"
  | "below_floor"
  | "unmeasurable_quality"
  /**
   * The optional decision-model filter, in enforce, judged that no note
   * would help (issue #213, Part 9). Only ever follows what would have
   * been an `inject`.
   */
  | "decision_model_abstain"
  /**
   * Every candidate that cleared the floor was already shown in this
   * session, by an earlier brief or by the SessionStart digest.
   */
  | "all_already_injected"
  /** Slices were declared and none of them placed a note in the brief. */
  | "all_slices_abstained"
  /**
   * The structural gate (`evaluateSurfacingGate`) refused before any
   * retrieval ran - the prompt is a verbatim repeat of its predecessor, a
   * slash command, a shell command, or empty, and the gate's own reason
   * rides `structuralReason`. `decideRecallInject` itself never returns
   * this: in production the transports run the gate AHEAD of this core,
   * and a caller that reproduces that composition (the bench's
   * proactive-recall arm) persists the refusal as this member, so an
   * abstention always names the layer that refused it.
   */
  | "structural";

/**
 * Why an attempt failed, as a closed vocabulary rather than as prose.
 *
 * The error decision used to carry the retriever's RAW `Error.message`,
 * and the hook copied it onto the recall-telemetry record - a synced
 * continuity payload that `brain_recall_telemetry` returns verbatim to a
 * model. A SQLite, store or config failure names the index file or the
 * config path, and the shared redactor strips secret-shaped tokens, not
 * paths. Every other producer in this tree already refuses exactly that:
 * the trigram lane classifies its fault to a code, cross-vault replaces
 * a failing origin's message with one, and the semantic phase carries a
 * category.
 *
 * Three members because three things can fail, and each has a different
 * repair: the corpus is too slow, the retriever is broken, or the host
 * killed the hook before either could answer. The message itself is not
 * discarded - it rides on {@link RecallInjectDecision.detail}, which
 * only the local audit file is allowed to read.
 */
export const RECALL_INJECT_FAULT = Object.freeze({
  /** Retrieval outlived {@link RECALL_INJECT_TIME_BUDGET_MS}. */
  timeout: "timeout",
  /** The retriever threw; `detail` carries what it said. */
  retrieverFailed: "retriever_failed",
  /** The hook's own self-watchdog fired before a decision was reached. */
  hookCeilingExceeded: "hook_ceiling_exceeded",
} as const);

/** Closed union over {@link RECALL_INJECT_FAULT}. */
export type RecallInjectFault = (typeof RECALL_INJECT_FAULT)[keyof typeof RECALL_INJECT_FAULT];

/** Membership list; every surface renders its vocabulary from this array. */
export const RECALL_INJECT_FAULTS: ReadonlyArray<RecallInjectFault> = Object.freeze([
  RECALL_INJECT_FAULT.timeout,
  RECALL_INJECT_FAULT.retrieverFailed,
  RECALL_INJECT_FAULT.hookCeilingExceeded,
]);

/** Narrow a string read back off disk or across a tool boundary. */
export function isRecallInjectFault(value: unknown): value is RecallInjectFault {
  return (
    typeof value === "string" && (RECALL_INJECT_FAULTS as ReadonlyArray<string>).includes(value)
  );
}

export type RecallInjectDecision =
  | {
      readonly kind: "inject";
      readonly brief: string;
      readonly noteCount: number;
      readonly topScore: number;
      /**
       * The quantity the floor was compared against; see the floor's
       * docblock. Null on an inject admitted without a comparable
       * measurement (an explicit request or an unmeasurable report):
       * the graded admission carried it as a null key.
       */
      readonly matchQuality: number | null;
      /**
       * Exactly the notes rendered into {@link brief}, in brief order:
       * after the char-budget fit and after the decision-model filter. The
       * hook records these, so a note that was cut is never suppressed
       * without having been shown.
       */
      readonly injectedNotes: ReadonlyArray<RecallInjectedNote>;
      /** Per-slice outcomes, in declared order; present only when slices ran. */
      readonly slices?: ReadonlyArray<RecallSliceOutcome>;
      /** Present only when the decision-model filter ran (use not `off`). */
      readonly decisionModel?: RecallInjectDecisionModelInfo;
      /** See {@link RecallResultSet.degraded}; present only when non-empty. */
      readonly retrievalDegraded?: ReadonlyArray<RetrievalDegradationCode>;
    }
  | {
      readonly kind: "abstain";
      readonly reason: RecallAbstainReason;
      /**
       * Present only on a `structural` abstain: the gate's own closed
       * reason (`duplicate`, `slash_command`, `shell_command`, `empty`),
       * carried beside the carrier member so the abstention says both
       * which layer refused and why.
       */
      readonly structuralReason?: SurfacingGateReason;
      readonly topScore: number;
      /**
       * The quantity the floor was compared against; see the floor's
       * docblock. `null` on the abstains where there was no comparison to
       * make - `unmeasurable_quality` always, and the earlier
       * short-circuits when the retrieval could not weigh the prompt.
       */
      readonly matchQuality: number | null;
      /** Per-slice outcomes, in declared order; present only when slices ran. */
      readonly slices?: ReadonlyArray<RecallSliceOutcome>;
      /** Present only on a `decision_model_abstain`. */
      readonly decisionModel?: RecallInjectDecisionModelInfo;
      /** See {@link RecallResultSet.degraded}; present only when non-empty. */
      readonly retrievalDegraded?: ReadonlyArray<RetrievalDegradationCode>;
    }
  | {
      readonly kind: "error";
      readonly fault: RecallInjectFault;
      /**
       * The originating message, for the LOCAL audit file only. Named
       * `detail` rather than `reason` so the split is structural: a
       * consumer reaching for a classification cannot reach this by
       * accident, which is how the raw message got onto a synced payload
       * in the first place.
       */
      readonly detail?: string;
      /**
       * See {@link RecallResultSet.degraded}; present only when non-empty.
       * A slice that answered before another failed still reports here.
       */
      readonly retrievalDegraded?: ReadonlyArray<RetrievalDegradationCode>;
    };

/** The identity of one rendered brief bullet. */
export interface RecallInjectedNote {
  readonly path: string;
  readonly origin?: string;
  readonly startLine: number;
  readonly endLine: number;
}

/**
 * The per-session dedupe key of one note: origin label (`local` for the
 * active vault through the default retriever; empty when a retriever sets
 * no origin), vault-relative path and line span. The one source of
 * the key: the hook records these values and this core filters on them.
 */
export function recallInjectNoteKey(note: RecallInjectedNote): string {
  return `${note.origin ?? ""}:${note.path}#L${note.startLine}-L${note.endLine}`;
}

/** Narrow rendered candidates to the identity the ledger records. */
function injectedNotesOf(notes: ReadonlyArray<RecallCandidate>): ReadonlyArray<RecallInjectedNote> {
  return Object.freeze(
    notes.map((n) =>
      Object.freeze({
        path: n.path,
        ...(n.origin !== undefined ? { origin: n.origin } : {}),
        startLine: n.startLine,
        endLine: n.endLine,
      }),
    ),
  );
}

/**
 * Drop candidates this session was already shown. Runs after the floor
 * check and before the `maxNotes` slice; with neither set given it returns
 * the input unchanged.
 */
function withoutDelivered(
  ranked: ReadonlyArray<RecallCandidate>,
  options: RecallInjectOptions,
): ReadonlyArray<RecallCandidate> {
  const injected = options.alreadyInjected;
  const digest = options.activeDigestPaths;
  if (
    (injected === undefined || injected.size === 0) &&
    (digest === undefined || digest.size === 0)
  ) {
    return ranked;
  }
  return ranked.filter(
    (c) =>
      !(injected?.has(recallInjectNoteKey(c)) ?? false) &&
      !(fromActiveVault(c) && (digest?.has(c.path) ?? false)),
  );
}

/**
 * Whether a candidate comes from the active vault. The SessionStart digest
 * delivers the active vault's notes only, so a profile or recall source
 * note on the same vault-relative path was never shown and stays eligible.
 */
function fromActiveVault(candidate: RecallCandidate): boolean {
  return candidate.origin === undefined || candidate.origin === LOCAL_ORIGIN;
}

/** Typed error for a retrieval that exceeded the fixed time budget. */
export class RecallInjectTimeoutError extends Error {
  constructor(public readonly budgetMs: number) {
    super(`recall retrieval exceeded the ${budgetMs}ms time budget`);
    this.name = "RecallInjectTimeoutError";
  }
}

/**
 * Decide whether to inject, abstain, or error for one prompt. Never throws:
 * a retriever failure or timeout is caught and surfaced as an explicit
 * `error` decision so the hook can audit and inject nothing.
 */
export async function decideRecallInject(
  prompt: string,
  retriever: RecallRetriever,
  options: RecallInjectOptions = {},
): Promise<RecallInjectDecision> {
  // Every retrieval this decision makes reports through one recorder, so
  // the codes reach the decision on every return path below without each
  // path having to remember them. Order is first-seen, each code once.
  const seen: RetrievalDegradationCode[] = [];
  const recorded =
    (inner: RecallRetriever): RecallRetriever =>
    async (query) => {
      const set = await inner(query);
      for (const code of set.degraded ?? []) if (!seen.includes(code)) seen.push(code);
      return set;
    };
  const sliceRetriever = options.sliceRetriever;
  const decision = await decideOverRetrieval(prompt, recorded(retriever), {
    ...options,
    ...(sliceRetriever !== undefined
      ? { sliceRetriever: (spec, limit) => recorded(sliceRetriever(spec, limit)) }
      : {}),
  });
  if (seen.length === 0) return decision;
  return Object.freeze({ ...decision, retrievalDegraded: Object.freeze(seen) });
}

async function decideOverRetrieval(
  prompt: string,
  retriever: RecallRetriever,
  options: RecallInjectOptions,
): Promise<RecallInjectDecision> {
  const clock = options.now ?? Date.now;
  const started = clock();
  const query = prompt.trim();
  if (query.length === 0) {
    return Object.freeze({ kind: "abstain", reason: "empty_prompt", topScore: 0, matchQuality: 0 });
  }
  const maxNotes = options.maxNotes ?? RECALL_INJECT_MAX_NOTES;
  const maxChars = options.maxChars ?? RECALL_INJECT_MAX_CHARS;
  const timeBudgetMs = options.timeBudgetMs ?? RECALL_INJECT_TIME_BUDGET_MS;
  const floor = options.confidenceFloor ?? RECALL_INJECT_CONFIDENCE_FLOOR;
  const caps: ResolvedCaps = { maxNotes, maxChars, timeBudgetMs, floor };
  if (
    options.slices !== undefined &&
    options.slices.length > 0 &&
    options.sliceRetriever !== undefined
  ) {
    return decideSliced(query, options.slices, options.sliceRetriever, caps, options, started);
  }

  let resultSet: RecallResultSet;
  try {
    resultSet = await withTimeBudget(retriever(query), timeBudgetMs);
  } catch (exc) {
    return retrievalError(exc);
  }

  const ranked = rankCandidates(resultSet.candidates);
  const matchQuality = resultSet.idfWeightedCoverage;
  if (ranked.length === 0) {
    return Object.freeze({ kind: "abstain", reason: "no_matches", topScore: 0, matchQuality });
  }
  const topScore = ranked[0]!.score;
  // The floor reads match quality, never the rank position `topScore`
  // reports. `topScore` is still carried on the decision because it is
  // what the brief's bullets show and what the audit line records - it is
  // simply no longer allowed to decide anything.
  //
  // Admission is the SHARED calculator (`surfacing-key.ts`), not a
  // private floor comparison: the gate channel grades the same quality
  // against the same bound, so a boundary decision is identical on every
  // channel. The floor override rides the calculator's `floor` parameter.
  //
  // No quality means no comparison. Abstaining is the explicit choice
  // the `unmeasurable_quality` tier makes rather than a fallback: the
  // alternative was the producer's old `1`, which put every unweighable
  // prompt above every floor and injected on it.
  let admission: SurfacingKeyDecision;
  try {
    admission = computeSurfacingKey({ matchQuality, channel: RECALL_CHANNEL.hook, floor });
  } catch (exc) {
    // A retriever that reports NaN where the contract says a [0,1] number
    // or `null` has broken its report contract - an explicit error
    // decision, never a silent admit.
    return retrievalError(exc);
  }
  if (!admission.admit) {
    return Object.freeze({
      kind: "abstain",
      reason: admission.reason,
      topScore,
      matchQuality,
    });
  }

  // Dedupe sits after the floor, which read the unfiltered retrieval, and
  // before the cap. There is no over-fetch: the coverage the floor read is
  // measured over the retrieved rows, so refilling would move verdicts.
  const fresh = withoutDelivered(ranked, options);
  if (fresh.length === 0) {
    return Object.freeze({
      kind: "abstain",
      reason: "all_already_injected",
      topScore,
      matchQuality,
    });
  }

  const chosen = fresh.slice(0, maxNotes);
  // Every fresh candidate the brief does not show is counted, the ones
  // past `maxNotes` included.
  const { brief, noteCount } = renderRecallBrief(chosen, resultSet.total, maxChars, fresh.length);
  const today: Extract<RecallInjectDecision, { kind: "inject" }> = Object.freeze({
    kind: "inject",
    brief,
    noteCount,
    topScore,
    matchQuality,
    injectedNotes: injectedNotesOf(chosen.slice(0, noteCount)),
  });
  const filter = options.decisionFilter;
  if (filter === undefined || noteCount === 0) return today;
  return applyDecisionFilter(filter, today, {
    query,
    rendered: chosen.slice(0, noteCount),
    render: (kept) => {
      // The notes the budget left out stay counted; the ones the model
      // dropped are not a budget cut.
      const out = renderRecallBrief(
        kept,
        resultSet.total,
        maxChars,
        kept.length + fresh.length - noteCount,
      );
      return { ...out, injectedNotes: injectedNotesOf(kept.slice(0, out.noteCount)) };
    },
    remainingMs: filterWaitMs(timeBudgetMs - (clock() - started), options),
    clock,
  });
}

interface ResolvedCaps {
  readonly maxNotes: number;
  readonly maxChars: number;
  readonly timeBudgetMs: number;
  readonly floor: number;
}

/** A failed or timed-out retrieval as an explicit `error` decision. */
function retrievalError(exc: unknown): RecallInjectDecision {
  if (exc instanceof RecallInjectTimeoutError) {
    return Object.freeze({ kind: "error", fault: RECALL_INJECT_FAULT.timeout });
  }
  return Object.freeze({
    kind: "error",
    fault: RECALL_INJECT_FAULT.retrieverFailed,
    detail: errorDetail(exc),
  });
}

/** Score descending, then path, so equal scores render in a stable order. */
function rankCandidates(
  candidates: ReadonlyArray<RecallCandidate>,
): ReadonlyArray<RecallCandidate> {
  return candidates.toSorted(
    (a, b) => b.score - a.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
  );
}

/** One slice's retrieval judged against the floor on its own rows. */
interface SliceVerdict {
  readonly spec: RecallSliceSpec;
  readonly outcome: "inject" | RecallAbstainReason;
  readonly ranked: ReadonlyArray<RecallCandidate>;
  readonly total: number;
  readonly topScore: number;
  readonly matchQuality: number | null;
}

function judgeSlice(spec: RecallSliceSpec, set: RecallResultSet, floor: number): SliceVerdict {
  const ranked = rankCandidates(set.candidates);
  const matchQuality = set.idfWeightedCoverage;
  const topScore = ranked[0]?.score ?? 0;
  const base = { spec, ranked, total: set.total, topScore, matchQuality };
  if (ranked.length === 0) return { ...base, outcome: "no_matches" };
  // The same shared admission calculator the single-pool path uses, so a
  // slice and a whole-pool verdict agree at the tier boundaries. A
  // malformed quality report throws the calculator's named refusal, which
  // the caller catches into the same explicit error decision a broken
  // retrieval gets.
  const admission = computeSurfacingKey({ matchQuality, channel: RECALL_CHANNEL.hook, floor });
  if (!admission.admit) return { ...base, outcome: admission.reason };
  return { ...base, outcome: "inject" };
}

/**
 * The slice path: every slice retrieves in parallel under the one shared
 * time budget, each is judged against the floor on its own retrieval, and
 * the survivors are laid out in declared order inside one fence, with the
 * global caps bounding the sum. A slow slice fails the whole decision the
 * way a slow single retrieval does; there is no partial inject.
 */
async function decideSliced(
  query: string,
  slices: ReadonlyArray<RecallSliceSpec>,
  sliceRetriever: (slice: RecallSliceSpec, limit: number) => RecallRetriever,
  caps: ResolvedCaps,
  options: RecallInjectOptions,
  started: number,
): Promise<RecallInjectDecision> {
  const clock = options.now ?? Date.now;
  let sets: ReadonlyArray<RecallResultSet>;
  try {
    sets = await withTimeBudget(
      Promise.all(
        slices.map((spec) =>
          sliceRetriever(spec, Math.min(spec.limit ?? caps.maxNotes, caps.maxNotes))(query),
        ),
      ),
      caps.timeBudgetMs,
    );
  } catch (exc) {
    return retrievalError(exc);
  }
  let verdicts: ReadonlyArray<SliceVerdict>;
  try {
    verdicts = slices.map((spec, i) => judgeSlice(spec, sets[i]!, caps.floor));
  } catch (exc) {
    // A slice's coverage report broke the calculator's contract (a
    // non-finite or out-of-range `idfWeightedCoverage`): the same explicit
    // error decision a broken or slow retrieval gets, never a throw out of
    // the exported decision core.
    return retrievalError(exc);
  }
  const total = sets.reduce((sum, set) => sum + set.total, 0);
  const groups = verdicts.map((v) =>
    v.outcome === "inject" ? withoutDelivered(v.ranked, options) : [],
  );
  // Fixed before any layout: a slice the session had already seen in full.
  const shownBefore = verdicts.map((v, i) => v.outcome === "inject" && groups[i]!.length === 0);

  const layout = (pools: ReadonlyArray<ReadonlyArray<RecallCandidate>>, omittedBefore = 0) => {
    const out = renderSlicedBrief(verdicts, pools, total, caps, omittedBefore);
    const outcomes = verdicts.map((v, i): RecallSliceOutcome => {
      const placed = out.placed[i]!.length;
      if (v.outcome !== "inject") return { name: v.spec.name, outcome: v.outcome, notes: 0 };
      if (shownBefore[i] === true || out.onlyRepeats[i] === true) {
        return { name: v.spec.name, outcome: "all_already_injected", notes: 0 };
      }
      return { name: v.spec.name, outcome: "inject", notes: placed };
    });
    return { ...out, slices: Object.freeze(outcomes.map((o) => Object.freeze(o))) };
  };

  const first = layout(groups);
  const placedVerdicts = verdicts.filter((_, i) => first.placed[i]!.length > 0);
  if (placedVerdicts.length === 0) {
    const qualities = verdicts.flatMap((v) => (v.matchQuality === null ? [] : [v.matchQuality]));
    return Object.freeze({
      kind: "abstain",
      reason: "all_slices_abstained",
      topScore: Math.max(0, ...verdicts.map((v) => v.topScore)),
      matchQuality: qualities.length > 0 ? Math.max(...qualities) : null,
      slices: first.slices,
    });
  }
  const rendered = first.placed.flat();
  const today: Extract<RecallInjectDecision, { kind: "inject" }> = Object.freeze({
    kind: "inject",
    brief: first.brief,
    noteCount: rendered.length,
    topScore: Math.max(...placedVerdicts.map((v) => v.topScore)),
    matchQuality: Math.max(...placedVerdicts.map((v) => v.matchQuality ?? 0)),
    injectedNotes: injectedNotesOf(rendered),
    slices: first.slices,
  });
  const filter = options.decisionFilter;
  if (filter === undefined) return today;
  return applyDecisionFilter(filter, today, {
    query,
    rendered,
    render: (kept) => {
      const keep = new Set(kept.map(recallInjectNoteKey));
      // The notes the budget left out stay counted; the ones the model
      // dropped are not a budget cut.
      const out = layout(
        first.placed.map((pool) => pool.filter((c) => keep.has(recallInjectNoteKey(c)))),
        new Set(groups.flat().map(recallInjectNoteKey)).size - rendered.length,
      );
      const notes = out.placed.flat();
      return {
        brief: out.brief,
        noteCount: notes.length,
        injectedNotes: injectedNotesOf(notes),
        slices: out.slices,
      };
    },
    remainingMs: filterWaitMs(caps.timeBudgetMs - (clock() - started), options),
    clock,
  });
}

/**
 * Which notes survive an answer, and whether the brief is withheld. Pure,
 * so a shadow record can carry what enforce would do.
 *
 *   - `inject_any` below {@link RECALL_INJECT_ANY_MIN} withholds the brief,
 *     but only when every note was sent: a note the model never saw
 *     cannot be judged useless by it;
 *   - otherwise a sent note whose `helps_<k>` is below
 *     {@link RECALL_INJECT_NOTE_MIN} is dropped; a note that was not sent,
 *     or whose answer is invalid, stays;
 *   - no note left withholds the brief.
 *
 * The result only removes notes; it never adds one.
 */
export function recallInjectFilterOutcome(
  helps: ReadonlyArray<number | null>,
  sent: ReadonlyArray<boolean>,
  injectAny: number | null,
): { readonly abstain: boolean; readonly keep: ReadonlyArray<boolean> } {
  const keep = helps.map((p, i) => !(sent[i] === true && p !== null && p < RECALL_INJECT_NOTE_MIN));
  const allSent = sent.length === helps.length && sent.every(Boolean);
  const abstain =
    (injectAny !== null && injectAny < RECALL_INJECT_ANY_MIN && allSent) || !keep.some(Boolean);
  return { abstain, keep };
}

/** A brief laid out again over the notes the filter kept. */
interface RenderedBrief {
  readonly brief: string;
  readonly noteCount: number;
  readonly injectedNotes: ReadonlyArray<RecallInjectedNote>;
  readonly slices?: ReadonlyArray<RecallSliceOutcome>;
}

interface FilterContext {
  readonly query: string;
  readonly rendered: ReadonlyArray<RecallCandidate>;
  /**
   * The same renderer and caps that produced today's brief. Its cut line
   * names only the notes the budget left out (task 4.4): a note the
   * decision filter judged unhelpful is not a budget cut, and naming it
   * would spend the characters the filter saved.
   */
  readonly render: (kept: ReadonlyArray<RecallCandidate>) => RenderedBrief;
  readonly remainingMs: number;
  readonly clock: () => number;
}

/**
 * How long the decision filter may wait: what is left of the time budget,
 * never past the caller's own bound ({@link RecallInjectOptions.decisionWaitLeftMs}).
 */
function filterWaitMs(budgetLeftMs: number, options: RecallInjectOptions): number {
  const bound = options.decisionWaitLeftMs?.();
  return bound === undefined ? budgetLeftMs : Math.min(budgetLeftMs, bound);
}

/**
 * Run the decision-model filter over today's `inject` decision. Never
 * throws and never extends the time budget: with nothing left the filter
 * is not asked at all, and a filter still running when the budget ends
 * is abandoned as a `timeout`. Every failure keeps today's decision.
 */
async function applyDecisionFilter(
  filter: RecallInjectFilter,
  today: Extract<RecallInjectDecision, { kind: "inject" }>,
  ctx: FilterContext,
): Promise<RecallInjectDecision> {
  const t0 = ctx.clock();
  const degraded = (reason: string): RecallInjectDecision =>
    Object.freeze({
      ...today,
      decisionModel: Object.freeze({
        mode: filter.mode,
        outcome: "degraded",
        degradeReason: reason,
        latencyMs: Math.max(0, ctx.clock() - t0),
        notesDropped: 0,
        abstained: false,
        charsRemoved: 0,
      }),
    });
  if (ctx.remainingMs <= 0) return degraded("timeout");

  let verdict: RecallInjectFilterVerdict;
  try {
    verdict = await withTimeBudget(
      filter.run({ query: ctx.query, notes: ctx.rendered, remainingMs: ctx.remainingMs }),
      ctx.remainingMs,
    );
  } catch (exc) {
    return degraded(exc instanceof RecallInjectTimeoutError ? "timeout" : "network");
  }
  if (verdict.status === "off") return today;
  if (verdict.status === "degraded") {
    return Object.freeze({
      ...today,
      decisionModel: Object.freeze({
        mode: verdict.mode,
        outcome: "degraded",
        degradeReason: verdict.reason,
        latencyMs: verdict.latencyMs,
        notesDropped: 0,
        abstained: false,
        charsRemoved: 0,
      }),
    });
  }
  if (verdict.status === "not_sent") {
    return Object.freeze({
      ...today,
      decisionModel: Object.freeze({
        mode: verdict.mode,
        outcome: "not_sent",
        latencyMs: Math.max(0, ctx.clock() - t0),
        notesDropped: 0,
        abstained: false,
        charsRemoved: 0,
      }),
    });
  }

  const { abstain, keep } = recallInjectFilterOutcome(
    verdict.helps,
    verdict.sent,
    verdict.injectAny,
  );
  const kept = ctx.rendered.filter((_, i) => keep[i] === true);
  const notesDropped = abstain ? ctx.rendered.length : ctx.rendered.length - kept.length;
  const info = {
    mode: verdict.mode,
    outcome: "ok" as const,
    latencyMs: verdict.latencyMs,
    notesDropped,
    abstained: abstain,
    charsRemoved: 0,
  };
  // Shadow: recorded, and today's brief goes out unchanged.
  if (verdict.mode === "shadow" || notesDropped === 0) {
    return Object.freeze({ ...today, decisionModel: Object.freeze(info) });
  }
  const tokensBefore = estimateTokens(today.brief);
  const withheld = (): RecallInjectDecision =>
    Object.freeze({
      kind: "abstain",
      reason: "decision_model_abstain",
      topScore: today.topScore,
      matchQuality: today.matchQuality,
      ...(today.slices !== undefined ? { slices: today.slices } : {}),
      decisionModel: Object.freeze({
        ...info,
        abstained: true,
        notesDropped: ctx.rendered.length,
        tokensBefore,
        tokensAfter: 0,
        charsRemoved: today.brief.length,
      }),
    });
  if (abstain) return withheld();
  // The existing renderer and caps over the surviving notes only.
  const { brief, noteCount, injectedNotes, slices } = ctx.render(kept);
  if (noteCount === 0) return withheld();
  return Object.freeze({
    kind: "inject",
    brief,
    noteCount,
    topScore: today.topScore,
    matchQuality: today.matchQuality,
    injectedNotes,
    ...(slices !== undefined ? { slices } : {}),
    decisionModel: Object.freeze({
      ...info,
      tokensBefore,
      tokensAfter: estimateTokens(brief),
      charsRemoved: Math.max(0, today.brief.length - brief.length),
    }),
  });
}

/**
 * Render the bounded brief: a fixed header, the shared recall-hint
 * orientation line, then one bullet per note added only while the whole
 * brief stays within `maxChars`. Returns the count of notes actually
 * rendered so the audit reflects the delivered brief.
 *
 * Note titles are untrusted vault content, so every title is neutralized
 * (see {@link neutralizeTitle}) BEFORE it reaches either the recall-hint line
 * or a note bullet, and the finished brief is fenced as untrusted content
 * ({@link fenceUntrustedContent}). The fence delimiter overhead is charged
 * against `maxChars` - the whole fenced brief, not just its inner body, stays
 * within the cap - so the hard char bound the audit relies on still holds.
 */
function renderRecallBrief(
  chosen: ReadonlyArray<RecallCandidate>,
  total: number,
  maxChars: number,
  /** How many candidates were on offer (the cut line counts the rest); `chosen.length` by default. */
  offered: number = chosen.length,
): { readonly brief: string; readonly noteCount: number } {
  const safe = chosen.map((c) => ({ ...c, title: neutralizeTitle(c.title) }));
  // Charge the fence delimiter overhead against the cap so the FENCED brief
  // (not merely its inner body) is what stays within `maxChars`.
  const innerBudget = Math.max(0, maxChars - fenceOverhead());
  // Seed the header only when it fits the inner budget; a caller-supplied
  // tiny `maxChars` must never be exceeded just to carry the header.
  const header = RECALL_BRIEF_HEADER;
  const lines: string[] = header.length <= innerBudget ? [header] : [];
  let noteCount = 0;
  for (const note of safe) {
    const line = renderNoteLine(note);
    if ([...lines, line].join("\n").length > innerBudget) break;
    lines.push(line);
    noteCount += 1;
  }
  // The budget-cut line (task 4.4): the notes this cap left out are
  // named, with a real way to get them. The
  // line rides INSIDE the budget: a note gives way when the line would
  // not fit, the count is recomputed after each eviction, and the last
  // note is never evicted for it - the line is dropped instead.
  // Evictions are tried on a copy and kept only when the line then fits.
  // A brief that shows no note carries no cut line either.
  if (noteCount > 0 && offered - noteCount > 0) {
    const trial = [...lines];
    let shown = noteCount;
    for (;;) {
      const cut = recallCutLine(offered - shown);
      if ([...trial, cut].join("\n").length <= innerBudget) {
        lines.splice(0, lines.length, ...trial, cut);
        noteCount = shown;
        break;
      }
      if (shown <= 1) break;
      trial.pop();
      shown -= 1;
    }
  }
  // The hint is orientation, not a pointer: it describes the notes the
  // brief finally shows and goes in after the header only while it fits,
  // so a tight budget spends its characters on the note pointers instead.
  const hintInputs: ReadonlyArray<RecallHintInput> = safe.slice(0, noteCount).map((c) => ({
    searchType: c.searchType,
    score: c.score,
    title: c.title,
  }));
  const hint = deriveRecallHint(hintInputs, total);
  if (hint !== null) {
    const at = lines[0] === header ? 1 : 0;
    const withHint = lines.toSpliced(at, 0, hint);
    if (withHint.join("\n").length <= innerBudget) lines.splice(at, 0, hint);
  }
  return { brief: fenceUntrustedContent(lines.join("\n"), RECALL_FENCE_ORIGIN), noteCount };
}

const RECALL_BRIEF_HEADER = "Recalled vault context (relevance-matched to this prompt):";

/**
 * The sectioned variant of {@link renderRecallBrief}: the same header,
 * fence, neutralisers and bullet format, with each slice's notes under a
 * `## <heading>` line. Slices are laid out in declared order; each takes
 * `min(slice.limit, notes left)` notes and `min(slice.maxChars, chars
 * left)` of heading plus bullets, so the global caps, fence included,
 * bound the sum and a later slice is the one clamped. A note already
 * placed by an earlier slice is not repeated, and a slice that places no
 * note gets no heading. The recall-hint line is orientation, so it goes in
 * after the notes and only while it still fits.
 */
function renderSlicedBrief(
  verdicts: ReadonlyArray<SliceVerdict>,
  pools: ReadonlyArray<ReadonlyArray<RecallCandidate>>,
  total: number,
  caps: Pick<ResolvedCaps, "maxNotes" | "maxChars">,
  /** Notes an earlier layout's budget left out of `pools`: still counted in the cut line. */
  omittedBefore = 0,
): {
  readonly brief: string;
  readonly placed: ReadonlyArray<ReadonlyArray<RecallCandidate>>;
  /** Per slice: its pool was not empty, and an earlier slice placed every note of it. */
  readonly onlyRepeats: ReadonlyArray<boolean>;
} {
  const innerBudget = Math.max(0, caps.maxChars - fenceOverhead());
  const lines: string[] = RECALL_BRIEF_HEADER.length <= innerBudget ? [RECALL_BRIEF_HEADER] : [];
  const seen = new Set<string>();
  const placed: RecallCandidate[][] = [];
  const onlyRepeats: boolean[] = [];
  for (const [i, verdict] of verdicts.entries()) {
    const fresh = (pools[i] ?? []).filter((c) => !seen.has(recallInjectNoteKey(c)));
    onlyRepeats.push((pools[i] ?? []).length > 0 && fresh.length === 0);
    const notesLeft = caps.maxNotes - seen.size;
    const take = Math.min(verdict.spec.limit ?? notesLeft, notesLeft);
    const sliceChars = verdict.spec.maxChars ?? Number.POSITIVE_INFINITY;
    const heading = `## ${neutralizeHeading(verdict.spec)}`;
    const section: string[] = [];
    const chosen: RecallCandidate[] = [];
    for (const note of fresh) {
      if (chosen.length >= take) break;
      const line = renderNoteLine({ ...note, title: neutralizeTitle(note.title) });
      const next = [heading, ...section, line];
      if (next.join("\n").length > sliceChars) break;
      if ([...lines, ...next].join("\n").length > innerBudget) break;
      section.push(line);
      chosen.push(note);
    }
    if (chosen.length > 0) lines.push(heading, ...section);
    for (const note of chosen) seen.add(recallInjectNoteKey(note));
    placed.push(chosen);
  }
  // The budget-cut line (task 4.4), as renderRecallBrief renders it: a
  // tail note gives way (and leaves `placed`, so it is not recorded as
  // injected), a heading left without notes goes with it, the count is
  // recomputed after each eviction, and the last note is never evicted.
  // Evictions are tried on copies and kept only when the line then fits.
  const offered = new Set(pools.flat().map(recallInjectNoteKey));
  const notShownOf = (p: RecallCandidate[][]): number =>
    omittedBefore + offered.size - p.flat().length;
  if (notShownOf(placed) > 0) {
    const trialLines = [...lines];
    const trialPlaced = placed.map((p) => [...p]);
    for (;;) {
      const cut = recallCutLine(notShownOf(trialPlaced));
      if ([...trialLines, cut].join("\n").length <= innerBudget) {
        lines.splice(0, lines.length, ...trialLines, cut);
        placed.splice(0, placed.length, ...trialPlaced);
        break;
      }
      if (trialPlaced.flat().length <= 1) break;
      const lastSlice = trialPlaced.findLastIndex((p) => p.length > 0);
      trialPlaced[lastSlice]!.pop();
      trialLines.pop();
      if (trialPlaced[lastSlice]!.length === 0) trialLines.pop();
    }
  }
  // The hint describes the notes the brief finally shows, after the cut
  // line's evictions, and goes in only while it still fits.
  const hint = deriveRecallHint(
    placed.flat().map((c) => ({
      searchType: c.searchType,
      score: c.score,
      title: neutralizeTitle(c.title),
    })),
    total,
  );
  const at = lines[0] === RECALL_BRIEF_HEADER ? 1 : 0;
  if (hint !== null) {
    const withHint = lines.toSpliced(at, 0, hint);
    if (withHint.join("\n").length <= innerBudget) lines.splice(at, 0, hint);
  }
  return {
    brief: fenceUntrustedContent(lines.join("\n"), RECALL_FENCE_ORIGIN),
    placed,
    onlyRepeats,
  };
}

/** Where the notes a recall brief leaves out can be read: the search tool with this prompt. */
const RECALL_CUT_COMMAND = "Search for them with `brain_search` and this prompt";

function recallCutLine(dropped: number): string {
  return budgetCutLine({
    dropped,
    what: "recalled notes",
    whatOne: "recalled note",
    command: RECALL_CUT_COMMAND,
  });
}

/** A slice heading is operator text: neutralised like a title, never empty. */
function neutralizeHeading(spec: RecallSliceSpec): string {
  const clean = neutralizeSingleLine(spec.heading).trim();
  return clean.length > 0 ? clean : spec.name;
}

/** Character cost of the untrusted-content fence around an empty body. */
function fenceOverhead(): number {
  return fenceUntrustedContent("", RECALL_FENCE_ORIGIN).length;
}

/**
 * Neutralize one untrusted vault title for single-line use in the brief.
 * Reuses the structural neutralizer (control/bidi/zero-width strip plus
 * delimiter escape), then collapses any surviving newline/tab run to one
 * space so the title can never break the brief's line structure or smuggle a
 * forged delimiter past review.
 */
function neutralizeTitle(title: string | null): string {
  if (title === null || title.length === 0) return "(untitled)";
  const clean = neutralizeSingleLine(title);
  return clean.length > 0 ? clean : "(untitled)";
}

function renderNoteLine(note: { readonly title: string } & Omit<RecallCandidate, "title">): string {
  // The path is untrusted vault content too: neutralize it the same way as a
  // title so a newline/control char in a path cannot break the line format.
  const pointer = `${neutralizeSingleLine(note.path)}:L${note.startLine}-L${note.endLine}`;
  const origin = note.origin !== undefined ? ` [${note.origin}]` : "";
  return `- "${note.title}" (${pointer}, ${note.searchType} ${note.score.toFixed(2)})${origin}`;
}

/**
 * The originating message, for the local audit file. Never reaches a
 * telemetry payload - see {@link recallInjectTelemetryMetadata}.
 */
function errorDetail(exc: unknown): string {
  if (exc instanceof Error) return exc.message;
  return String(exc);
}

/**
 * One decision as the metadata of a recall-telemetry record.
 *
 * Classifications and bounded numbers ONLY. This payload is appended to
 * the continuity log, which syncs, and `brain_recall_telemetry` returns
 * it verbatim to a model - so nothing shaped like a filesystem path or a
 * provider sentence may appear here. Both the abstain reason and the
 * error fault are members of closed vocabularies, which is what makes
 * that rule checkable rather than a matter of care at each call site.
 */
export function recallInjectTelemetryMetadata(
  decision: RecallInjectDecision,
): Readonly<Record<string, unknown>> {
  if (decision.kind === "inject") {
    return Object.freeze({
      decision: "inject",
      note_count: decision.noteCount,
      top_score: decision.topScore,
      match_quality: decision.matchQuality,
      ...decisionModelTelemetry(decision.decisionModel),
    });
  }
  if (decision.kind === "abstain") {
    return Object.freeze({
      decision: "abstain",
      reason: decision.reason,
      // The gate's own reason is a closed classification like the abstain
      // reason itself, so it satisfies the same names-nothing-sensitive
      // rule; dropping it would leave an unexplainable `structural`.
      ...(decision.structuralReason !== undefined
        ? { structural_reason: decision.structuralReason }
        : {}),
      top_score: decision.topScore,
      match_quality: decision.matchQuality,
      ...decisionModelTelemetry(decision.decisionModel),
    });
  }
  return Object.freeze({ decision: "error", fault: decision.fault });
}

/**
 * The same decision as a hook-audit line: everything the telemetry
 * record carries, plus the originating message when there is one.
 *
 * The audit file is local, unsynced operational evidence under
 * `<vault>/.open-second-brain/hook-audit/`, and the message is exactly
 * what an operator debugging a broken retriever needs, so it stays HERE
 * and only here. Derived from the telemetry projection rather than
 * written out a second time: two hand-maintained shapes are how the
 * message reached the synced payload to begin with.
 */
export function recallInjectAuditDetails(
  decision: RecallInjectDecision,
): Readonly<Record<string, unknown>> {
  const safe = recallInjectTelemetryMetadata(decision);
  if (decision.kind !== "error") {
    // Slice names are operator vocabulary, local to this vault's policy:
    // they ride the audit line only, never the synced telemetry record.
    const sliced =
      decision.slices === undefined ? safe : Object.freeze({ ...safe, slices: decision.slices });
    // The decision-model degrade reason is local operational evidence,
    // like a retriever's message: it rides this line only.
    // So are the retrieval's degradation codes: a gated or degraded
    // semantic lane at the hook is named here, never in the synced record.
    const degraded =
      decision.retrievalDegraded === undefined
        ? sliced
        : Object.freeze({ ...sliced, retrieval_degraded: decision.retrievalDegraded });
    const reason = decision.decisionModel?.degradeReason;
    if (reason === undefined) return degraded;
    return Object.freeze({
      ...degraded,
      decision_model: Object.freeze({
        ...(safe["decision_model"] as Readonly<Record<string, unknown>>),
        degrade_reason: reason,
      }),
    });
  }
  return Object.freeze({
    ...safe,
    ...(decision.detail !== undefined ? { detail: decision.detail } : {}),
    ...(decision.retrievalDegraded !== undefined
      ? { retrieval_degraded: decision.retrievalDegraded }
      : {}),
  });
}

/**
 * The decision-model fields of a telemetry record: mode, a coarse outcome,
 * the added latency, notes dropped and whether the brief was withheld.
 * Absent when the filter did not run, so an install without the feature
 * writes exactly the record it wrote before.
 */
function decisionModelTelemetry(
  info: RecallInjectDecisionModelInfo | undefined,
): Readonly<Record<string, unknown>> {
  if (info === undefined) return {};
  return {
    decision_model: Object.freeze({
      mode: info.mode,
      outcome: info.outcome,
      latency_ms: Math.max(0, Math.round(info.latencyMs)),
      notes_dropped: info.notesDropped,
      abstained: info.abstained,
    }),
  };
}

/**
 * Resolve `promise`, or reject with a {@link RecallInjectTimeoutError} once
 * `budgetMs` elapses. The timer is cleared on settle so it never keeps the
 * process alive past the real work.
 */
async function withTimeBudget<T>(promise: Promise<T>, budgetMs: number): Promise<T> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  const timeout = new Promise<never>((_resolve, reject) => {
    timer = setTimeout(() => reject(new RecallInjectTimeoutError(budgetMs)), budgetMs);
  });
  try {
    return await Promise.race([promise, timeout]);
  } finally {
    if (timer !== undefined) clearTimeout(timer);
  }
}

/**
 * The default retriever: the existing cross-vault search over the active
 * vault and its read-only recall sources. No new retriever is introduced -
 * this only adapts {@link searchAcrossVaults} results into the narrow
 * {@link RecallCandidate} shape the decision core consumes.
 */
export function defaultRecallRetriever(
  configPath: string,
  vault: string,
  limitOrFilter: number | RecallRetrieverFilter = RECALL_INJECT_MAX_NOTES,
): RecallRetriever {
  const filter: RecallRetrieverFilter =
    typeof limitOrFilter === "number" ? { limit: limitOrFilter } : limitOrFilter;
  const limit = filter.limit ?? RECALL_INJECT_MAX_NOTES;
  const types = filter.types ?? [];
  return async (query) => {
    // The decision-model rerank kind is skipped here: a decision request
    // (its timeout plus a retry) does not fit the hook's retrieval budget,
    // and a hook fires on every prompt. The heuristic order is used.
    const outcome = await searchAcrossVaults(configPath, vault, {
      query,
      limit,
      skipDecisionModelRerank: true,
      ...(filter.pathPrefix !== undefined ? { pathPrefix: filter.pathPrefix } : {}),
      ...(types.length > 0 ? { properties: new Map([["type", types]]) } : {}),
    });
    const candidates = outcome.results.map((result) =>
      Object.freeze({
        path: result.path,
        title: result.title,
        score: result.score,
        searchType: result.searchType,
        startLine: result.startLine,
        endLine: result.endLine,
        ...(result.origin !== undefined ? { origin: result.origin } : {}),
        content: result.content,
      }),
    );
    const degraded = outcome.retrievalTrail?.degraded ?? [];
    return Object.freeze({
      candidates: Object.freeze(candidates),
      total: outcome.total,
      idfWeightedCoverage: outcome.idfWeightedCoverage,
      ...(degraded.length > 0 ? { degraded: Object.freeze(degraded.map((d) => d.code)) } : {}),
    });
  };
}