@dzhechkov/harness-core 0.7.11 → 0.8.1

package/src/patterns.ts

@@ -31,6 +31,7 @@ import { resolveAgentdbPath } from './agentdb-index.js';
 import type { VectorEntry } from './vector-tier.js';
 import { rankLessonsByDelta, type LessonHistory } from './safla-delta.js';
 import { withStoreLock, withStoreLockSync, StoreLockTimeoutError, StoreLockCompromisedError } from './store-lock.js';
+import { describeNativeDep, exerciseSqliteOpen, probeNativeDep } from './native-dep-probe.js';
 
 /** A learned pattern as written by `dz teach` to `.dz/patterns.jsonl`. */
 export interface PatternRecord {
@@ -106,6 +107,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 +160,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 +187,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 +598,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 +681,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> {
@@ -1211,7 +1273,11 @@ function countNoiseVectors(projectRoot: string): { removed: number; error?: stri
       db.close();
     }
   } catch (err) {
-    return { removed: 0, error: `vector mirror: ${err instanceof Error ? err.message : String(err)}` };
+    const verdict = probeNativeDep(projectRoot, 'better-sqlite3', exerciseSqliteOpen, 'sqlite-open');
+    const message = verdict.state === 'unusable'
+      ? describeNativeDep(verdict)
+      : err instanceof Error ? err.message : String(err);
+    return { removed: 0, error: `vector mirror: ${message}` };
   }
 }
 
@@ -1253,6 +1319,10 @@ function pruneNoiseVectors(projectRoot: string): { removed: number; error?: stri
       db.close();
     }
   } catch (err) {
+    const verdict = probeNativeDep(projectRoot, 'better-sqlite3', exerciseSqliteOpen, 'sqlite-open');
+    if (verdict.state === 'unusable') {
+      return { removed: 0, error: `vector mirror: ${describeNativeDep(verdict)}` };
+    }
     return { removed: 0, error: `vector prune failed: ${err instanceof Error ? err.message : String(err)}` };
   }
 }