@dzhechkov/harness-core 0.7.12 → 0.8.2

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

@@ -75,6 +75,12 @@ import {
 import { BACKLOG_TASK_TYPE } from './backlog.js';
 import { currentEmbedManifest, guardEmbedSpace, DEFAULT_EMBED_DIM, resolveEmbedModel, type EmbedModelConfig } from './embedding-config.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 {
@@ -634,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.
  */
@@ -659,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)' };
 }
 
@@ -1199,7 +1232,23 @@ export async function recallHybrid(
       semanticRanked: 0,
       ...extra,
       ...(banditReport !== undefined ? { bandit: banditReport } : {}),
-      ...(banditReport !== undefined && opts.deferExposures === true
+      ...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
@@ -1217,9 +1266,8 @@ export async function recallHybrid(
               } catch { /* a derived index never blocks the recall return (NFR-5) */ }
             },
           }
-        : {}),
-    };
-  };
+        : {};
+  }
 
   if (mode === 'lexical') {
     const out = lexicalOnly({});
@@ -1295,6 +1343,7 @@ export async function recallHybrid(
     semanticCandidates: sr.hits.length,
     semanticRanked: semantic.length,
     ...(banditReport !== undefined ? { bandit: banditReport } : {}),
+    ...deferredCommit(),
   };
 }