@dzhechkov/harness-core 0.8.36 → 0.8.37

package/src/debt-ratchet.ts

@@ -0,0 +1,143 @@
+/**
+ * Shared debt-ratchet verdict — one place, called by every "N exceeds ceiling C" gate.
+ *
+ * WHY (backlog `19e671ebfea26fc9`, feature debt-ceiling-diff): a count-only ceiling knows how MANY
+ * debt items exist but not WHICH ones. Once the set crosses the ceiling, printing "every current
+ * finding" drowns the one new offender in a legacy list of 100+ — the check technically fires, but
+ * a human (or an agent) reading the failure cannot see what actually changed. Pinning the set
+ * alongside the count lets the verdict print a DIFFERENCE: `added` (new, not in the pinned set) and
+ * `resolved` (pinned, no longer present) — the legacy tail stops being printed at all.
+ *
+ * The three-way verdict:
+ *   - current.length > ceiling  → ok:false, names only the newly added ids/findings.
+ *     If `added` is empty despite being over ceiling, the pinned set and the ceiling number have
+ *     drifted apart (caller error, not a real debt increase) — the message says so explicitly
+ *     rather than silently printing an empty new: list.
+ *   - current.length < ceiling  → ok:true, suggests lowering the ceiling, names what resolved.
+ *   - current.length === ceiling → ok:true UNLESS the membership itself changed (one debt swapped
+ *     for another at the same count) — that specific case is ok:false with a `swapped:` message,
+ *     because a same-count substitution is exactly the failure mode a raw-number ratchet cannot see:
+ *     a new debt item can hide behind a legacy one that happened to be fixed in the same window.
+ */
+
+export interface DebtRatchetArgs {
+  readonly label: string;
+  readonly current: readonly string[];
+  readonly pinned: readonly string[];
+  readonly ceiling: number;
+}
+
+export interface DebtRatchetVerdict {
+  readonly ok: boolean;
+  readonly message: string;
+  readonly added: string[];
+  readonly resolved: string[];
+}
+
+export function debtRatchetVerdict(args: DebtRatchetArgs): DebtRatchetVerdict {
+  const { label, current, pinned, ceiling } = args;
+  const pinnedSet = new Set(pinned);
+  const currentSet = new Set(current);
+  const added = current.filter((id) => !pinnedSet.has(id));
+  const resolved = pinned.filter((id) => !currentSet.has(id));
+  const n = current.length;
+
+  // Lead delta after Codex r1 (MEDIUM): a "set" with duplicates is not a set — the count, the +K and
+  // the suggested ceiling would all be wrong. Loud, never normalised silently.
+  if (currentSet.size !== n) {
+    const dupes = current.filter((id, i) => current.indexOf(id) !== i);
+    return { ok: false, message: `${label}: duplicate ids in the current set (${[...new Set(dupes)].join(', ')}) — the count ${n} is not a set size`, added, resolved };
+  }
+
+  // Lead delta after Codex r1 (HIGH): ANY new debt is a failure, whatever the count does — two legacy
+  // items resolved plus one new one is 2 < 3 by count and would otherwise pass silently, hiding the
+  // very thing this ratchet exists to name. The count-only ceiling never hid this any better; the
+  // pinned set finally makes it visible.
+  if (n <= ceiling && added.length > 0) {
+    return {
+      ok: false,
+      message: `${label} ${n}; ceiling ${ceiling}, but NEW debt appeared: new: ${added.join(', ')}; resolved: ${resolved.length > 0 ? resolved.join(', ') : '(none)'}`,
+      added,
+      resolved,
+    };
+  }
+
+  if (n > ceiling) {
+    const newPart = added.length > 0 ? added.join(', ') : '(none — set/ceiling inconsistent)';
+    const resolvedPart = resolved.length > 0 ? resolved.join(', ') : '(none)';
+    return {
+      ok: false,
+      message: `${label} ${n} exceeds ceiling ${ceiling} (+${n - ceiling}): new: ${newPart}; resolved: ${resolvedPart}`,
+      added,
+      resolved,
+    };
+  }
+
+  if (n < ceiling) {
+    const resolvedPart = resolved.length > 0 ? resolved.join(', ') : '(none)';
+    return {
+      ok: true,
+      message: `${label} ${n}; ceiling can be lowered to ${n}; resolved: ${resolvedPart}`,
+      added,
+      resolved,
+    };
+  }
+
+  // n === ceiling with no new ids: a swap (one resolved, one added) is already caught above by the
+  // any-new-debt rule, so the only way to land here is an unchanged set — a clean pass.
+
+  return {
+    ok: true,
+    message: `${label} ${n}; ceiling ${ceiling}`,
+    added,
+    resolved,
+  };
+}
+
+export interface PinnedCeiling {
+  readonly count: number;
+  readonly pinned: string[];
+  readonly measuredAt: string;
+  readonly reproducer: string;
+}
+
+/**
+ * Reads a debt-ceiling json file and requires the pinned set to agree with the declared count —
+ * a ceiling whose set and number disagree is not trustworthy data, so this fails loud rather than
+ * trusting the number alone (the exact defect this feature exists to close).
+ */
+export function ceilingUnreadableMessage(file: string): string {
+  return `Cannot read ${file}; measure the debt and create this ceiling file by hand.`;
+}
+
+/**
+ * PURE: the caller reads the file (tests own their I/O — the core-boundary ratchet counts src files
+ * that touch node:fs, and a debt-ceiling parser has no business being one); `file` is only used to
+ * name the offending file in error messages.
+ */
+export function parsePinnedCeiling(
+  source: string,
+  file: string,
+  countField: 'unobserved' | 'uncommented',
+  setField: 'ids' | 'findings',
+): PinnedCeiling {
+  const parsed = JSON.parse(source) as Record<string, unknown>;
+  const count = parsed[countField];
+  const set = parsed[setField];
+  const measuredAt = parsed.measuredAt;
+  const reproducer = parsed.reproducer;
+  if (
+    !Number.isSafeInteger(count) || (count as number) < 0
+    || typeof measuredAt !== 'string' || typeof reproducer !== 'string'
+    || !Array.isArray(set) || !set.every((item) => typeof item === 'string')
+  ) {
+    throw new Error(`Invalid debt ceiling: ${file}`);
+  }
+  if (set.length !== count) {
+    throw new Error(`Invalid debt ceiling: ${file}: ${setField}.length ${set.length} ≠ ${countField} ${count}`);
+  }
+  if (new Set(set as string[]).size !== set.length) {
+    throw new Error(`Invalid debt ceiling: ${file}: ${setField} contains duplicates — a pinned set must be a set`);
+  }
+  return { count: count as number, pinned: set as string[], measuredAt, reproducer };
+}

