@dzhechkov/harness-core 0.7.10 → 0.7.12

package/src/patterns.ts

@@ -106,6 +106,24 @@ export interface MemoryLearningConfig {
   readonly quarantineDamp: number;
   /** Days after which an unreinforced quarantined lesson is an EXPIRY CANDIDATE (informational). */
   readonly quarantineExpireDays: number;
+  /**
+   * Bandit payoff re-rank (feature lesson-bandit-rerank, ADR-001). When true, recall adds a BOUNDED
+   * term derived from each lesson's measured payoff posterior — "has this lesson ever actually
+   * helped", the axis similarity cannot answer. ADDITIVE alongside {@link deltaRerank}, never a
+   * replacement, and capped at the same `REINFORCE_RRF_CAP`: similarity still decides WHICH lessons
+   * are candidates; the bandit only reorders WITHIN them. Default FALSE: absent config is
+   * byte-identical to today — no file read, no file written, no term applied.
+   */
+  readonly banditRerank: boolean;
+  /**
+   * Bandit EXPLORATION (feature lesson-bandit-rerank, ADR-003). When true, an arm with no evidence
+   * may receive a bounded trial lift so it can accumulate some. This deliberately weakens the
+   * view-does-not-promote posture, so it SHIPS DISARMED and is a separate flag: enabling payoff
+   * re-ranking must never silently mean "start surfacing unproven lessons". Quarantined lessons are
+   * NEVER explored in any configuration. Default FALSE; `true` with `banditRerank: false` is a
+   * warned no-op.
+   */
+  readonly banditExploration: boolean;
 }
 
 /**
@@ -141,10 +159,10 @@ export function readLearningConfig(projectRoot: string): LearningConfig {
 }
 
 export function readMemoryLearningConfig(projectRoot: string): MemoryLearningConfig {
-  const fallback: MemoryLearningConfig = { backend: 'native', onRecallHits: true, usesSat: 64, halfLifeDays: 30, reinforceThreshold: 0.95, deltaRerank: false, quarantine: false, quarantineDamp: 0.5, quarantineExpireDays: 30 };
+  const fallback: MemoryLearningConfig = { backend: 'native', onRecallHits: true, usesSat: 64, halfLifeDays: 30, reinforceThreshold: 0.95, deltaRerank: false, quarantine: false, quarantineDamp: 0.5, quarantineExpireDays: 30, banditRerank: false, banditExploration: false };
   try {
     const parsed = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8')) as {
-      memory?: { learning?: { backend?: string; onRecallHits?: boolean; usesSat?: number; halfLifeDays?: number; reinforceThreshold?: number; deltaRerank?: boolean; quarantine?: boolean; quarantineDamp?: number; quarantineExpireDays?: number } };
+      memory?: { learning?: { backend?: string; onRecallHits?: boolean; usesSat?: number; halfLifeDays?: number; reinforceThreshold?: number; deltaRerank?: boolean; quarantine?: boolean; quarantineDamp?: number; quarantineExpireDays?: number; banditRerank?: boolean; banditExploration?: boolean } };
     };
     const learning = parsed.memory?.learning ?? {};
     const backend = learning.backend === 'off' || learning.backend === 'ruvector-gnn' || learning.backend === 'native' ? learning.backend : 'native';
@@ -168,6 +186,11 @@ export function readMemoryLearningConfig(projectRoot: string): MemoryLearningCon
         typeof learning.quarantineExpireDays === 'number' && Number.isFinite(learning.quarantineExpireDays) && learning.quarantineExpireDays > 0
           ? Math.floor(learning.quarantineExpireDays)
           : fallback.quarantineExpireDays,
+      // Same `=== true` discipline as deltaRerank/quarantine: absent, null, "true" (a string), 1, or
+      // any legacy value ⇒ false. That is what makes "flag absent ⇒ byte-identical" true BY
+      // CONSTRUCTION rather than by care (ADR-001 R1).
+      banditRerank: learning.banditRerank === true,
+      banditExploration: learning.banditExploration === true,
     };
   } catch {
     return fallback;
@@ -574,16 +597,54 @@ export interface ReinforcePatternResult {
   readonly dzId?: string;
   readonly uses?: number;
   readonly error?: string;
+  /** The reward value actually observed for this reinforcement, clamped to [0,1]. */
+  readonly reward?: number;
 }
 
