@dzhechkov/harness-core 0.3.90 → 0.3.94

package/src/brain.ts

@@ -207,6 +207,36 @@ export function readBookKus(opts: {
   }
 }
 
+/**
+ * Exact by-kuId FULL-content lookup over the brain's lexical store (`brainBooksPath(home)` by
+ * default) — the by-id reader behind `dz brain expand <kuId>` (brain-ground-expand Tier 1) and the
+ * worth-enrichment pass of the budgeted-eager grounding path. Reuses the audited {@link readBookKus}
+ * primitive (shared require-path resolution, schema detection, error surfacing), then filters by
+ * `kuId`, returning the reconstructed {@link BookKU} with its whole `content` (never a snippet).
+ *
+ * Best-effort and deterministic: a missing store, unknown kuId, or dependency error returns
+ * `{ error }`, never throws. `source` narrows the scan to one book slug (saves a full-table scan on a
+ * large brain); omit to search all sources.
+ */
+export function expandKu(opts: {
+  kuId: string;
+  brainHome?: string;
+  depsRoot?: string;
+  source?: string;
+}): { ku?: BookKU; error?: string } {
+  const home = opts.brainHome ?? brainHome();
+  const storePath = brainBooksPath(home);
+  const res = readBookKus({
+    storePath,
+    ...(opts.depsRoot !== undefined ? { depsRoot: opts.depsRoot } : {}),
+    ...(opts.source !== undefined ? { source: opts.source } : {}),
+  });
+  if (res.error !== undefined) return { error: res.error };
+  const ku = res.kus.find((k) => k.kuId === opts.kuId);
+  if (ku === undefined) return { error: `kuId not found: ${opts.kuId}` };
+  return { ku };
+}
+
 /**
  * The vector primitive is insert-only, so before re-indexing a book we delete its existing brain
  * vector rows — mirroring the reindex approach. Best-effort: a missing store/table is a no-op.
@@ -1077,11 +1107,36 @@ function snippet(s: string, max = 160): string {
   return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
 }
 
+/**
+ * Approximate token count for `s`. ASCII/Latin ≈ chars/4, but CYRILLIC — the brain's primary KU
+ * language — costs ~2 tokens/char under multilingual tokenizers, so a plain chars/4 UNDERCOUNTS
+ * Russian content and lets `--budget N` OVERSHOOT the real token budget. We count Cyrillic at chars/2
+ * and the rest at chars/4; OVERESTIMATING is the safe direction for a soft ceiling (inlines slightly
+ * less, never more). Used only by the budgeted-eager grounding path; never on the default hot path.
+ */
+function approxTokens(s: string): number {
+  const cyrillic = (s.match(/[Ѐ-ӿ]/g) || []).length;
+  return Math.ceil((s.length - cyrillic) / 4 + cyrillic / 2);
+}
+
 /** The directive line prepended to every grounding block (§7.1). */
 const GROUNDING_DIRECTIVE =
   'Ground your answer in the KNOWLEDGE BRAIN below; prefer these ingested sources over ' +
   'training-data recall; cite [Kn] source+page per claim; if the brain is silent on a point, say so.';
 