package/src/embedding-config.ts

@@ -1,12 +1,27 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, copyFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 export type EmbedModelSource = 'env' | 'config' | 'default';
 
+/**
+ * `embed-daemon-memory` (ADR-001 D2): dtype is a property of the STORE, not a global runtime
+ * setting. `fp32` is the full-precision default (existing behaviour, unchanged); `q8` is the
+ * quantized variant (`{ dtype: 'q8' }` at `pipeline()` construction, `model_quantized.onnx`) —
+ * roughly half the RSS of fp32 at a measured cosine parity >= 0.990 (see the harness-core README's
+ * `memory.embed.dtype` section for the numbers). `memory.embed.dtype` in config selects the dtype
+ * for a NEW index/reindex; the STORE's manifest is what a query is actually embedded with
+ * ({@link guardEmbedSpace}) — the two are deliberately allowed to disagree only long enough for the
+ * guard to demand a reindex, never silently.
+ */
+export type EmbedDtype = 'fp32' | 'q8';
+export const KNOWN_EMBED_DTYPES: readonly EmbedDtype[] = ['fp32', 'q8'];
+const DEFAULT_EMBED_DTYPE: EmbedDtype = 'fp32';
+
 export interface EmbedModelConfig {
   readonly model: string;
   readonly dim: 384;
   readonly source: EmbedModelSource;
+  readonly dtype: EmbedDtype;
 }
 
 export interface EmbedManifest {
@@ -14,6 +29,24 @@ export interface EmbedManifest {
   readonly dim: 384;
   readonly version: number;
   readonly engine?: string;
+  /** Absent on a manifest written before this feature — reads as `'fp32'` everywhere it is compared
+   * ({@link guardEmbedSpace}), matching the pre-existing fp32-only behaviour exactly. */
+  readonly dtype?: EmbedDtype;
+  /**
+   * Fix round 1 (Codex #4): the RAW `dtype` string off disk when it is PRESENT but not one of
+   * {@link KNOWN_EMBED_DTYPES} — a corrupted manifest (`"Q8"`) or one written by a future version
+   * (`"int8"`). Distinct from an ABSENT field (legacy pre-feature manifest, safe to read as `'fp32'`):
+   * a present-but-unknown value must never be silently folded into the same "absent" bucket, because
+   * the underlying vectors may genuinely not be fp32 — {@link guardEmbedSpace} and
+   * {@link resolveStoreEmbedDtype} both refuse instead of guessing when this is set.
+   */
+  readonly dtypeError?: string;
+  /** Lead delta after Codex r2 (HIGH): the manifest file EXISTS but could not be read/parsed
+   * (truncated by a concurrent writer, hand-edited into invalid JSON). It used to read as "absent"
+   * and fall through to legacy fp32 — the same silent cross-space risk as an unknown dtype. Only
+   * ENOENT means absent; a read/parse failure is carried here and guardEmbedSpace refuses. The
+   * remedy stays reachable: reindex stamps a NEW manifest before it re-indexes. */
+  readonly readError?: string;
 }
 
 export const DEFAULT_EMBED_MODEL = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
@@ -50,8 +83,10 @@ export const KNOWN_EMBED_DIMS: Readonly<Record<string, 384>> = {
  */
 
 export function resolveEmbedModel(projectRoot: string): EmbedModelConfig | { error: string } {
+  const dtypeResult = resolveEmbedDtype(projectRoot);
+  if ('error' in dtypeResult) return dtypeResult;
   const env = process.env['DZ_EMBED_MODEL'];
-  if (env !== undefined && env.trim() !== '') return modelConfig(env.trim(), 'env');
+  if (env !== undefined && env.trim() !== '') return modelConfig(env.trim(), 'env', dtypeResult.dtype);
   const cfgPath = join(projectRoot, '.dz', 'config.json');
   if (existsSync(cfgPath)) {
     try {
@@ -60,20 +95,45 @@ export function resolveEmbedModel(projectRoot: string): EmbedModelConfig | { err
       const agentdb = memory?.['agentdb'] as Record<string, unknown> | undefined;
       const embed = memory?.['embed'] as Record<string, unknown> | undefined;
       const configured = agentdb?.['embeddingModel'] ?? embed?.['model'];
-      if (typeof configured === 'string' && configured.trim() !== '') return modelConfig(configured.trim(), 'config');
+      if (typeof configured === 'string' && configured.trim() !== '') return modelConfig(configured.trim(), 'config', dtypeResult.dtype);
     } catch {
       /* corrupt config falls back to the default, matching the existing config-read discipline */
     }
   }
-  return modelConfig(DEFAULT_EMBED_MODEL, 'default');
+  return modelConfig(DEFAULT_EMBED_MODEL, 'default', dtypeResult.dtype);
+}
+
+/**
+ * FR-3/AC-2 (`embed-daemon-memory`): `memory.embed.dtype` read INDEPENDENTLY of which model source
+ * won above — a dtype override must apply the same way whether the model itself came from env,
+ * config, or the default. An unset value (or a config file that predates this feature) is `'fp32'`,
+ * matching every store written before this feature existed. An unrecognized string is a hard
+ * `{error}` naming the allowed values, never a silent fp32 fallback — a typo in the dtype must not
+ * quietly build the wrong-shaped index.
+ */
+function resolveEmbedDtype(projectRoot: string): { dtype: EmbedDtype } | { error: string } {
+  const cfgPath = join(projectRoot, '.dz', 'config.json');
+  if (!existsSync(cfgPath)) return { dtype: DEFAULT_EMBED_DTYPE };
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')) as Record<string, unknown>;
+    const memory = cfg['memory'] as Record<string, unknown> | undefined;
+    const embed = memory?.['embed'] as Record<string, unknown> | undefined;
+    const raw = embed?.['dtype'];
+    if (raw === undefined) return { dtype: DEFAULT_EMBED_DTYPE };
+    if (typeof raw === 'string' && (KNOWN_EMBED_DTYPES as readonly string[]).includes(raw)) return { dtype: raw as EmbedDtype };
+    return { error: `unsupported embedding dtype '${String(raw)}' (known: ${KNOWN_EMBED_DTYPES.join(', ')})` };
+  } catch {
+    // corrupt config falls back to the default, matching resolveEmbedModel's own discipline
+    return { dtype: DEFAULT_EMBED_DTYPE };
+  }
 }
 
-function modelConfig(model: string, source: EmbedModelSource): EmbedModelConfig | { error: string } {
+function modelConfig(model: string, source: EmbedModelSource, dtype: EmbedDtype): EmbedModelConfig | { error: string } {
   const dim = KNOWN_EMBED_DIMS[model];
   if (dim === undefined) {
     return { error: `unsupported embedding model '${model}' (known 384-dim models: ${Object.keys(KNOWN_EMBED_DIMS).join(', ')})` };
   }
-  return { model, dim, source };
+  return { model, dim, source, dtype };
 }
 
 export function embedManifestPath(storePath: string): string {
@@ -86,13 +146,41 @@ export function readEmbedManifest(storePath: string): EmbedManifest | undefined
 
 function readManifestFile(p: string): EmbedManifest | undefined {
   if (!existsSync(p)) return undefined;
+  // `readError` (below) is scoped to a REGULAR FILE whose bytes cannot be parsed — the concurrent-
+  // writer/hand-edit case Codex r2 named. A non-file at the sidecar path (a directory) is a different
+  // pathology and stays "absent": the store-generation AM-3 fixture plants exactly that directory so
+  // the manifest WRITE fails loudly after a real commit — refusing here would hide that contract.
+  let isFile = false;
+  try {
+    isFile = statSync(p).isFile();
+  } catch {
+    isFile = false;
+  }
+  if (!isFile) return undefined;
   try {
     const m = JSON.parse(readFileSync(p, 'utf-8')) as Partial<EmbedManifest>;
     if (typeof m.model !== 'string' || m.model === '') return undefined;
     if (m.dim !== DEFAULT_EMBED_DIM) return undefined;
-    return { model: m.model, dim: DEFAULT_EMBED_DIM, version: typeof m.version === 'number' ? m.version : 1, ...(typeof m.engine === 'string' ? { engine: m.engine } : {}) };
-  } catch {
-    return undefined;
+    // T1 + fix round 1 (Codex #4): only the two known dtype strings are trusted off disk as a real
+    // dtype. An ABSENT field reads as `undefined` (legacy pre-feature manifest — guardEmbedSpace
+    // treats it as fp32, the safe pre-existing default). A field that IS PRESENT but names neither
+    // known value is NEVER folded into that same "absent" bucket — it used to be (T1's original cut),
+    // which let a corrupted (`"Q8"`) or future-version (`"int8"`) dtype masquerade as legacy-fp32 and
+    // search would silently compare vectors from two different spaces. It is carried instead as
+    // `dtypeError` (the raw string), which guardEmbedSpace/resolveStoreEmbedDtype turn into a hard
+    // refusal rather than a guess.
+    const dtype = m.dtype === 'fp32' || m.dtype === 'q8' ? m.dtype : undefined;
+    const dtypeError = m.dtype !== undefined && dtype === undefined ? String(m.dtype) : undefined;
+    return {
+      model: m.model,
+      dim: DEFAULT_EMBED_DIM,
+      version: typeof m.version === 'number' ? m.version : 1,
+      ...(typeof m.engine === 'string' ? { engine: m.engine } : {}),
+      ...(dtype !== undefined ? { dtype } : {}),
+      ...(dtypeError !== undefined ? { dtypeError } : {}),
+    };
+  } catch (err) {
+    return { model: '', dim: DEFAULT_EMBED_DIM, version: 1, readError: err instanceof Error ? err.message : String(err) };
   }
 }
 
@@ -111,9 +199,20 @@ export function legacyEmbedManifest(): EmbedManifest {
 }
 
 export function currentEmbedManifest(configured: EmbedModelConfig, version = 1, engine?: string): EmbedManifest {
-  return { model: configured.model, dim: configured.dim, version, ...(engine !== undefined ? { engine } : {}) };
+  return { model: configured.model, dim: configured.dim, version, dtype: configured.dtype, ...(engine !== undefined ? { engine } : {}) };
 }
 
+/**
+ * D2 (`embed-daemon-memory`): the model/dim check is unchanged; a SEPARATE dtype check is added
+ * after it. Absent manifest dtype reads as `'fp32'` (matching every store written before this
+ * feature) before the comparison — so an existing fp32 store configured for fp32 never trips this,
+ * and only a genuine fp32<->q8 disagreement (or a q8 store re-configured to fp32) is refused.
+ *
+ * Fix round 1 (Codex #4): a manifest `dtype` that is PRESENT but unrecognized ({@link
+ * EmbedManifest.dtypeError}) is checked BEFORE the fp32-fallback comparison above — it must never
+ * be silently treated as the safe legacy-absent case, because the store's real vectors may not be
+ * fp32 at all.
+ */
 export function guardEmbedSpace(args: {
   storePath: string;
   configured: EmbedModelConfig;
@@ -122,6 +221,13 @@ export function guardEmbedSpace(args: {
 }): { ok: true; manifest: EmbedManifest } | { ok: false; error: string; manifest: EmbedManifest } {
   const manifest = readStoreManifest(args.storePath)
     ?? (args.hasRows ? legacyEmbedManifest() : currentEmbedManifest(args.configured));
+  if (manifest.readError !== undefined) {
+    return {
+      ok: false,
+      manifest,
+      error: `embedding manifest unreadable (${manifest.readError}); run ${args.reindexHint}`,
+    };
+  }
   if (manifest.model !== args.configured.model || manifest.dim !== args.configured.dim) {
     return {
       ok: false,
@@ -129,6 +235,21 @@ export function guardEmbedSpace(args: {
       error: `embedding model mismatch: index built with ${manifest.model}/${manifest.dim}, configured ${args.configured.model}/${args.configured.dim}; run ${args.reindexHint}`,
     };
   }
+  if (manifest.dtypeError !== undefined) {
+    return {
+      ok: false,
+      manifest,
+      error: `unknown embedding dtype "${manifest.dtypeError}" in manifest; run ${args.reindexHint}`,
+    };
+  }
+  const manifestDtype = manifest.dtype ?? DEFAULT_EMBED_DTYPE;
+  if (manifestDtype !== args.configured.dtype) {
+    return {
+      ok: false,
+      manifest,
+      error: `embedding dtype mismatch: index built with ${manifestDtype}, configured ${args.configured.dtype}; run ${args.reindexHint}`,
+    };
+  }
   return { ok: true, manifest };
 }
 

package/src/feature-adr-checkpoints.ts

@@ -491,6 +491,11 @@ export interface TrainingPair {
   truncated: TrainingPairTruncation | null;
   captureMode: 'capture' | 'backfill';
   resumed: boolean;
+  /** experiment-envelope FR-3(б): the envelope built once after the Step-0 router, carried
+   * alongside `budgetMode` (not instead of it — `budgetMode` is a narrower legacy summary).
+   * Normalized via `validateExperimentEnvelope`: an invalid or absent value becomes `null`, never
+   * a malformed value smuggled into the dataset. */
+  envelope: unknown | null;
 }
 
 /** Per-stage JSONL path, relative to the repo root. ONE file per stage. */
@@ -649,6 +654,28 @@ function normalizeTrainingPairBudget(raw: unknown): TrainingPairBudget | null {
   }
 }
 
+/**
+ * experiment-envelope FR-3(б): a LIGHTWEIGHT structural check, not the full field-by-field
+ * validator (`validateExperimentEnvelope` in `feature-adr-envelope.ts`) — this module is
+ * DELIBERATELY import-free (the workflow sandbox mirrors it inline, same discipline as
+ * `TP_PROFILE_MARKER_START`/`tpRedact` above), so importing the full validator here would break
+ * that mirroring. This check catches gross malformation (not an object, wrong schema, missing
+ * the four nested sections) — the AUTHORITATIVE per-field validation gate lives at the
+ * run-records/round layer, where an invalid envelope actually refuses a write. Absent or
+ * malformed here degrades HONESTLY to `null`, never a fabricated or partially-checked value.
+ */
+function normalizeTrainingPairEnvelope(raw: unknown): unknown | null {
+  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const v = raw as Record<string, unknown>;
+  if (v.schema !== 1) return null;
+  if (typeof v.runId !== 'string' || v.runId.trim() === '') return null;
+  if (v.arms === null || typeof v.arms !== 'object') return null;
+  if (v.chosen === null || typeof v.chosen !== 'object') return null;
+  if (v.policy === null || typeof v.policy !== 'object') return null;
+  if (v.evaluator === null || typeof v.evaluator !== 'object') return null;
+  return raw;
+}
+
 /** Assemble one SFT-ready training pair. Deterministic (ts passed in). Applies the oversize
  * guard: when input+output exceed TRAINPAIR_MAX_IO_CHARS combined, each over-budget side is
  * truncated with a marker naming the cut char count + the fnv1a64 of its FULL text (the
@@ -667,6 +694,7 @@ export function buildTrainingPair(opts: {
   budgetMode?: unknown;
   captureMode?: unknown;
   resumed?: unknown;
+  envelope?: unknown;
 }): TrainingPair {
   // Operator-profile redaction FIRST — before the oversize guard, so the truncation hashes are
   // hashes of the redacted text and the full-text fnv1a64 never fingerprints personal data.
@@ -709,6 +737,7 @@ export function buildTrainingPair(opts: {
     truncated,
     captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',
     resumed: opts.resumed === true,
+    envelope: normalizeTrainingPairEnvelope(opts.envelope),
   };
 }
 

package/src/feature-adr-decision-recall.ts

@@ -8,8 +8,8 @@ const MAX_QUERY_CHARS = 512;
 const MAX_PATTERN_CHARS = 800;
 const MAX_EVIDENCE_CHARS = 800;
 
-export type DecisionRecallKind = 'adr-alternative-selection' | 'plan-route-selection';
-export type DecisionRecallStage = 'step-3' | 'step-6';
+export type DecisionRecallKind = 'adr-alternative-selection' | 'plan-route-selection' | 'code-implementation';
+export type DecisionRecallStage = 'step-3' | 'step-6' | 'step-7';
 export type DecisionRecallOutcomeName =
   | 'success'
   | 'empty'
@@ -63,6 +63,8 @@ function oneLine(value: unknown, cap: number): string {
 function decisionShape(kind: DecisionRecallKind): { stage: DecisionRecallStage; banditContext: string } {
   return kind === 'adr-alternative-selection'
     ? { stage: 'step-3', banditContext: 'feature-adr-decision-adr-alternative' }
+    : kind === 'code-implementation'
+    ? { stage: 'step-7', banditContext: 'feature-adr-decision-code-implementation' }
     : { stage: 'step-6', banditContext: 'feature-adr-decision-plan-route' };
 }
 
@@ -391,8 +393,8 @@ function validBase(value: Record<string, unknown>): boolean {
   return typeof value.slug === 'string' && value.slug !== ''
     && typeof value.logicalDecisionId === 'string' && /^decision:[0-9a-f]{16}$/.test(value.logicalDecisionId)
     && typeof value.attemptId === 'string' && value.attemptId.startsWith(`${value.logicalDecisionId}:`)
-    && (value.stage === 'step-3' || value.stage === 'step-6')
-    && (value.decisionKind === 'adr-alternative-selection' || value.decisionKind === 'plan-route-selection')
+    && (value.stage === 'step-3' || value.stage === 'step-6' || value.stage === 'step-7')
+    && (value.decisionKind === 'adr-alternative-selection' || value.decisionKind === 'plan-route-selection' || value.decisionKind === 'code-implementation')
     && typeof value.ts === 'string' && value.ts !== '';
 }