-export async function reinforcePattern(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean } = {}): Promise<ReinforcePatternResult> {
+export async function reinforcePattern(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean; domain?: string } = {}): Promise<ReinforcePatternResult> {
   // The WHOLE read-modify-write holds the store lock (finding 5): two concurrent
   // reinforces would otherwise both read uses=N and both write back N+1.
+  let result: ReinforcePatternResult;
   try {
-    return await withStoreLock(projectRoot, async () => reinforcePatternLocked(projectRoot, dzIdOrText, opts));
+    result = await withStoreLock(projectRoot, async () => reinforcePatternLocked(projectRoot, dzIdOrText, opts));
   } catch (err) {
     return { ok: false, error: lockErrorMessage(err) };
   }
+  // ── Bandit reward emission (feature lesson-bandit-rerank, ADR-001 D-5 / architecture §4) ──
+  //
+  // WHERE: here, in `reinforcePattern`, and NOT inside `reinforcePatternLocked` — that body runs
+  // under `withStoreLock`, and the bandit takes a DIFFERENT named lock. Lock nesting is AVOIDED,
+  // not managed: the bandit call is made after the store lock is released, from the result the
+  // locked section already returns. A crash between the two leaves the bandit one reward behind —
+  // a tolerable, self-correcting inconsistency for a ranking hint, and explicitly NOT tolerable for
+  // the store itself, which is why the store write is the one inside the lock.
+  //
+  // WHEN: only on the non-exposure branch — the SAME predicate that decides quarantine promotion
+  // eleven lines below. Hanging both on one predicate means the two can never disagree; the
+  // exposure≠reward distinction has ONE implementation, not two that must be kept in sync (INV-2).
+  //
+  // The store write is authoritative; the bandit is a derived index. Its failure is counted inside
+  // `recordReward` and can never fail a reinforce.
+  if (result.ok && result.dzId !== undefined && opts.exposure !== true) {
+    try {
+      if (readMemoryLearningConfig(projectRoot).banditRerank) {
+        // Dynamic import so the module is not even LOADED on the disarmed path (INV-1), and so
+        // patterns.ts keeps no static edge to a module that imports it.
+        const payoff = await import('./lesson-payoff.js');
+        const ev = payoff.makeRewardEvent(
+          result.dzId,
+          // HONEST LIMIT: a confirmation carries no memory of WHICH recall surfaced the lesson, so
+          // without an explicit `domain` the reward lands in the `general` bucket — the same bucket
+          // an undomained recall reads. A caller that knows the recall context should name it.
+          payoff.contextKeyFor(opts.domain),
+          result.reward ?? 1,
+          opts.ts ?? new Date().toISOString(),
+        );
+        if (ev !== null) payoff.recordReward(projectRoot, ev);
+      }
+    } catch { /* counted inside the payoff module; a derived index never fails a reinforce */ }
+  }
+  return result;
 }
 
 async function reinforcePatternLocked(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean }): Promise<ReinforcePatternResult> {
@@ -619,7 +680,7 @@ async function reinforcePatternLocked(projectRoot: string, dzIdOrText: string, o
   try {
     appendFileSync(join(projectRoot, '.dz', 'sessions.jsonl'), JSON.stringify({ event: 'reinforce', ts, dzId: rec.id, uses: nextState.uses }) + '\n');
   } catch { /* best-effort */ }
-  return { ok: true, dzId: rec.id, uses: nextState.uses };
+  return { ok: true, dzId: rec.id, uses: nextState.uses, reward: observed };
 }
 
 export async function updateReinforcementState(projectRoot: string, dzId: string, state: ReinforcementState): Promise<ReinforcePatternResult> {

package/src/project-skills-root.ts

@@ -0,0 +1,63 @@
+/**
+ * Which root does `dz project-skills` read the manifest from?
+ *
+ * Field report doc-25b (2026-08-25). The Step-0 probe in `feature-adr.js` and the `PS_GUIDANCE`
+ * paragraph handed to every design/code/qe stage BOTH hardcoded `cd <REPO> && dz project-skills`.
+ * On a run whose REPO is an external checkout, the manifest installed in the WORKSPACE was therefore
+ * unreachable: the probe answered `hasManifest:false`, the run recorded an honest `polymorphism:null`,
+ * and not one project lens reached any stage. Nothing failed loudly — the run just silently became
+ * generic. (How many lenses were lost on the reporting machine is NOT-ESTABLISHED — their workspace
+ * is not on this host. This repo's own manifest wires 4 injections from 3 files, which says what the
+ * blast radius looks like HERE and nothing about theirs. An earlier draft of this comment called their
+ * number "overstated" on the strength of that local measurement; measuring one manifest and reporting
+ * it as a verdict on a different one is the same error the reports themselves keep getting caught on.)
+ *
+ * The rule, symmetric with the doc-21 fix for the K2 gate:
+ *   probe the TARGET repo first — a repo's own conventions are authoritative for that repo —
+ *   and fall back to the workspace ONLY when the target has no manifest AND the workspace is a
+ *   genuinely different root.
+ *
+ * The choice is made in the SHELL by `grep -q`, never by the dispatched agent's judgment: a model
+ * asked to "pick the one that worked" is layer 4 on the cost-of-detection ladder, and this whole
+ * defect class is what layer 4 costs. One builder feeds both call sites so they cannot drift apart
+ * again — which is the actual bug the report describes, twice over.
+ */
+
+/**
+ * Shell-quote one argument. The root is spliced into a command string that an agent executes, and
+ * neither `assertAbsoluteNoTraversal` nor `checkArtifactRoot` rejects a space or a `$`. Unquoted, a
+ * workspace at `/tmp/space ws` silently relapsed into exactly this bug through a new door, and one at
+ * `/tmp/ws$(touch /tmp/PWNED)` EXECUTED the substitution — both MEASURED 2026-08-25 by the adversarial
+ * review of the first version of this file.
+ */
+function sq(s: string): string {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * The single-root form. Belt AND braces: it `cd`s to the root *and* names it with `--project`.
+ *
+ * `--project` alone would be enough for a current CLI — but `skills-feature-adr` ships this workflow
+ * to machines whose `dz` may predate the flag, and because the known-flag list is FLAT an old CLI
+ * accepts `--project` and ignores it. On such a CLI the bare `--project` form silently reads whatever
+ * the dispatched agent's cwd happens to be, which is strictly worse than the `cd` it replaced. With
+ * both, the command is correct on an old CLI (via the cd) and cwd-independent on a new one (via the
+ * flag), and the two can never disagree because they are built from the same `root`.
+ */
+export function projectSkillsOneRoot(dzBin: string, root: string): string {
+  return 'cd ' + sq(root) + ' && ' + dzBin + ' project-skills --project ' + sq(root) + ' --stages-json';
+}
+
+/**
+ * The command the Step-0 probe runs and the command `PS_GUIDANCE` tells each stage agent to run —
+ * necessarily the same string, or the stages fetch guidance from a root the probe never checked.
+ *
+ * `workspace` null / equal to `repo` ⇒ the plain single-root form (byte-identical to a run that has
+ * nowhere else to look), so the common workspace-CWD case pays nothing for this.
+ */
+export function projectSkillsProbeCommand(dzBin: string, repo: string, workspace?: string | null): string {
+  const primary = projectSkillsOneRoot(dzBin, repo);
+  if (workspace === null || workspace === undefined || workspace === repo) return primary;
+  return 'o=$(' + primary + ' 2>/dev/null); echo "$o" | grep -q \'"hasManifest":true\' || o=$('
+    + projectSkillsOneRoot(dzBin, workspace) + ' 2>/dev/null); echo "$o"';
+}

package/src/publish.ts

@@ -440,6 +440,12 @@ export function changelogRegion(lines: readonly string[]): Set<number> {
   const masked = maskFences(lines);
   const start = masked.findIndex((l) => ANY_ENTRY.test(l));
   if (start < 0) return out;
+  // REJECTED design, recorded so it is not retried: "sync the FIRST entry, protect the rest". It
+  // looks like it restores the lock-step for the current release, and it is unsafe in exactly the
+  // case that produced the bug — an author who bumps WITHOUT adding a new entry has the previous
+  // release's entry sitting first, and syncing it relabels that release's contents to the new
+  // version. The whole region stays protected; writing the newest heading is the author's job, and
+  // the prompt for it is that the version they type is the version they are about to publish.
   for (let i = start; i < masked.length; i++) {
     if (i > start && REGION_END.test(masked[i] as string)) break;
     out.add(i);

package/src/vector-tier.ts

@@ -74,7 +74,17 @@ 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';
+// 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 +229,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 +318,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)  */
@@ -979,11 +1008,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 +1059,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 +1110,120 @@ 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 } : {}),
+      ...(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 +1232,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 +1254,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 +1287,14 @@ 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 } : {}),
   };
 }