+/**
+ * Expand-capable variant of the grounding directive (brain-ground-expand Tier 1/2). Used ONLY when
+ * `contentBudget > 0`; the default (no-budget) path keeps {@link GROUNDING_DIRECTIVE} byte-identical.
+ * Augments the base directive with a model instruction: each citation carries its `kuId` as the first
+ * field, and the model can pull a KU's FULL content ON DEMAND by running `dz brain expand <kuId>` —
+ * so it expands only the KUs it actually needs (latency paid only on real use).
+ */
+const GROUNDING_DIRECTIVE_EXPAND =
+  'Ground your answer in the KNOWLEDGE BRAIN below; prefer these ingested sources over ' +
+  'training-data recall; cite [Kn] source+page per claim; if the brain is silent on a point, say so. ' +
+  "Each citation shows its kuId as the first field — to read a KU's FULL content on demand, run " +
+  '`dz brain expand <kuId>`; expand only the KUs you actually need.';
+
 /**
  * The grounding-enforcement hook entrypoint (ADR-001 §7, P1). Given a user prompt, deterministically
  * builds a GROUNDING DIRECTIVE block from the brain's top lexical hits — the mechanical half of
@@ -1105,6 +1160,12 @@ export async function groundPrompt(opts: {
   depsRoot?: string;
   k?: number;
   source?: string;
+  /**
+   * brain-ground-expand: approximate token budget (chars/4) for EAGERLY inlining full KU `content`
+   * into the block, worth-ranked. `undefined`/`0` ⇒ the byte-identical pointer-only default (Tier 0);
+   * `> 0` ⇒ the expand-capable block (Tier 1/2) with full content inlined for the top-K KUs that fit.
+   */
+  contentBudget?: number;
 }): Promise<{ emitted: boolean; block: string; hitCount: number; error?: string }> {
   const silent = { emitted: false, block: '', hitCount: 0 } as const;
   try {
@@ -1158,13 +1219,75 @@ export async function groundPrompt(opts: {
       if (covered < 2 && semanticHits.length === 0) return silent;
     }
 
-    // Build the GROUNDING DIRECTIVE block (§7.1): directive line + numbered citations.
-    const lines: string[] = [GROUNDING_DIRECTIVE, ''];
+    // ── Tier 0: DEFAULT (backward-compatible pointer block) ────────────────────────────────────
+    // No budget ⇒ the exact block emitted before brain-ground-expand, byte-identical (property a).
+    // `!opts.contentBudget` covers both `undefined` and `0` (--budget 0 ≡ no budget, FR-03.6).
+    if (!opts.contentBudget) {
+      // Build the GROUNDING DIRECTIVE block (§7.1): directive line + numbered citations.
+      const lines: string[] = [GROUNDING_DIRECTIVE, ''];
+      merged.forEach((h, i) => {
+        const ch = h.chapter !== undefined && h.chapter !== '' ? ` гл.${h.chapter}` : '';
+        const pg = h.pages !== undefined && h.pages.length > 0 ? ` с.${h.pages.join('–')}` : '';
+        const body = snippet(h.problem !== '' ? h.problem : h.content);
+        lines.push(`[K${i + 1}] ${h.book}${ch}${pg} — ${h.name}: ${body}`);
+      });
+      return { emitted: true, block: lines.join('\n'), hitCount: merged.length };
+    }
+
+    // ── Tier 1/2: BUDGETED EAGER (contentBudget > 0) — inside the try/catch so any bug in ranking /
+    // budgeting falls back to `silent` and NEVER errors the prompt (property e). Content is already
+    // in-hand on every hit; budgeting only chooses what to RENDER (no extra retrieval).
+
+    // Enrich hits with declared worth for ranking — BookKUHit drops `metadata`, so recover it by a
+    // by-kuId lookup. HONEST PERF NOTE: each expandKu re-reads the books store, so this is k FULL-store
+    // reads (NOT a metadata-only pass) — fine at the top-K scale here (k≤~5, small brain); if k grows,
+    // pre-load readBookKus once into a kuId→metadata map. Absent worth ⇒ worthScore's 0.5 default.
+    type RankedHit = { hit: BookKUHit; worth: number; rank: number };
+    const rankedHits: RankedHit[] = merged.map((h, i) => {
+      const expanded = expandKu({
+        kuId: h.kuId,
+        ...(opts.brainHome !== undefined ? { brainHome: opts.brainHome } : {}),
+        ...(opts.depsRoot !== undefined ? { depsRoot: opts.depsRoot } : {}),
+        ...(opts.source !== undefined ? { source: opts.source } : {}),
+      });
+      const worth = expanded.ku !== undefined ? worthScore(expanded.ku.metadata ?? {}) : 0.5;
+      return { hit: h, worth, rank: i }; // rank = merge/rerank position (lower = more on-point)
+    });
+    // Rank: worth desc → similarity/rerank-order (rank) asc → kuId asc (stable, deterministic).
+    rankedHits.sort((a, b) => b.worth - a.worth || a.rank - b.rank || a.hit.kuId.localeCompare(b.hit.kuId));
+
+    // Greedy budget fill: inline a KU's full content ONLY if it fits the remaining budget; the first
+    // KU that would overflow stops the fill (property c: hard ceiling, atomic KUs — never partial).
+    let tokensBudgeted = 0;
+    const inlineSet = new Set<string>();
+    for (const { hit } of rankedHits) {
+      if (hit.content === '') continue; // empty content → stays a pointer (zero-token)
+      const cost = approxTokens(hit.content);
+      if (tokensBudgeted + cost <= opts.contentBudget) {
+        inlineSet.add(hit.kuId);
+        tokensBudgeted += cost;
+      } else {
+        break; // stop at first overflow (stop-don't-skip policy, FR-03.4)
+      }
+    }
+
+    // Emit the expand-capable block: directive names `dz brain expand <kuId>`; every citation exposes
+    // its kuId (property b). Chosen KUs get full content inlined; the rest stay pointers.
+    const lines: string[] = [GROUNDING_DIRECTIVE_EXPAND, ''];
     merged.forEach((h, i) => {
       const ch = h.chapter !== undefined && h.chapter !== '' ? ` гл.${h.chapter}` : '';
       const pg = h.pages !== undefined && h.pages.length > 0 ? ` с.${h.pages.join('–')}` : '';
-      const body = snippet(h.problem !== '' ? h.problem : h.content);
-      lines.push(`[K${i + 1}] ${h.book}${ch}${pg} — ${h.name}: ${body}`);
+      const header = `[K${i + 1}] ${h.kuId} · ${h.book}${ch}${pg} — ${h.name}`;
+      if (inlineSet.has(h.kuId) && h.content !== '') {
+        // Inlined full content (budget allocated) — content supersedes the snippet suffix.
+        lines.push(header);
+        lines.push(h.content);
+        lines.push(''); // blank separator between KUs for readability
+      } else {
+        // Pointer with kuId annotation; the model can expand this one on demand.
+        const body = snippet(h.problem !== '' ? h.problem : h.content);
+        lines.push(`${header}: ${body}`);
+      }
     });
     return { emitted: true, block: lines.join('\n'), hitCount: merged.length };
   } catch {

package/src/feature-adr-routing.ts

@@ -33,6 +33,12 @@ export interface StageOpts {
   readonly agentType?: string;
   readonly codexModel?: string;
   readonly _reasoning?: string;
+  /**
+   * Observability marker set ONLY when the usage-adaptive override chose this stage's codex spec
+   * (not on a user's explicit codex routing). `modelLabel` appends ` (usage-switched)` when present
+   * so the switch is auditable in `modelsUsed` (AC-6).
+   */
+  _usageSwitched?: boolean;
 }
 
 /** The knobs `resolveStageModel` closes over — passed in from the workflow. */
@@ -55,6 +61,124 @@ export interface RoutingEnv {
   readonly codexAvailable?: boolean;
   /** Optional log sink (the workflow passes its `log`); defaults to a no-op. */
   readonly log?: (msg: string) => void;
+  /**
+   * USAGE-ADAPTIVE override bit (env-threaded, non-global — LOCKED L-5). When true,
+   * `resolveStageModel` routes ALL stages to `codex:<topCodexId>` REGARDLESS of `MODELS`/knobs.
+   * The single mutable `let usageOverride` lives ONLY in the workflow script; the library stays
+   * pure — the state travels through THIS field, never a module-level global. Absent/undefined ⇒
+   * byte-identical resolution to the pre-feature behavior (NFR-2 / AC-4).
+   */
+  readonly usageOverride?: boolean;
+  /**
+   * Per-stage reasoning for the usage-override spec (merged OVER {@link OVERRIDE_REASONING}).
+   * `args.usageReasoning` — stage → `'high'|'xhigh'|…`; a single stage may be overridden without
+   * touching the others.
+   */
+  readonly usageReasoning?: Record<string, string>;
+}
+
+// ── USAGE-ADAPTIVE ROUTING (pre-emptive codex switch at >= usageThreshold) ────
+
+/** A probe reading. `null` on a pct ⇔ that limit is unconfigured (unknown — never a guess). */
+export interface UsageSignal {
+  readonly sessionPct: number | null;
+  readonly weeklyPct: number | null;
+}
+
+/**
+ * The LOCKED 6-value action vocabulary (L-1). `decideUsageAction` emits the first five (probe
+ * path); `'reactive-switch'` is pushed only by the workflow's belt sites — one shared type, no
+ * parallel enums.
+ */
+export type UsageAction =
+  | 'none'
+  | 'switch'
+  | 'restore'
+  | 'keep'
+  | 'fail-safe-switch'
+  | 'reactive-switch';
+
+/** The `decideUsageAction` verdict: the new override bit + the event action. */
+export interface UsageDecision {
+  readonly override: boolean;
+  readonly action: UsageAction;
+}
+
+/**
+ * Per-stage reasoning applied under the usage override (LOCKED L-4, arch §4.1 verbatim):
+ * design/code/plan stages ⇒ `xhigh`; router/qe/fleet ⇒ `high`. A pure DATA table (not control
+ * flow); user-overridable via `env.usageReasoning`. An unknown stage falls back to `'high'`.
+ */
+export const OVERRIDE_REASONING: Record<string, 'high' | 'xhigh'> = {
+  router: 'high',
+  requirements: 'xhigh',
+  research: 'xhigh',
+  adr: 'xhigh',
+  ideation: 'xhigh',
+  ddd: 'xhigh',
+  architecture: 'xhigh',
+  plan: 'xhigh',
+  code: 'xhigh',
+  qe: 'high',
+  fleet: 'high',
+};
+
+/**
+ * The gpt-5.6-ready TOP codex-id pick — SHARED by the cross-model QE default and the usage
+ * override so adding an id to {@link KNOWN_CODEX} (e.g. `gpt-5.7`) retargets BOTH with zero
+ * control-flow diff (AC-3). Pinned `CODEX_MODEL` when ≠ `'auto'`; else the last non-`auto` key of
+ * `KNOWN_CODEX`.
+ */
+export function topCodexId(env: RoutingEnv): string {
+  let top = env.CODEX_MODEL;
+  if (top === 'auto') {
+    const ids = Object.keys(KNOWN_CODEX);
+    for (let i = 0; i < ids.length; i++) {
+      if (ids[i] !== 'auto') top = ids[i] || top;
+    }
+  }
+  return top;
+}
+
+/**
+ * The PURE hysteresis core (the load-bearing safety property, AC-1). Given the previous override
+ * bit, a probe signal (or `null` when the probe agent itself DIED), and the threshold, decide the
+ * new override bit + the event action. Total function — no input throws or returns an
+ * out-of-vocabulary action.
+ *
+ * The load-bearing asymmetry (INV-2):
+ *   - **agent-null** (`signal === null`, the probe dispatch died — OFTEN MEANS limits) ⇒ fail-safe
+ *     switch TO codex (OFF→ON), or `keep` if already overridden.
+ *   - **value-null** (a pct is `null` — limits unconfigured / garbled) ⇒ flips NOTHING: never
+ *     switches a fresh run to codex AND never restores an active override (unknown ⇒ hysteresis, no
+ *     flapping).
+ *   - `>= threshold` on EITHER known metric ⇒ switch (OFF→ON) / keep (ON stays ON). Boundary `= 70`
+ *     counts as over (`>=`).
+ *   - ONLY a positive BOTH-below reading (both pcts known and `< threshold`) clears an override
+ *     (`restore`); from OFF it is `none`.
+ *
+ * Non-finite pcts (`NaN`, negatives from a garbled probe) are treated as value-null.
+ */
+export function decideUsageAction(
+  prevOverride: boolean,
+  signal: UsageSignal | null,
+  threshold: number,
+): UsageDecision {
+  if (signal === null || signal === undefined) {
+    if (prevOverride) return { override: true, action: 'keep' };
+    return { override: true, action: 'fail-safe-switch' };
+  }
+  const s = signal.sessionPct;
+  const w = signal.weeklyPct;
+  const sKnown = typeof s === 'number' && isFinite(s) && s >= 0;
+  const wKnown = typeof w === 'number' && isFinite(w) && w >= 0;
+  if ((sKnown && s >= threshold) || (wKnown && w >= threshold)) {
+    return { override: true, action: prevOverride ? 'keep' : 'switch' };
+  }
+  if (sKnown && wKnown) {
+    return { override: false, action: prevOverride ? 'restore' : 'none' };
+  }
+  return { override: prevOverride, action: prevOverride ? 'keep' : 'none' };
 }
 
 // ── Data tables (data-only extensibility — gpt-5.6-ready) ───────────────────
@@ -147,14 +271,7 @@ export function resolveQeSpec(env: RoutingEnv): string {
   if (coderIsCodex(env)) return 'opus';
   const CODEX_AVAILABLE = env.codexAvailable !== false;
   if (!CODEX_AVAILABLE) return 'opus';
-  let top = env.CODEX_MODEL;
-  if (top === 'auto') {
-    const ids = Object.keys(KNOWN_CODEX);
-    for (let i = 0; i < ids.length; i++) {
-      if (ids[i] !== 'auto') top = ids[i] || top;
-    }
-  }
-  return 'codex:' + top + ':high';
+  return 'codex:' + topCodexId(env) + ':high';
 }
 
 /**
@@ -201,6 +318,12 @@ export function qeShouldUseCodex(env: RoutingEnv): boolean {
  *   4. `code`/`qe` `null` sentinels resolve via the coder / cross-model rules
  */
 export function resolveStageModel(stage: string, env: RoutingEnv): StageOpts {
+  if (env.usageOverride) {
+    const r = (env.usageReasoning && env.usageReasoning[stage]) || OVERRIDE_REASONING[stage] || 'high';
+    const o = specToOpts('codex:' + topCodexId(env) + ':' + r, env);
+    o._usageSwitched = true;
+    return o;
+  }
   let spec = env.MODELS[stage];
   if (spec === undefined) {
     if (!routingRequested(env)) return {};

package/src/index.ts

@@ -27,11 +27,14 @@ export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
 export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs } from './registry.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
-export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore } from './patterns.js';
-export type { PatternRecord, SessionRecord, LearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult } from './patterns.js';
+export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats } from './patterns.js';
+export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats } from './patterns.js';
+export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend } from './learning-backend.js';
+export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode } from './learning-backend.js';
 export {
   DEFAULT_VECTOR_TIMEOUT_MS,
   DEFAULT_HARMONIZE_THRESHOLD,
+  REINFORCE_RRF_CAP,
   withVectorTimeout,
   isVectorNoise,
   patternVectorEntry,
@@ -46,6 +49,7 @@ export {
   backfillVectorMirror,
   mergeHybridHits,
   recallHybrid,
+  teachGuard,
   vectorTierStatus,
   reindexVectorStore,
   harmonizeVectorStore,
@@ -74,11 +78,12 @@ export type {
   ImportReport,
   ImportOptions,
   ReindexVectorReport,
+  TeachGuardResult,
 } from './vector-tier.js';
 export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION } from './setup.js';
 export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStatePath } from './statusline.js';
 export type { StatuslineData, FeatureAdrState, WriteFeatureAdrStateInput } from './statusline.js';
