@dzhechkov/harness-core 0.7.11 → 0.8.1

package/src/teach-target.ts

@@ -0,0 +1,126 @@
+/**
+ * teach-target — which store does THIS lesson belong to, and who decided.
+ *
+ * The owner asked for a per-session choice: "in this session accumulate per project; in another,
+ * across all projects." For a CLI every invocation is a fresh process, so there is no session
+ * object to hold a mode. An environment variable IS a shell session — set once, governs every
+ * command in that terminal, dies with it. A persisted file would outlive what the user meant by
+ * "this session" and become a mode nobody remembers setting.
+ *
+ * This increment is third on purpose. A mode set once and forgotten lies silently, and it is safe
+ * here only because `learning-store-says-where` already makes every write announce its destination.
+ * This adds the other half of that sentence: not only WHERE the lesson landed, but WHY that store
+ * was chosen. A fact that is not stated cannot be checked.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Where a lesson is written. */
+export type TeachStore = 'project' | 'global';
+
+/** Who decided — the reason is printed, so a forgotten mode cannot stay invisible. */
+export type TeachReason = 'flag' | 'environment' | 'config' | 'default';
+
+export interface TeachTarget {
+  readonly store: TeachStore;
+  readonly reason: TeachReason;
+}
+
+/** Refusal, never a silent fallback. */
+export class TeachTargetError extends Error {}
+
+export const TEACH_STORES: readonly TeachStore[] = ['project', 'global'];
+
+const VALID = new Set<string>(TEACH_STORES);
+
+/**
+ * One level of input, validated.
+ *
+ * An unknown value is REFUSED and the source is named, because the cure differs: a bad flag is a
+ * typo on this command line, a bad environment variable was exported hours ago in another window,
+ * and a bad config is committed and affects everyone on the project.
+ *
+ * `DZ_LEARN=globl` quietly writing to the project store would be the invisible mislabel this whole
+ * mode exists to prevent, arriving through the mode itself.
+ */
+function validate(value: string | undefined, source: string): TeachStore | undefined {
+  if (value === undefined) return undefined;
+  const v = value.trim();
+  if (v === '') return undefined;                       // an empty export is not a choice
+  if (!VALID.has(v)) {
+    throw new TeachTargetError(
+      `${source}: unknown store ${JSON.stringify(v)} — expected one of: ${TEACH_STORES.join(', ')}`,
+    );
+  }
+  return v as TeachStore;
+}
+
+/**
+ * Resolve the destination.
+ *
+ * Precedence, most specific first: `--to` → `DZ_LEARN` → project config → `project`.
+ * That ordering is the only one a user can predict without reading the source.
+ *
+ * **The default does not move.** MEASURED: 361 records in this repo's own store were written under
+ * today's behaviour, and every other user's store is the same. Redirecting an un-flagged `dz teach`
+ * would silently change every existing workflow, and the user would find out when a lesson was not
+ * where they expected it.
+ */
+export function resolveTeachTarget(input: {
+  flag?: string | undefined;
+  env?: string | undefined;
+  config?: string | undefined;
+}): TeachTarget {
+  const flag = validate(input.flag, '--to');
+  if (flag !== undefined) return { store: flag, reason: 'flag' };
+
+  const env = validate(input.env, 'DZ_LEARN');
+  if (env !== undefined) return { store: env, reason: 'environment' };
+
+  const cfg = validate(input.config, '.dz/config.json learning.teachTo');
+  if (cfg !== undefined) return { store: cfg, reason: 'config' };
+
+  return { store: 'project', reason: 'default' };
+}
+
+/**
+ * How the reason reads in the store line.
+ *
+ * Each phrase names WHERE the decision came from, so a user who set `DZ_LEARN=global` three hours
+ * ago and forgot has something to recognise. `default` deliberately says nothing extra: adding a
+ * phrase there would change the line for every user who set nothing, breaking the byte-identity
+ * this feature promises them.
+ */
+export function teachReasonPhrase(reason: TeachReason): string {
+  switch (reason) {
+    case 'flag': return 'chosen by --to';
+    case 'environment': return 'chosen by DZ_LEARN in this shell';
+    case 'config': return 'chosen by .dz/config.json';
+    case 'default': return '';
+  }
+}
+
+/**
+ * Read the project default from `.dz/config.json` → `learning.teachTo`.
+ *
+ * Returns the RAW string, not a validated store: an unreadable file is "no opinion", but a file
+ * that says `teachTo: "globl"` HAS an opinion and must be refused by `resolveTeachTarget` rather
+ * than swallowed here. Those two cases are different and the caller can only tell them apart if
+ * this function keeps them apart.
+ */
+export function readTeachToConfig(projectRoot: string): string | undefined {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8'),
+    ) as { learning?: { teachTo?: unknown } };
+    const raw = parsed.learning?.teachTo;
+    if (raw === undefined || raw === null) return undefined;   // no key is no opinion
+    // A present key of the WRONG TYPE (`teachTo: true`) is still an opinion, and a wrong one.
+    // Returning undefined here would fall through to the project default silently — the exact
+    // fail-open the resolver refuses everywhere else (cross-family QE, 2026-08-27).
+    return typeof raw === 'string' ? raw : JSON.stringify(raw);
+  } catch {
+    return undefined;   // missing or unparseable config is no opinion at all
+  }
+}

