@dzhechkov/harness-core 0.3.128 → 0.3.129

package/src/patterns.ts

@@ -93,6 +93,18 @@ export interface MemoryLearningConfig {
    * ones nudge down. Default FALSE: absent config is byte-identical to the reinforce-only re-rank.
    */
   readonly deltaRerank: boolean;
+  /**
+   * Lesson quarantine (feature lesson-quarantine, ADR-001). When true, a freshly taught lesson is
+   * a HYPOTHESIS, not knowledge: marked `qStatus: 'quarantined'`, excluded from the auto-inject
+   * hook, damped + ⚠q-marked in interactive recall, and promoted only by an EARNED signal
+   * (reinforce or an explicit `dz recall --promote`). Default FALSE: absent config is
+   * byte-identical to today.
+   */
+  readonly quarantine: boolean;
+  /** Interactive-recall rank damp for quarantined hits, (0,1]; default 0.5. */
+  readonly quarantineDamp: number;
+  /** Days after which an unreinforced quarantined lesson is an EXPIRY CANDIDATE (informational). */
+  readonly quarantineExpireDays: number;
 }
 
 /**
@@ -128,10 +140,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 };
+  const fallback: MemoryLearningConfig = { backend: 'native', onRecallHits: true, usesSat: 64, halfLifeDays: 30, reinforceThreshold: 0.95, deltaRerank: false, quarantine: false, quarantineDamp: 0.5, quarantineExpireDays: 30 };
   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 } };
+      memory?: { learning?: { backend?: string; onRecallHits?: boolean; usesSat?: number; halfLifeDays?: number; reinforceThreshold?: number; deltaRerank?: boolean; quarantine?: boolean; quarantineDamp?: number; quarantineExpireDays?: number } };
     };
     const learning = parsed.memory?.learning ?? {};
     const backend = learning.backend === 'off' || learning.backend === 'ruvector-gnn' || learning.backend === 'native' ? learning.backend : 'native';
@@ -145,6 +157,16 @@ export function readMemoryLearningConfig(projectRoot: string): MemoryLearningCon
           ? learning.reinforceThreshold
           : fallback.reinforceThreshold,
       deltaRerank: learning.deltaRerank === true, // opt-in; absent/invalid ⇒ false (byte-identical to today)
+      quarantine: learning.quarantine === true, // opt-in (byte-identical to today when absent)
+      // Number.isFinite clamps (the recurring Infinity lesson): non-finite/out-of-range ⇒ default.
+      quarantineDamp:
+        typeof learning.quarantineDamp === 'number' && Number.isFinite(learning.quarantineDamp) && learning.quarantineDamp > 0 && learning.quarantineDamp <= 1
+          ? learning.quarantineDamp
+          : fallback.quarantineDamp,
+      quarantineExpireDays:
+        typeof learning.quarantineExpireDays === 'number' && Number.isFinite(learning.quarantineExpireDays) && learning.quarantineExpireDays > 0
+          ? Math.floor(learning.quarantineExpireDays)
+          : fallback.quarantineExpireDays,
     };
   } catch {
     return fallback;
@@ -386,6 +408,29 @@ export function recordToPattern(r: MemoryRecord): PatternRecord {
   };
 }
 
+/**
+ * Quarantine state of a learned record (feature lesson-quarantine, ADR-001). Carried in the SAME
+ * record metadata as reinforcement state — no schema migration, no second store. ABSENCE of the
+ * field = promoted (every pre-feature record is grandfathered), and AM-1 fail-safe points TOWARD
+ * knowledge: any unparseable/unknown `qStatus` reads as promoted — a metadata glitch must never
+ * isolate a proven lesson (the conservative side here is NOT quarantining).
+ */
+export interface QuarantineState {
+  readonly quarantined: boolean;
+  readonly quarantinedAt?: string;
+}
+
+export function readQuarantineState(r: MemoryRecord): QuarantineState {
+  const meta = r.metadata ?? {};
+  if (meta['qStatus'] !== 'quarantined') return { quarantined: false }; // AM-1 fail-safe
+  const at = typeof meta['quarantinedAt'] === 'string' ? meta['quarantinedAt'] : undefined;
+  return { quarantined: true, ...(at !== undefined ? { quarantinedAt: at } : {}) };
+}
+
+export function encodeQuarantineState(ts: string): Record<string, string> {
+  return { qStatus: 'quarantined', quarantinedAt: ts };
+}
+
 export interface ReinforcementState {
   readonly uses: number;
   readonly lastUsedTs?: string;
@@ -497,7 +542,7 @@ export interface ReinforcePatternResult {
   readonly error?: string;
 }
 
-export async function reinforcePattern(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[] } = {}): Promise<ReinforcePatternResult> {
+export async function reinforcePattern(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean } = {}): Promise<ReinforcePatternResult> {
   const records = loadStoreRecords(projectRoot);
   const rec = records.find((r) => r.id === dzIdOrText || r.text === dzIdOrText);
   if (rec === undefined) return { ok: false, error: `no learned pattern matches ${JSON.stringify(dzIdOrText)}` };
@@ -512,9 +557,18 @@ export async function reinforcePattern(projectRoot: string, dzIdOrText: string,
     avgReward,
     mergedFrom: [...prev.mergedFrom, ...(opts.mergedFrom ?? [])],
   };
+  // Reinforcement IS the earned promotion signal (FR-6a): CONFIRMING a lesson lifts quarantine.
+  // EXPOSURE (a recall-hit sample) is not confirmation — stats update, quarantine stays (the
+  // no-promotion-by-exposure invariant; found by cross-model QE as a live hole: recall-hit
+  // flushes were routed through this same function and silently promoted every viewed lesson).
+  const promotedMeta = { ...(rec.metadata ?? {}), ...encodeReinforcementState(nextState) };
+  if (opts.exposure !== true) {
+    delete promotedMeta['qStatus'];
+    delete promotedMeta['quarantinedAt'];
+  }
   const next: MemoryRecord = {
     ...rec,
-    metadata: { ...(rec.metadata ?? {}), ...encodeReinforcementState(nextState) },
+    metadata: promotedMeta,
   };
   const put = await putStoreRecord(projectRoot, next);
   if ('error' in put) return { ok: false, dzId: rec.id, error: put.error };
@@ -536,6 +590,99 @@ export async function updateReinforcementState(projectRoot: string, dzId: string
   return { ok: true, dzId, uses: state.uses };
 }
 
+/** Result of a promotion (dz recall --promote). */
+export interface PromoteResult {
+  readonly ok: boolean;
+  readonly promoted: readonly string[];
+  readonly notFound: readonly string[];
+  readonly notQuarantined: readonly string[];
+  readonly error?: string;
+}
+
+/**
+ * FR-6b: EXPLICIT promotion — lift quarantine from the named records. The other earned path is
+ * reinforcement ({@link reinforcePattern} clears the state as part of confirming the lesson).
+ * There is deliberately NO exposure-based auto-promotion: `uses` grows from recall HITS, and
+ * promoting by exposure would be a self-fulfilling prophecy (ADR).
+ */
+export async function promotePatterns(projectRoot: string, dzIds: readonly string[]): Promise<PromoteResult> {
+  const records = loadStoreRecords(projectRoot);
+  const promoted: string[] = [];
+  const notFound: string[] = [];
+  const notQuarantined: string[] = [];
+  for (const id of dzIds) {
+    const rec = records.find((r) => r.id === id);
+    if (rec === undefined) { notFound.push(id); continue; }
+    if (!readQuarantineState(rec).quarantined) { notQuarantined.push(id); continue; }
+    const meta = { ...(rec.metadata ?? {}) };
+    delete meta['qStatus'];
+    delete meta['quarantinedAt'];
+    const put = await putStoreRecord(projectRoot, { ...rec, metadata: meta });
+    if ('error' in put) return { ok: false, promoted, notFound, notQuarantined, error: put.error };
+    promoted.push(id);
+  }
+  return { ok: true, promoted, notFound, notQuarantined };
+}
+
+/** One quarantined-and-stale record, surfaced for review (informational — FR-7). */
+export interface QuarantineExpiryCandidate {
+  readonly dzId: string;
+  readonly text: string;
+  readonly quarantinedAt: string;
+  readonly ageDays: number;
+}
+
+/**
+ * FR-7 (informational-first, per the recalled decay-vs-noise lesson): quarantined records older
+ * than `expireDays` with ZERO reinforcement are EXPIRY CANDIDATES — reported, never auto-deleted.
+ * Deletion happens only through {@link pruneQuarantinePatterns} (explicit, snapshotted).
+ */
+export function quarantineExpiryCandidates(projectRoot: string, expireDays: number, now: Date = new Date()): QuarantineExpiryCandidate[] {
+  const out: QuarantineExpiryCandidate[] = [];
+  // Codex-QE fix (finding 6): the destructive API clamps its own input — a zero/negative/NaN
+  // expireDays would make FRESH lessons instantly deletable through the exported surface.
+  const days = Number.isFinite(expireDays) && expireDays > 0 ? expireDays : 30;
+  for (const r of loadStoreRecords(projectRoot)) {
+    const q = readQuarantineState(r);
+    if (!q.quarantined) continue;
+    // NO uses-based immunity (Codex-QE finding 1): a TRULY reinforced record is no longer
+    // quarantined at all (reinforce clears qStatus), so any uses on a still-quarantined record
+    // are EXPOSURE — and exposure must not immortalize a hypothesis.
+    const at = q.quarantinedAt ?? r.timestamp;
+    let ageMs = now.getTime() - new Date(at).getTime();
+    if (!Number.isFinite(ageMs)) ageMs = now.getTime() - new Date(r.timestamp).getTime(); // finding 7: fall back
+    if (!Number.isFinite(ageMs)) {
+      // Both timestamps corrupt: surface for human review (ageDays -1 renders as "?") — an
+      // unparseable age must not make the record IMMORTAL in quarantine (finding 7).
+      out.push({ dzId: r.id, text: r.text, quarantinedAt: at, ageDays: -1 });
+      continue;
+    }
+    const ageDays = ageMs / 86_400_000;
+    if (ageDays >= days) out.push({ dzId: r.id, text: r.text, quarantinedAt: at, ageDays: Math.floor(ageDays) });
+  }
+  return out;
+}
+
+/**
+ * Destructive half of expiry — a SEPARATE, explicit gate (never coupled to --prune-noise; AM-3).
+ * Dry-run by default; a live run snapshots the store first ({@link snapshotStore}) then removes
+ * exactly the expiry candidates via {@link removePatternsByIds}.
+ */
+export function pruneQuarantinePatterns(
+  projectRoot: string,
+  opts: { dryRun?: boolean; expireDays: number; now?: Date },
+): { candidates: QuarantineExpiryCandidate[]; removed: number; snapshot?: string; error?: string } {
+  const now = opts.now ?? new Date();
+  const candidates = quarantineExpiryCandidates(projectRoot, opts.expireDays, now);
+  if (opts.dryRun !== false || candidates.length === 0) return { candidates, removed: 0 };
+  // Snapshot BEFORE the drop; a failed snapshot ABORTS the deletion (the harmonize precedent —
+  // a destructive sweep with no receipt is exactly what the recalled decay lesson forbids).
+  const snap = snapshotStore(projectRoot, join(projectRoot, '.dz', `patterns-pre-prune-quarantine-${now.getTime()}.json`));
+  if (snap.error !== undefined) return { candidates, removed: 0, error: `aborted: ${snap.error}` };
+  const res = removePatternsByIds(projectRoot, new Set(candidates.map((c) => c.dzId)));
+  return { candidates, removed: res.removed, snapshot: snap.path, ...(res.error !== undefined ? { error: res.error } : {}) };
+}
+
 export interface StoreStats {
   readonly total: number;
   readonly perDomain: Record<string, number>;
@@ -703,13 +850,18 @@ function migrationRecords(projectRoot: string): MemoryRecord[] {
  * duplicates), so migrating JSON→SQLite never loses or doubles a record, and the
  * JSON file is never deleted. Returns the total record count after the write.
  */
-export async function recordPattern(projectRoot: string, p: PatternRecord): Promise<number> {
+export async function recordPattern(projectRoot: string, p: PatternRecord, opts: { quarantine?: boolean } = {}): Promise<number> {
   const { sqliteBackend } = readLearningConfig(projectRoot);
+  // lesson-quarantine: a fresh lesson is a HYPOTHESIS — mark it when the feature is on. Folded
+  // legacy records are NEVER marked (they predate the feature: grandfathered as promoted).
+  const rec = opts.quarantine === true
+    ? { ...patternToRecord(p), metadata: { ...patternToRecord(p).metadata, ...encodeQuarantineState(p.ts) } }
+    : patternToRecord(p);
   const sqlite = tryOpenSqlite(projectRoot, sqliteBackend);
   if (sqlite) {
     try {
       for (const r of migrationRecords(projectRoot)) await sqlite.put(r);
-      await sqlite.put(patternToRecord(p));
+      await sqlite.put(rec);
       return await sqlite.count();
     } finally {
       sqlite.close();
@@ -720,7 +872,7 @@ export async function recordPattern(projectRoot: string, p: PatternRecord): Prom
   for (const legacy of readJsonl(join(projectRoot, '.dz', 'patterns.jsonl'), isPatternRecord)) {
     await backend.put(patternToRecord(legacy));
   }
-  await backend.put(patternToRecord(p));
+  await backend.put(rec);
   await backend.save();
   return backend.count();
 }
@@ -735,6 +887,8 @@ export interface RecallHit {
    * emits them — it stays the sync lexical baseline, AC-5).
    */
   readonly backend: 'sqlite' | 'json' | 'vector' | 'both';
+  /** lesson-quarantine: set (true) only for a quarantined hit — display marks it ⚠q and ranking damps/sinks it. */
+  readonly quarantined?: boolean;
 }
 
 /**
@@ -749,21 +903,47 @@ export function recallPatterns(projectRoot: string, query: string, limit = 10):
     try {
       const db = SqliteBackend.open(sqlitePath(projectRoot));
       try {
-        return db.querySync({ text: query, limit }).map((r) => ({ pattern: recordToPattern(r), backend: 'sqlite' as const }));
+        return sinkQuarantined(
+          db.querySync({ text: query, limit: limit * 2 }).map((r) => ({
+            pattern: recordToPattern(r),
+            backend: 'sqlite' as const,
+            ...(readQuarantineState(r).quarantined ? { quarantined: true as const } : {}),
+          })),
+          limit,
+        );
       } finally {
         db.close();
       }
     } catch { /* fall through to JSON */ }
   }
   try {
-    return JsonFileBackend.openSync(storePath(projectRoot))
-      .querySync({ text: query, limit })
-      .map((r) => ({ pattern: recordToPattern(r), backend: 'json' as const }));
+    return sinkQuarantined(
+      JsonFileBackend.openSync(storePath(projectRoot))
+        .querySync({ text: query, limit: limit * 2 })
+        .map((r) => ({
+          pattern: recordToPattern(r),
+          backend: 'json' as const,
+          ...(readQuarantineState(r).quarantined ? { quarantined: true as const } : {}),
+        })),
+      limit,
+    );
   } catch {
     return [];
   }
 }
 
+/**
+ * Lexical recall has no numeric rank to damp, so quarantine "damping" is a STABLE sink: promoted
+ * hits keep their relative order first, quarantined hits follow (still VISIBLE — hiding them would
+ * make the loop a write-only log; ADR D2). Hybrid (scored) recall damps numerically instead.
+ */
+function sinkQuarantined<T extends { quarantined?: boolean }>(hits: readonly T[], limit?: number): T[] {
+  // Codex-QE finding 2: the query OVERFETCHES (2×limit) before sinking, so quarantined hits in
+  // the backend's top-K cannot crowd promoted knowledge out of the final window.
+  const sunk = [...hits.filter((h) => h.quarantined !== true), ...hits.filter((h) => h.quarantined === true)];
+  return limit !== undefined ? sunk.slice(0, limit) : sunk;
+}
+
 /* ------------------------------------------------------------------ */
 /*  Tier-2.5: session consolidation (harvestDreamPatterns)            */
 /* ------------------------------------------------------------------ */
@@ -1044,6 +1224,9 @@ export function pruneNoisePatterns(projectRoot: string, opts: { dryRun?: boolean
       const db = SqliteBackend.open(sqlitePath(projectRoot));
       try {
         for (const r of db.allSync()) {
+          // AM-3 (recalled decay-vs-noise lesson): a quarantined record is valid-but-unproven, not
+          // garbage — noise-prune must NEVER touch it; its lifecycle belongs to prune-quarantine.
+          if (readQuarantineState(r).quarantined) continue;
           if (isNoiseInsight(r.text)) {
             candidates.push({ id: r.id, text: r.text });
             if (!dryRun) db.removeSync(r.id);
@@ -1064,6 +1247,7 @@ export function pruneNoisePatterns(projectRoot: string, opts: { dryRun?: boolean
       const backend = JsonFileBackend.openSync(storePath(projectRoot));
       let removed = 0;
       for (const r of backend.allSync()) {
+        if (readQuarantineState(r).quarantined) continue; // AM-3: never coupled to noise-prune
         if (isNoiseInsight(r.text)) {
           if (!candidates.some((c) => c.id === r.id)) candidates.push({ id: r.id, text: r.text });
           if (!dryRun) backend.removeSync(r.id);

package/src/recall-hook-policy.ts

@@ -100,6 +100,8 @@ export interface HookCandidate {
   readonly pattern: string;
   readonly score: number;
   readonly domain?: string;
+  /** lesson-quarantine: an unproven hypothesis — the AUTO-INJECT surface excludes it (FR-5). */
+  readonly quarantined?: boolean;
 }
 
 export interface HookSelection {
@@ -107,6 +109,11 @@ export interface HookSelection {
   /** The floor that was applied — reported so the hook's own output can explain its silence. */
   readonly floor: number;
   readonly lang: QueryLang;
+  /**
+   * lesson-quarantine AM-2: how many candidates were dropped for being quarantined — the
+   * exclusion is OBSERVABLE (the hook logs it), never a silent shrink of the context.
+   */
+  readonly quarantinedExcluded: number;
 }
 
 /**
@@ -125,9 +132,14 @@ export function selectHookHits(
   const budget = intOr(opts.budgetChars, DEFAULT_RECALL_HOOK_BUDGET_CHARS);
 
   // A prompt with no intent gets no injection, whatever its cosine says.
-  if (!hasEnoughSignal(prompt)) return { hits: [], floor, lang };
+  if (!hasEnoughSignal(prompt)) return { hits: [], floor, lang, quarantinedExcluded: 0 };
+
+  // FR-5: the auto-inject surface is the STRICTEST — a quarantined lesson (unproven hypothesis)
+  // never rides into a prompt uninvited. Counted, not silent (AM-2).
+  const quarantinedExcluded = (candidates ?? []).filter((c) => c !== null && typeof c === 'object' && c.quarantined === true).length;
 
   const clean = (candidates ?? [])
+    .filter((c) => !(c !== null && typeof c === 'object' && c.quarantined === true))
     .filter(
       (c): c is HookCandidate =>
         c !== null &&
@@ -152,7 +164,7 @@ export function selectHookHits(
     hits.push(c);
     used += cost;
   }
-  return { hits, floor, lang };
+  return { hits, floor, lang, quarantinedExcluded };
 }
 
 function intOr(v: unknown, fallback: number): number {

package/src/vector-tier.ts

@@ -50,6 +50,7 @@ import {
   loadStoreRecords,
   readMemoryLearningConfig,
   readReinforcementState,
+  readQuarantineState,
   removePatternsByIds,
   snapshotStore,
   updateReinforcementState,
@@ -155,6 +156,8 @@ export interface HybridHit {
   readonly backend: RecallHit['backend'];
   /** Reciprocal-rank-fusion score (ranking only — NOT the pattern's reward). */
   readonly score: number;
+  /** lesson-quarantine: set only for a quarantined hit — display marks ⚠q, ranking was damped. */
+  readonly quarantined?: boolean;
 }
 
 /** Outcome of {@link recallHybrid}. With no engine this is content-identical to `recallPatterns`. */
@@ -336,7 +339,7 @@ export function isVectorNoise(text: string): boolean {
  * ACL: taught {@link PatternRecord} → {@link VectorEntry}. Returns `undefined` for noise (the
  * ingest gate — I-6). Score is the record's REAL reward, never a fabricated 1.0.
  */
-export function patternVectorEntry(p: PatternRecord, source = 'dz-teach'): VectorEntry | undefined {
+export function patternVectorEntry(p: PatternRecord, source = 'dz-teach', opts: { quarantined?: boolean } = {}): VectorEntry | undefined {
   if (isVectorNoise(p.pattern)) return undefined;
   const dzId = patternRecordId(p);
   return {
@@ -345,7 +348,9 @@ export function patternVectorEntry(p: PatternRecord, source = 'dz-teach'): Vecto
     score: p.reward,
     taskType: 'dz-teach',
     tags: ['dz-teach', p.type],
-    metadata: { dzId, source, ts: p.ts, domain: p.domain },
+    // FR-8: quarantine rides into the mirror so the HOOK DAEMON (which reads only the mirror's
+    // sqlite metadata) can exclude unproven lessons from auto-injection.
+    metadata: { dzId, source, ts: p.ts, domain: p.domain, ...(opts.quarantined === true ? { qStatus: 'quarantined' } : {}) },
   };
 }
 
@@ -790,7 +795,20 @@ export async function recallHybrid(
   const learning = resolveLearningBackend(projectRoot);
   // Phase 3: opt-in SAFLA-delta re-rank. The map is built ONCE per recall (off ⇒ undefined ⇒ the
   // reinforce-only path, byte-identical to today).
-  const deltaMap = readMemoryLearningConfig(projectRoot).deltaRerank ? lessonDeltaMap(projectRoot) : undefined;
+  const memCfg = readMemoryLearningConfig(projectRoot);
+  const deltaMap = memCfg.deltaRerank ? lessonDeltaMap(projectRoot) : undefined;
+  // lesson-quarantine: damp read from the AUTHORITATIVE store records (idToRecord), never from
+  // mirror metadata — the mirror may lag a promotion; the store cannot.
+  const dampQuarantined = (hits: readonly HybridHit[]): HybridHit[] => {
+    if (!memCfg.quarantine) return [...hits];
+    return hits
+      .map((h) => {
+        const rec = idToRecord.get(idOf(h.pattern));
+        const q = rec !== undefined && readQuarantineState(rec).quarantined;
+        return q ? { ...h, score: h.score * memCfg.quarantineDamp, quarantined: true as const } : h;
+      })
+      .sort((a, b) => b.score - a.score);
+  };
   const enhance = (hits: readonly HybridHit[]): HybridHit[] => {
     const candidates = hits.map((h) => {
       const dzId = idOf(h.pattern);
@@ -799,9 +817,9 @@ export async function recallHybrid(
     });
     if (deltaMap !== undefined) {
       const deltaByIndex = candidates.map((c) => deltaMap.get(c.dzId) ?? 0);
-      return applyLearningSignalsWithDelta(hits, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP);
+      return dampQuarantined(applyLearningSignalsWithDelta(hits, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP));
     }
-    return applyLearningSignals(hits, learning, candidates, 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) }))),