-export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows } from './agentdb-index.js';
+export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';
 export { DEFAULT_EMBED_MODEL, LEGACY_EMBED_MODEL, DEFAULT_EMBED_DIM, KNOWN_EMBED_DIMS, resolveEmbedModel, readEmbedManifest, writeEmbedManifest, embedManifestPath, legacyEmbedManifest } from './embedding-config.js';
 export type { EmbedModelConfig, EmbedModelSource, EmbedManifest } from './embedding-config.js';
@@ -99,6 +104,7 @@ export {
   reindexBrainVectors,
   rerankHits,
   groundPrompt,
+  expandKu,
   buildPrimer,
   writePrimer,
   readBookKus,
@@ -178,5 +184,10 @@ export {
   DEFAULT_MODELS,
   KNOWN_CODEX,
   CLAUDE_NAMES,
+  topCodexId,
+  decideUsageAction,
+  OVERRIDE_REASONING,
 } from './feature-adr-routing.js';
-export type { StageOpts, RoutingEnv } from './feature-adr-routing.js';
+export type { StageOpts, RoutingEnv, UsageSignal, UsageAction } from './feature-adr-routing.js';
+export { computeUsage, readUsageLimits } from './usage.js';
+export type { UsageEstimate, UsageLimits } from './usage.js';

package/src/learning-backend.ts

@@ -0,0 +1,202 @@
+import { writeFileSync } from 'node:fs';
+
+import {
+  readMemoryLearningConfig,
+  readReinforcementState,
+  reinforcePattern,
+  type ReinforcementState,
+  type MemoryLearningConfig,
+} from './patterns.js';
+
+export const DEFAULT_REINFORCE_THRESHOLD = 0.95;
+
+export type LearningBackendMode = 'native' | 'off' | 'ruvector-gnn';
+export type LearningSampleKind = 'recall-hit' | 'reinforce' | 'merge';
+
+export interface SignalCandidate {
+  readonly dzId: string;
+  readonly score: number;
+  readonly reinforcement?: ReinforcementState | undefined;
+}
+
+export interface EnhanceContext {
+  readonly kind: 'recall' | 'recommend';
+  readonly now?: number;
+  readonly cap?: number;
+}
+
+export interface LearningSample {
+  readonly dzId: string;
+  readonly kind: LearningSampleKind;
+  readonly reward?: number;
+  readonly ts: string;
+}
+
+export interface TrainingResult {
+  readonly trained: boolean;
+  readonly flushed: number;
+  readonly failed: number;
+  readonly error?: string;
+}
+
+export interface LearningSignalStats {
+  readonly enabled: boolean;
+  readonly backend: string;
+  readonly samplesCollected: number;
+  readonly lastTrainingTime: number | null;
+  readonly flushedTotal: number;
+  readonly failedTotal: number;
+  readonly advisory?: string;
+}
+
+export interface LearningSignalBackend {
+  enhance(candidates: readonly SignalCandidate[], ctx: EnhanceContext): Float32Array;
+  addSample(sample: LearningSample): void;
+  train(opts?: { readonly maxMs?: number }): Promise<TrainingResult>;
+  clearSamples(): void;
+  saveModel(path: string): Promise<void>;
+  loadModel(path: string): Promise<void>;
+  getStats(): LearningSignalStats;
+  reset(): void;
+}
+
+export function isLearningSignalBackend(v: unknown): v is LearningSignalBackend {
+  if (typeof v !== 'object' || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return ['enhance', 'addSample', 'train', 'clearSamples', 'saveModel', 'loadModel', 'getStats', 'reset']
+    .every((k) => typeof o[k] === 'function');
+}
+
+export class NoopLearningBackend implements LearningSignalBackend {
+  enhance(candidates: readonly SignalCandidate[]): Float32Array {
+    return new Float32Array(candidates.length);
+  }
+  addSample(): void { /* no-op kill switch */ }
+  async train(): Promise<TrainingResult> { return { trained: false, flushed: 0, failed: 0 }; }
+  clearSamples(): void { /* no-op */ }
+  async saveModel(path: string): Promise<void> {
+    writeFileSync(path, JSON.stringify({ backend: 'off', note: 'NoopLearningBackend has no model state' }, null, 2));
+  }
+  async loadModel(): Promise<void> { /* no-op */ }
+  getStats(): LearningSignalStats {
+    return { enabled: false, backend: 'off', samplesCollected: 0, lastTrainingTime: null, flushedTotal: 0, failedTotal: 0 };
+  }
+  reset(): void { /* no-op */ }
+}
+
+export class NativeReinforcementBackend implements LearningSignalBackend {
+  private readonly samples: LearningSample[] = [];
+  private flushedTotal = 0;
+  private failedTotal = 0;
+  private lastTrainingTime: number | null = null;
+
+  constructor(
+    private readonly projectRoot: string,
+    private readonly opts: { readonly usesSat: number; readonly halfLifeDays: number; readonly advisory?: string } = { usesSat: 64, halfLifeDays: 30 },
+  ) {}
+
+  enhance(candidates: readonly SignalCandidate[], ctx: EnhanceContext): Float32Array {
+    const out = new Float32Array(candidates.length);
+    const now = ctx.now ?? Date.now();
+    for (let i = 0; i < candidates.length; i += 1) {
+      const st = candidates[i]!.reinforcement;
+      out[i] = st === undefined ? 0 : this.signal(st, now);
+    }
+    return out;
+  }
+
+  addSample(sample: LearningSample): void {
+    this.samples.push(sample);
+  }
+
+  async train(): Promise<TrainingResult> {
+    const batch = this.samples.splice(0);
+    let flushed = 0;
+    let failed = 0;
+    let error: string | undefined;
+    for (const sample of batch) {
+      const r = await reinforcePattern(this.projectRoot, sample.dzId, {
+        ts: sample.ts,
+        ...(sample.reward !== undefined ? { reward: sample.reward } : {}),
+      });
+      if (r.ok) flushed += 1;
+      else {
+        failed += 1;
+        error = r.error;
+      }
+    }
+    this.flushedTotal += flushed;
+    this.failedTotal += failed;
+    this.lastTrainingTime = Date.now();
+    return { trained: batch.length > 0, flushed, failed, ...(error !== undefined ? { error } : {}) };
+  }
+
+  clearSamples(): void {
+    this.samples.splice(0);
+  }
+
+  async saveModel(path: string): Promise<void> {
+    writeFileSync(path, JSON.stringify({ backend: 'native', note: 'state lives in .dz/memory records' }, null, 2));
+  }
+  async loadModel(): Promise<void> { /* native state lives in the store */ }
+
+  getStats(): LearningSignalStats {
+    return {
+      enabled: true,
+      backend: 'native',
+      samplesCollected: this.samples.length,
+      lastTrainingTime: this.lastTrainingTime,
+      flushedTotal: this.flushedTotal,
+      failedTotal: this.failedTotal,
+      ...(this.opts.advisory !== undefined ? { advisory: this.opts.advisory } : {}),
+    };
+  }
+
+  reset(): void {
+    this.samples.splice(0);
+    this.flushedTotal = 0;
+    this.failedTotal = 0;
+    this.lastTrainingTime = null;
+  }
+
+  private signal(state: ReinforcementState, now: number): number {
+    if (state.uses <= 0) return 0;
+    const usesSat = Math.max(2, this.opts.usesSat);
+    const freq = Math.min(1, Math.log1p(state.uses) / Math.log1p(usesSat));
+    const t = state.lastUsedTs !== undefined ? Date.parse(state.lastUsedTs) : Number.NaN;
+    const halfLifeMs = Math.max(1, this.opts.halfLifeDays) * 86_400_000;
+    const age = Number.isFinite(t) ? Math.max(0, now - t) : halfLifeMs;
+    const recency = 0.5 + 0.5 * Math.exp(-age / halfLifeMs);
+    return Math.max(0, Math.min(1, freq * recency));
+  }
+}
+
+export function resolveLearningBackend(projectRoot: string, config: MemoryLearningConfig = readMemoryLearningConfig(projectRoot)): LearningSignalBackend {
+  try {
+    const cfg = config;
+    if (cfg.backend === 'off') return new NoopLearningBackend();
+    const advisory = cfg.backend === 'ruvector-gnn'
+      ? 'memory.learning.backend="ruvector-gnn" is reserved; falling back to native reinforcement'
+      : undefined;
+    return new NativeReinforcementBackend(projectRoot, {
+      usesSat: cfg.usesSat,
+      halfLifeDays: cfg.halfLifeDays,
+      ...(advisory !== undefined ? { advisory } : {}),
+    });
+  } catch {
+    return new NativeReinforcementBackend(projectRoot);
+  }
+}
+
+export function applyLearningSignals<H extends { readonly score: number }>(
+  hits: readonly H[],
+  backend: LearningSignalBackend,
+  candidates: readonly SignalCandidate[],
+  cap: number,
+): H[] {
+  const signals = backend.enhance(candidates, { kind: 'recall', cap });
+  return hits
+    .map((hit, i) => ({ hit, adjusted: hit.score + cap * (signals[i] ?? 0), i }))
+    .sort((a, b) => b.adjusted - a.adjusted || a.i - b.i)
+    .map((x) => x.hit);
+}

package/src/recommend.ts

@@ -15,7 +15,8 @@
 
 import type { Registry, RegistryEntry } from './registry.js';
 import { pretrain } from './pretrain.js';
-import { loadPatterns, computePatternBoost, readLearningConfig } from './patterns.js';
+import { computePatternBoost, loadPatterns, loadStoreRecords, readLearningConfig, readReinforcementState, recordToPattern } from './patterns.js';
+import { resolveLearningBackend } from './learning-backend.js';
 
 /** A recommended skill with relevance score. */
 export interface SkillRecommendation {
@@ -202,21 +203,34 @@ export function recommend(task: string, registry: Registry, projectRoot?: string
   // bounded, monotonic boost. Gated on the rollout flag; when memory is empty or
   // the flag is off, `patterns` is [] and the boost is 0 — ranking stays
   // byte-identical to the pure keyword scoring (the graceful invariant, R3).
-  const patterns =
-    projectRoot && readLearningConfig(projectRoot).recommendBoost ? loadPatterns(projectRoot) : [];
+  const records = projectRoot && readLearningConfig(projectRoot).recommendBoost ? loadStoreRecords(projectRoot) : [];
+  const patterns = projectRoot && readLearningConfig(projectRoot).recommendBoost ? loadPatterns(projectRoot) : [];
+  const backend = projectRoot !== undefined ? resolveLearningBackend(projectRoot) : undefined;
+  const boostFor = (entry: RegistryEntry): number => {
+    const base = computePatternBoost(entry.id, entry.description, patterns);
+    if (base <= 0 || backend === undefined) return base;
+    const matched = records.filter((r) => computePatternBoost(entry.id, entry.description, [recordToPattern(r)]) > 0);
+    if (matched.length === 0) return base;
+    const signals = backend.enhance(
+      matched.map((r) => ({ dzId: r.id, score: r.score, reinforcement: readReinforcementState(r) })),
+      { kind: 'recommend' },
+    );
+    const maxSignal = Math.max(0, ...signals);
+    return Math.min(50, Math.round(base * (1 + 0.25 * maxSignal)));
+  };
 
   // Score and rank skills
   const scored = registry.entries
     .map((e) => ({
       entry: e,
-      score: scoreSkill(e, topics) + (patterns.length ? computePatternBoost(e.id, e.description, patterns) : 0),
+      score: scoreSkill(e, topics) + (patterns.length ? boostFor(e) : 0),
     }))
     .filter((s) => s.score > 0)
     .sort((a, b) => b.score - a.score);
 
   const skills: SkillRecommendation[] = scored.slice(0, 10).map((s) => {
     let reason = `Matches topics: ${topics.filter((t) => scoreSkill(s.entry, [t]) > 0).join(', ')}`;
-    if (patterns.length && computePatternBoost(s.entry.id, s.entry.description, patterns) > 0) {
+    if (patterns.length && boostFor(s.entry) > 0) {
       reason += ' + learned patterns';
     }
     return {