package/src/vector-tier.ts

@@ -74,7 +74,23 @@ import {
 // agentdb-index/compounding only, never vector-tier, so there is no cycle.
 import { BACKLOG_TASK_TYPE } from './backlog.js';
 import { currentEmbedManifest, guardEmbedSpace, DEFAULT_EMBED_DIM, resolveEmbedModel, type EmbedModelConfig } from './embedding-config.js';
-import { applyLearningSignals, applyLearningSignalsWithDelta, resolveLearningBackend, type LearningSignalBackend } from './learning-backend.js';
+import { applyLearningSignals, applyLearningSignalsWithDelta, applyLearningSignalsWithTerms, resolveLearningBackend, type LearningSignalBackend, type RerankTerm } from './learning-backend.js';
+import {
+  describeNativeDep,
+  exerciseSqliteOpen,
+  probeNativeDep,
+  type NativeDepVerdict,
+} from './native-dep-probe.js';
+// lesson-bandit-rerank: the payoff axis. ONE-DIRECTIONAL — lesson-payoff imports patterns.js and
+// nothing from here, so there is no cycle.
+import {
+  contextKeyFor,
+  narrowBanditReport,
+  payoffTermsFor,
+  recordExposures,
+  resolveBanditConfig,
+  type BanditRecallReport,
+} from './lesson-payoff.js';
 
 /* ------------------------------------------------------------------ */
 /*  Types (04_domain_model §3.4 / §4.1)                                */
@@ -219,6 +235,17 @@ export interface HybridRecall {
    * returns only ids the lexical store no longer has has participated in nothing.
    */
   readonly semanticRanked: number;
+  /**
+   * The bandit payoff explanation (feature lesson-bandit-rerank, FR-8/AC-11) — PRESENT only when
+   * `memory.learning.banditRerank` is armed, ABSENT otherwise (not `null`, not `{}`): its mere
+   * presence tells a reader the feature ran. `armsConsidered` describes the POST-cut list, and
+   * `moved` — the honest headline — counts the candidates whose position the term actually changed.
+   * An armed, silent re-ranker is indistinguishable from a broken one, which is why this exists.
+   */
+  readonly bandit?: BanditRecallReport | undefined;
+  /** Present ONLY when `deferExposures` was requested and the bandit ran. Call it with the ids the
+   * caller actually printed; until it is called, no exposure has been recorded for this recall. */
+  readonly commitExposures?: ((shownDzIds: readonly string[]) => void) | undefined;
 }
 
 
@@ -297,6 +324,14 @@ export const DEFAULT_VECTOR_TIMEOUT_MS = 10_000;
 /** Default cosine cutoff for near-duplicate clustering (`--threshold` / config overrides). */
 export const DEFAULT_HARMONIZE_THRESHOLD = 0.92;
 export const REINFORCE_RRF_CAP = (1 / (60 + 1)) - (1 / (60 + 4));
+/**
+ * The bandit payoff term's bound (ADR-001 D-2). Deliberately the SAME constant the reinforcement and
+ * SAFLA-delta terms use, not a new one: it keeps the "a learning signal is worth less than one RRF
+ * rank step" invariant those terms already established, and makes the joint excursion of two payoff
+ * terms auditable as exactly `2 × CAP`. Payoff reorders near-ties; it cannot overturn a real
+ * relevance gap.
+ */
+export const BANDIT_RRF_CAP = REINFORCE_RRF_CAP;
 
 /* ------------------------------------------------------------------ */
 /*  Harmonize + import types (dz-vector-harmonize-import 05 §2.1/§2.2)  */
@@ -605,8 +640,11 @@ export function mirrorWriterExplanation(state: MirrorWriterState): string {
 }
 
 /**
- * Engine selection cascade: config mode → `require.resolve` probe (NO module load — a
- * lexical-only project pays zero engine cost, NFR-5) → adapter or an honest reason.
+ * Engine selection cascade: config mode → project-local package gate → native usability probe
+ * → adapter or an honest reason. A lexical-only project still pays nothing because
+ * {@link isPackageInstalled} gates the probe; a project with the dependency installed pays one
+ * require + one in-memory open per process (measured: agentdb 53.6 ms, better-sqlite3 8.6 ms,
+ * 62.2 ms total, versus about 0.008 ms for the old existsSync-only check).
  * Never throws. `auto` prefers agentdb (it reads the vectors consolidate already wrote),
  * falling through to rvf.
  */
@@ -630,19 +668,43 @@ function isPackageInstalled(projectRoot: string, pkgName: string): boolean {
 export function resolveVectorEngine(projectRoot: string): ResolvedVectorEngine {
   const mode = readVectorEngineMode(projectRoot);
   if (mode === 'off') return { reason: 'vector tier disabled (memory.vector.engine = "off")' };
-  const canResolve = (id: string): boolean => isPackageInstalled(projectRoot, id);
+  let autoAgentdbFailure: string | undefined;
+  const probeIfInstalled = (id: string): NativeDepVerdict =>
+    isPackageInstalled(projectRoot, id)
+      ? id === 'better-sqlite3'
+        ? probeNativeDep(projectRoot, id, exerciseSqliteOpen)
+        : probeNativeDep(projectRoot, id)
+      : { state: 'absent', pkg: id };
   if (mode === 'agentdb' || mode === 'auto') {
-    if (canResolve('agentdb') && canResolve('better-sqlite3')) return { engine: agentdbVectorEngine(projectRoot) };
+    const agentdb = probeIfInstalled('agentdb');
+    if (agentdb.state === 'unusable') {
+      const reason = describeNativeDep(agentdb);
+      if (mode === 'agentdb') return { reason };
+      autoAgentdbFailure = reason;
+    }
+    const sqlite = agentdb.state === 'usable' ? probeIfInstalled('better-sqlite3') : undefined;
+    if (sqlite?.state === 'unusable') return { reason: describeNativeDep(sqlite) };
+    if (agentdb.state === 'usable' && sqlite?.state === 'usable') {
+      return { engine: agentdbVectorEngine(projectRoot) };
+    }
     if (mode === 'agentdb') {
       return { reason: 'agentdb/better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
     }
   }
   if (mode === 'rvf' || mode === 'auto') {
-    if (canResolve('@ruvector/rvf')) return { engine: rvfVectorEngine(projectRoot) };
+    const rvf = probeIfInstalled('@ruvector/rvf');
+    if (rvf.state === 'unusable') {
+      const reason = describeNativeDep(rvf);
+      return { reason: autoAgentdbFailure === undefined ? reason : `${autoAgentdbFailure}; ${reason}` };
+    }
+    if (rvf.state === 'usable') return { engine: rvfVectorEngine(projectRoot) };
     if (mode === 'rvf') {
       return { reason: '@ruvector/rvf not installed in project (npm i @ruvector/rvf) — vector tier inactive' };
     }
   }
+  if (autoAgentdbFailure !== undefined) {
+    return { reason: `${autoAgentdbFailure}; @ruvector/rvf not installed in project (npm i @ruvector/rvf) — vector tier inactive` };
+  }
   return { reason: 'no vector engine available: agentdb/better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
 }
 
@@ -979,11 +1041,44 @@ export function mergeHybridHits(
   return cut.map(toHit);
 }
 
-function markRecallHits(projectRoot: string, backend: LearningSignalBackend, hits: readonly HybridHit[], idOf: (p: PatternRecord) => string): void {
+/**
+ * Emit the recall-hit telemetry for the hits a caller is about to see.
+ *
+ * `bandit` is passed ONLY when `memory.learning.banditRerank` is armed; when it is absent this
+ * function is byte-identical to its pre-feature self — no state file, no lock, no allocation.
+ */
+function markRecallHits(
+  projectRoot: string,
+  backend: LearningSignalBackend,
+  hits: readonly HybridHit[],
+  idOf: (p: PatternRecord) => string,
+  bandit?: {
+    readonly contextKey: string; readonly explored: readonly string[]; readonly moved: number; readonly arms: number;
+    /** TRUE ⇒ record the learning samples but NOT the bandit exposures; the caller commits them once
+     * it knows which hits it actually printed. `dz recall --domain` over-fetches and truncates AGAIN
+     * downstream, so committing here counted hits nobody ever saw as "seen" — inflating the health
+     * metrics and mislabeling hidden candidates (cross-family QE, gpt-5.6-sol). */
+    readonly deferred?: boolean;
+  } | undefined,
+): void {
   const cfg = readMemoryLearningConfig(projectRoot);
   if (cfg.backend === 'off' || cfg.onRecallHits === false) return;
   const ts = new Date().toISOString();
   for (const h of hits) backend.addSample({ dzId: idOf(h.pattern), kind: 'recall-hit', reward: h.pattern.reward, ts });
+  if (bandit !== undefined && bandit.deferred === true) return;   // the caller will commit post-cut
+  if (bandit !== undefined) {
+    // EXPOSURE, not reward (INV-2): one BATCHED locked transaction per recall, and it touches only
+    // our own counters — `alpha`/`beta`/`totalReward` are not passed to the engine at all. Taking
+    // the lock once per HIT would be `limit` transactions per recall for bookkeeping.
+    try {
+      recordExposures(
+        projectRoot,
+        hits.map((h) => ({ dzId: idOf(h.pattern), contextKey: bandit.contextKey, ts })),
+        bandit.explored,
+        { moved: bandit.moved, arms: bandit.arms },
+      );
+    } catch { /* a derived index never blocks the recall return (NFR-5) */ }
+  }
   void backend.train().catch(() => undefined);
 }
 
@@ -997,7 +1092,20 @@ function markRecallHits(projectRoot: string, backend: LearningSignalBackend, hit
 export async function recallHybrid(
   projectRoot: string,
   query: string,
-  opts: VectorServiceOptions & { readonly limit?: number | undefined; readonly mode?: HybridRecallMode | undefined } = {},
+  opts: VectorServiceOptions & {
+    readonly limit?: number | undefined;
+    readonly mode?: HybridRecallMode | undefined;
+    /** Defer bandit EXPOSURE recording to the caller (default false ⇒ byte-identical to today).
+     * A caller that over-fetches and truncates again — `dz recall --domain` does — must set this and
+     * then call `commitExposures(shownDzIds)`, or hits nobody ever saw are counted as seen. */
+    readonly deferExposures?: boolean | undefined;
+    /**
+     * The resolved recall domain (the axis `dz recall --domain` already boosts on). It becomes the
+     * bandit's ContextKey (FR-5) — coarse on purpose, so posteriors accumulate instead of every arm
+     * sitting at `pulls === 0` forever. Absent ⇒ `general`; it changes nothing while disarmed.
+     */
+    readonly domain?: string | undefined;
+  } = {},
 ): Promise<HybridRecall> {
   // Config-surface note (QE P3, benign by design): recall resolves the engine directly, while teach
   // only mirrors when the memory backend is agentdb (or an engine is explicit). In the window where
@@ -1035,30 +1143,135 @@ export async function recallHybrid(
       })
       .sort((a, b) => b.score - a.score);
   };
+  // lesson-bandit-rerank (ADR-001): the payoff axis. Resolved ONCE per recall; `enabled:false` ⇒
+  // the Lesson Payoff context is NEVER CONSTRUCTED — the branch is taken BEFORE any work, so the
+  // disarmed path reads no file, takes no lock and allocates nothing (INV-1).
+  const banditCfg = resolveBanditConfig(projectRoot, memCfg);
+  const banditCtxKey = contextKeyFor(opts.domain);
+  let banditReport: BanditRecallReport | undefined;
+  let banditExplored: readonly string[] = [];
   const enhance = (hits: readonly HybridHit[]): HybridHit[] => {
     const candidates = hits.map((h) => {
       const dzId = idOf(h.pattern);
       const rec = idToRecord.get(dzId);
       return { dzId, score: h.score, reinforcement: rec !== undefined ? readReinforcementState(rec) : undefined };
     });
+    if (banditCfg.enabled) {
+      // Quarantine read from the AUTHORITATIVE store records (idToRecord), never from mirror
+      // metadata — the mirror may lag a promotion; the store cannot (same rule as dampQuarantined).
+      const quarantined = new Set<string>();
+      for (const c of candidates) {
+        const rec = idToRecord.get(c.dzId);
+        if (rec !== undefined && readQuarantineState(rec).quarantined) quarantined.add(c.dzId);
+      }
+      // INV-3 / AC-3: with exploration disarmed a quarantined lesson is filtered out of the arm list
+      // BEFORE the engine is called, so it literally never learns that arm exists. (The ACL applies
+      // its own set-subtraction for the exploration lift as well — two independent gates, because
+      // this is the property ADR-003 says may only be weakened by an explicit request.)
+      const armKeys = candidates.map((c) => c.dzId).filter((id) => banditCfg.exploration || !quarantined.has(id));
+      const payoff = payoffTermsFor(projectRoot, banditCtxKey, armKeys, {
+        exploration: banditCfg.exploration,
+        quarantined,
+      });
+      const baseTerms: RerankTerm[] = deltaMap === undefined
+        ? []
+        : [{ id: 'delta', byIndex: candidates.map((c) => deltaMap.get(c.dzId) ?? 0), cap: REINFORCE_RRF_CAP }];
+      // The SAME ranking without the payoff term — the only honest way to say what the term moved.
+      const before = dampQuarantined(applyLearningSignalsWithTerms(hits, learning, candidates, REINFORCE_RRF_CAP, baseTerms));
+      const after = dampQuarantined(applyLearningSignalsWithTerms(hits, learning, candidates, REINFORCE_RRF_CAP, [
+        ...baseTerms,
+        // ADDED, never assigned, and pre-bounded to [-1,+1] by the ACL — so `squash` is identity and
+        // `cap` is an EXACT bound on this term's contribution (INV-4).
+        { id: 'bandit', byIndex: candidates.map((c) => payoff.terms.get(c.dzId)?.term ?? 0), cap: BANDIT_RRF_CAP, squash: (v) => v },
+      ]));
+      const beforeIds = before.map((h) => idOf(h.pattern));
+      const afterIds = after.map((h) => idOf(h.pattern));
+      const movedDzIds = afterIds.filter((id, i) => beforeIds[i] !== id);
+      banditExplored = payoff.explored;
+      banditReport = {
+        contextKey: banditCtxKey,
+        armsConsidered: armKeys.length,
+        quarantinedExcluded: candidates.length - armKeys.length,
+        unknownArms: payoff.unknownArms,
+        moved: movedDzIds.length,
+        exploration: banditCfg.exploration,
+        explored: payoff.explored.length,
+        reason: payoff.reason,
+        armDzIds: armKeys,
+        movedDzIds,
+        unknownDzIds: payoff.unknownDzIds,
+        exploredDzIds: payoff.explored,
+        beforeOrder: beforeIds,
+        afterOrder: afterIds,
+      };
+      return after;
+    }
     if (deltaMap !== undefined) {
       const deltaByIndex = candidates.map((c) => deltaMap.get(c.dzId) ?? 0);
       return dampQuarantined(applyLearningSignalsWithDelta(hits, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP));
     }
     return dampQuarantined(applyLearningSignals(hits, learning, candidates, REINFORCE_RRF_CAP));
   };
-  const lexicalOnly = (extra: Partial<Pick<HybridRecall, 'vectorEngine' | 'vectorReason' | 'vectorError'>>): HybridRecall => ({
-    hits: enhance(lexical.map((h, rank) => ({ pattern: h.pattern, backend: h.backend, score: 1 / (RRF_K + rank + 1) }))),
-    lexicalBackend,
-    vectorEngine: 'none',
-    semanticCandidates: 0,
-    semanticRanked: 0,
-    ...extra,
-  });
+  /** The exposure/telemetry payload for `markRecallHits` — `undefined` while disarmed (INV-1). */
+  const banditEmission = (): { readonly contextKey: string; readonly explored: readonly string[]; readonly moved: number; readonly arms: number; readonly deferred?: boolean } | undefined =>
+    banditReport === undefined
+      ? undefined
+      : {
+          contextKey: banditReport.contextKey, explored: banditExplored,
+          moved: banditReport.moved, arms: banditReport.armsConsidered,
+          ...(opts.deferExposures === true ? { deferred: true } : {}),
+        };
+  const lexicalOnly = (extra: Partial<Pick<HybridRecall, 'vectorEngine' | 'vectorReason' | 'vectorError'>>): HybridRecall => {
+    // `enhance` FIRST: it is what populates `banditReport` (the key is absent while disarmed).
+    const hits = enhance(lexical.map((h, rank) => ({ pattern: h.pattern, backend: h.backend, score: 1 / (RRF_K + rank + 1) })));
+    return {
+      hits,
+      lexicalBackend,
+      vectorEngine: 'none',
+      semanticCandidates: 0,
+      semanticRanked: 0,
+      ...extra,
+      ...(banditReport !== undefined ? { bandit: banditReport } : {}),
+      ...deferredCommit(),
+    };
+  };
+
+  /**
+   * The deferred-exposure commit, built ONCE and attached by EVERY return path.
+   *
+   * The first draft attached it only inside `lexicalOnly()` — the FALLBACK. On the main hybrid path
+   * (a vector engine present, i.e. the normal case) the field was absent, so `markRecallHits` had
+   * already returned early on `deferred: true` and NOTHING ever committed the exposures. MEASURED
+   * the same day: an armed recall printed `bandit payoff: … state absent` while `.dz/lesson-bandit/`
+   * was never created — the feature reported itself running while its reward feed was severed.
+   * A ranking feature that quietly stops ranking looks exactly like one that works; that sentence is
+   * in the vendored engine's own header, and the failure recurred one layer down anyway.
+   */
+  function deferredCommit(): { commitExposures?: (shownDzIds: readonly string[]) => void } {
+    return banditReport !== undefined && opts.deferExposures === true
+        ? {
+            /** Record exposures for the hits the caller actually PRINTED. Everything it needs is in
+             * the report plus the shown ids — no closure over the pre-cut hit list, so there is no
+             * way for this to disagree with `narrowBanditReport` about which list is being described. */
+            commitExposures: (shownDzIds: readonly string[]): void => {
+              const narrowed = narrowBanditReport(banditReport!, shownDzIds);
+              const ts2 = new Date().toISOString();
+              try {
+                recordExposures(
+                  projectRoot,
+                  shownDzIds.map((dzId) => ({ dzId, contextKey: narrowed.contextKey, ts: ts2 })),
+                  narrowed.exploredDzIds,
+                  { moved: narrowed.moved, arms: narrowed.armsConsidered },
+                );
+              } catch { /* a derived index never blocks the recall return (NFR-5) */ }
+            },
+          }
+        : {};
+  }
 
   if (mode === 'lexical') {
     const out = lexicalOnly({});
-    markRecallHits(projectRoot, learning, out.hits, idOf);
+    markRecallHits(projectRoot, learning, out.hits, idOf, banditEmission());
     return out;
   }
 
@@ -1067,12 +1280,12 @@ export async function recallHybrid(
     resolved = pickEngine(projectRoot, opts);
   } catch (err) {
     const out = lexicalOnly({ vectorReason: err instanceof Error ? err.message : String(err) });
-    markRecallHits(projectRoot, learning, out.hits, idOf);
+    markRecallHits(projectRoot, learning, out.hits, idOf, banditEmission());
     return out;
   }
   if (resolved.engine === undefined) {
     const out = lexicalOnly(resolved.reason !== undefined ? { vectorReason: resolved.reason } : {});
-    markRecallHits(projectRoot, learning, out.hits, idOf);
+    markRecallHits(projectRoot, learning, out.hits, idOf, banditEmission());
     return out;
   }
   const engine = resolved.engine;
@@ -1089,7 +1302,7 @@ export async function recallHybrid(
   if (sr.error !== undefined) {
     // The engine answered with an error, so nothing was returned and nothing ranked — both zero.
     const out = { ...lexicalOnly({}), vectorEngine: engine.kind, vectorError: sr.error };
-    markRecallHits(projectRoot, learning, out.hits, idOf);
+    markRecallHits(projectRoot, learning, out.hits, idOf, banditEmission());
     return out;
   }
 
@@ -1122,13 +1335,15 @@ export async function recallHybrid(
     backend: h.backend,
   }));
   const hits = enhance(mergeHybridHits(lex, semantic, { limit, semanticWeight: mode === 'semantic' ? 2 : 1 }));
-  markRecallHits(projectRoot, learning, hits, idOf);
+  markRecallHits(projectRoot, learning, hits, idOf, banditEmission());
   return {
     hits,
     lexicalBackend,
     vectorEngine: engine.kind,
     semanticCandidates: sr.hits.length,
     semanticRanked: semantic.length,
+    ...(banditReport !== undefined ? { bandit: banditReport } : {}),
+    ...deferredCommit(),
   };
 }