@dzhechkov/harness-core 0.8.36 → 0.8.38

package/dist/agentdb-index.js

@@ -100,11 +100,37 @@ export function ensureAgentdbSchema(projectRoot, dbPath) {
 function generationFilePath(dbFile) {
     return `${dbFile}.generation`;
 }
+/** `<dbFile>.generation.recovered` (T2, `store-generation-residuals`, record `1d465496`) — the
+ * corrupt-sidecar recovery floor's own memory, a SEPARATE file next to the counter (never a
+ * module-level variable: two OS processes do not share one, and two processes are exactly what
+ * race here). Substring `.generation` deliberately preserved so any future sidecar-enumeration
+ * point that greps for the counter family (checked, none exists today — see Р-2 in
+ * `features/store-generation-residuals/06_implementation_plan.md`) still finds this file. */
+function recoveredMemoryFilePath(genFile) {
+    return `${genFile}.recovered`;
+}
 /** AM-5 (fix-round): the ONLY shape {@link readStoreGeneration} trusts — one or more ASCII digits,
  * nothing else. `Number.parseInt` alone accepts a leading-numeric-with-trailing-junk string like
  * `"12junk"` as `12`; that reads a corrupt sidecar as a plausible generation instead of degrading to
  * the documented `0` compatibility floor. */
 const STRICT_GENERATION = /^\d+$/;
+/** Shared degrade-to-0 read for any sidecar holding a single non-negative decimal integer: garbage,
+ * a missing file, or anything not matching {@link STRICT_GENERATION} reads as `0`, never throws.
+ * Both {@link readStoreGeneration} (the counter itself) and T2's recovery memory
+ * ({@link recoveredMemoryFilePath}) use this ONE primitive — the recovery memory must degrade
+ * exactly like the counter it accompanies (T2 NFR-1), not by a second, possibly-diverging rule. */
+function readNonNegativeIntFile(path) {
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        if (!STRICT_GENERATION.test(raw))
+            return 0;
+        const n = Number.parseInt(raw, 10);
+        return Number.isFinite(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * FR-2/FR-3 (`store-generation-counter`): the store's write-generation counter, read back. A
  * missing file (a store that predates this feature, or one that has never been written through
@@ -115,16 +141,7 @@ const STRICT_GENERATION = /^\d+$/;
  * to decide validity, only to convert an already-validated string.
  */
 export function readStoreGeneration(projectRoot, dbPath) {
-    try {
-        const raw = readFileSync(generationFilePath(resolveAgentdbPath(projectRoot, dbPath)), 'utf8').trim();
-        if (!STRICT_GENERATION.test(raw))
-            return 0;
-        const n = Number.parseInt(raw, 10);
-        return Number.isFinite(n) && n >= 0 ? n : 0;
-    }
-    catch {
-        return 0;
-    }
+    return readNonNegativeIntFile(generationFilePath(resolveAgentdbPath(projectRoot, dbPath)));
 }
 /**
  * FR-1 (`store-generation-counter`): monotonically advance the store's write-generation counter by
@@ -147,6 +164,37 @@ export function readStoreGeneration(projectRoot, dbPath) {
  * regardless, telemetry is never a gate. AM-4: {@link resolveAgentdbPath} itself now runs INSIDE this
  * function's outer `try` — an unresolvable path can no longer throw OUT of `bumpStoreGeneration`
  * either; "never throws" now covers the whole function, not just the file-write tail.
+ *
+ * T2 (`store-generation-residuals`, record `1d465496`): the corrupt-sidecar recovery floor below
+ * used to be a bare `Date.now()` — NOT strictly monotonic on its own (two recoveries inside the same
+ * millisecond publish the same value; a backward clock step can publish a SMALLER one than an
+ * earlier recovery). It is now `max(now(), lastPublished + 1)`, where `lastPublished` is read from
+ * {@link recoveredMemoryFilePath} — a file, not a module-level variable, because the two writers who
+ * actually race here are two OS PROCESSES, which do not share process memory. `now` is an injectable
+ * time source (default `Date.now`) — AC-3's only reason to exist: a real clock cannot be rolled back
+ * from a test.
+ *
+ * Fix-round 1 (independent Codex review, gpt-5.6-sol — items 2/3/4/5/7), on top of T2:
+ * - item 2: {@link recoveredMemoryFilePath} now holds the LAST **published** generation, not the
+ *   last **recovered** one — it is written on EVERY successful bump, not only inside the
+ *   corrupt-sidecar branch. Before this fix, a run of ordinary bumps after a recovery left the
+ *   memory stale, so a LATER recovery under a rolled-back clock could float the counter below a
+ *   generation an ordinary bump already published (HIGH #2 finding).
+ * - item 3: the memory file is published BEFORE the counter file (was: counter first, memory
+ *   "best-effort" after). A crash between the two writes now leaves the memory AHEAD of the counter
+ *   — the SAFE direction: the next recovery floors too high rather than too low, so monotonicity
+ *   survives a half-done bump (HIGH #3 finding).
+ * - item 4: a memory-write failure (e.g. a directory sitting at its path) does NOT block the counter
+ *   publish below it — invalidation is the load-bearing behaviour — but the degradation is reported
+ *   on stderr via {@link reportBumpMemoryDegraded}, never swallowed. LIMITATION: while the memory
+ *   sidecar stays unwritable, a future corrupt-sidecar recovery on this store floors only at the wall
+ *   clock, same as pre-fix-round behaviour — not strictly above every ordinary bump published in the
+ *   meantime (HIGH #4 finding).
+ * - item 5: every error-to-string conversion in this function goes through {@link safeErrorMessage},
+ *   which cannot itself throw even if `err` carries a poisoned `toString` — "never throws" is
+ *   absolute (MEDIUM #5 finding).
+ * - item 7: the memory sidecar's own tmp file is cleaned up on a failed write, matching the counter's
+ *   existing tmp-cleanup discipline (LOW #7 finding).
  */
 /** Codex round-2 (NEW HIGH): most mutators discard the bump result, so a failed bump must be
  * VISIBLE on its own — one stderr line, written by the helper itself. Telemetry never throws. */
@@ -157,29 +205,100 @@ function reportBumpFailure(error) {
     catch { /* telemetry never throws */ }
     return { ok: false, error };
 }
-export function bumpStoreGeneration(projectRoot, dbPath) {
+/** Fix-round 1, item 4: a bump whose COUNTER publish succeeded but whose recovery-memory sidecar
+ * ({@link recoveredMemoryFilePath}) could not be written must not swallow that fact — same
+ * stderr-report shape as {@link reportBumpFailure}, but this one never changes the return value:
+ * the counter genuinely advanced, so `{ok:true, generation}` stands. LIMITATION (documented here per
+ * the brief, item 4): until the memory sidecar is writable again, a FUTURE corrupt-sidecar recovery
+ * on this store is not guaranteed to floor above every generation an ordinary bump already published
+ * in the meantime (item 2's fix depends on the memory file being current) — it still floors above the
+ * wall clock, same as before this fix-round. */
+function reportBumpMemoryDegraded(reason) {
+    try {
+        process.stderr.write(`dz: store generation recovery memory not updated — ${reason} — a future corrupt-sidecar recovery on this store is not guaranteed to stay strictly monotonic until this is fixed\n`);
+    }
+    catch { /* telemetry never throws */ }
+}
+/** Fix-round 1, item 5: `String(err)` itself can throw if `err` carries a poisoned `toString` (or
+ * `Error.prototype.message` getter). `bumpStoreGeneration`'s "never throws" contract (FR-4) is
+ * ABSOLUTE, so every place in this function that turns a caught error into a string goes through
+ * this ONE protected helper — never a bare `err instanceof Error ? err.message : String(err)`.
+ * Exported test-only (same convention as {@link needsRescueBump}/{@link resetAgentdbEmbedderCache}).
+ */
+export function safeErrorMessage(err) {
+    try {
+        return err instanceof Error ? err.message : String(err);
+    }
+    catch {
+        return '(unstringifiable error)';
+    }
+}
+export function bumpStoreGeneration(projectRoot, dbPath, 
+/** T2: the ONLY signature extension the plan permits — injectable wall clock, default `Date.now`,
+ * so AC-3 (a rolled-back system clock) can be reproduced without touching the real clock. */
+now = Date.now) {
     try {
         const dbFile = resolveAgentdbPath(projectRoot, dbPath);
         const genFile = generationFilePath(dbFile);
+        // Fix-round 1, item 2: computed UNCONDITIONALLY (was: only inside the corrupt-sidecar branch) —
+        // this sidecar now tracks "last PUBLISHED generation", updated on every successful bump, not just
+        // a recovery.
+        const recoveredMemoryFile = recoveredMemoryFilePath(genFile);
         return withNamedLockSync(dirname(dbFile), 'store-generation', () => {
             // AM-2: re-read the CURRENT value from disk while holding the lock — a value observed before
             // acquisition may already be stale, another holder may have advanced it in the meantime.
             let current = readStoreGeneration(projectRoot, dbPath);
             const tmp = `${genFile}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+            const recTmp = `${recoveredMemoryFile}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
             try {
-                // Codex round-2 (AM-2 residual): a sidecar that EXISTS but is corrupt reads as 0 and would
-                // reset the counter to 1 — a value an engine-cache entry may already be keyed on. Floor a
-                // corrupt value at a wall-clock stamp instead: still monotonic (ms since epoch exceeds any
-                // count reached by bumping) and never colliding with an earlier generation. Absent file ⇒ 1.
+                // Codex round-2 (AM-2 residual) / T2 (record `1d465496`): a sidecar that EXISTS but is
+                // corrupt reads as 0 and would reset the counter to 1 — a value an engine-cache entry may
+                // already be keyed on. Floor a corrupt value at max(wall-clock, lastPublished+1) instead:
+                // still monotonic (ms-since-epoch exceeds any count reached by bumping) AND strictly
+                // increasing across successive corrupt recoveries even inside the same millisecond or
+                // across a backward clock step — the bare `Date.now()` this replaces was neither. Absent
+                // file (not corrupt, simply missing) still takes the ordinary `current === 0` path below,
+                // unaffected — only a genuinely corrupt EXISTING sidecar enters this branch.
                 if (current === 0 && existsSync(genFile)) {
                     const raw = readFileSync(genFile, 'utf8').trim();
-                    if (raw !== '0' && !STRICT_GENERATION.test(raw))
-                        current = Date.now();
+                    if (raw !== '0' && !STRICT_GENERATION.test(raw)) {
+                        // NFR-1: a memory file that cannot be read (missing, or itself corrupt) degrades to 0,
+                        // exactly like the counter's own read — never a throw, never a special-cased error.
+                        // Fix-round 1, item 2: `lastPublished` now reflects every prior successful bump
+                        // (ordinary or recovery), not only the previous recovery — see the doc comment above.
+                        const lastPublished = readNonNegativeIntFile(recoveredMemoryFile);
+                        current = Math.max(now(), lastPublished + 1);
+                    }
                 }
                 const next = current + 1;
                 mkdirSync(dirname(genFile), { recursive: true });
+                // Fix-round 1, item 3: the memory sidecar is published BEFORE the counter sidecar — a crash
+                // between the two then leaves the memory AHEAD of the counter (safe: the next recovery
+                // floors too high, never too low). Fix-round 1, item 2: this now runs on EVERY successful
+                // bump, not only inside the corrupt-sidecar branch above.
+                let memoryError;
+                try {
+                    writeFileSync(recTmp, String(next), { encoding: 'utf8', flag: 'wx' });
+                    renameSync(recTmp, recoveredMemoryFile);
+                }
+                catch (memErr) {
+                    // Fix-round 1, item 4: the counter publish below still goes ahead — invalidation matters
+                    // more than the memory sidecar — but the degradation is reported, not swallowed (see the
+                    // stderr write after the counter publish). Fix-round 1, item 7: clean up a half-written
+                    // memory tmp file the same way the counter's own tmp is cleaned up on failure below.
+                    try {
+                        if (existsSync(recTmp))
+                            unlinkSync(recTmp);
+                    }
+                    catch { /* best-effort only */ }
+                    memoryError = safeErrorMessage(memErr);
+                }
                 writeFileSync(tmp, String(next), { encoding: 'utf8', flag: 'wx' });
                 renameSync(tmp, genFile);
+                // Fix-round 1, item 4: reported AFTER the counter publish succeeds, so the stderr line
+                // never implies the bump itself failed — it names exactly the narrower, degraded guarantee.
+                if (memoryError !== undefined)
+                    reportBumpMemoryDegraded(memoryError);
                 return { ok: true, generation: next };
             }
             catch (err) {
@@ -190,7 +309,12 @@ export function bumpStoreGeneration(projectRoot, dbPath) {
                         unlinkSync(tmp);
                 }
                 catch { /* best-effort only */ }
-                return reportBumpFailure(`store generation bump failed: ${err instanceof Error ? err.message : String(err)}`);
+                try {
+                    if (existsSync(recTmp))
+                        unlinkSync(recTmp);
+                }
+                catch { /* best-effort only */ } // item 7
+                return reportBumpFailure(`store generation bump failed: ${safeErrorMessage(err)}`);
             }
         });
     }
@@ -198,7 +322,7 @@ export function bumpStoreGeneration(projectRoot, dbPath) {
         // AM-2/FR-4: a lock that could not be acquired by its deadline (`NamedLockTimeoutError`) — and
         // any other failure reaching this point (an unresolvable path, AM-4) — degrades to the same
         // honest `{ok:false, error}` shape; it never throws into the store write it accompanies.
-        return reportBumpFailure(`store generation bump failed: ${err instanceof Error ? err.message : String(err)}`);
+        return reportBumpFailure(`store generation bump failed: ${safeErrorMessage(err)}`);
     }
 }
 /**
@@ -209,36 +333,27 @@ export async function indexPatternsToAgentdb(projectRoot, rows, opts = {}) {
     if (rows.length === 0)
         return { indexed: 0 };
     let sqliteUrl;
-    let agentdbDir;
     try {
         const req = createRequire(join(projectRoot, 'package.json'));
         sqliteUrl = pathToFileURL(req.resolve('better-sqlite3')).href;
-        agentdbDir = dirname(req.resolve('agentdb'));
     }
     catch {
         return { indexed: 0, error: 'agentdb/better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
     }
     try {
         const { default: Database } = (await import(sqliteUrl));
-        const { EmbeddingService } = (await import(pathToFileURL(join(agentdbDir, 'controllers', 'EmbeddingService.js')).href));
         const model = resolveEmbedModel(projectRoot);
         if ('error' in model)
             return { indexed: 0, error: model.error };
-        const emb = new EmbeddingService({
-            model: model.model,
-            dimension: model.dim,
-            provider: 'transformers',
-            // agentdb >= 3.0.0-alpha.20 refuses UNREGISTERED models without an explicit role policy
-            // (its built-in registry knows all-MiniLM-L6-v2 but not our multilingual variant — grounded
-            // in dist/src/controllers/EmbeddingService.js:53). paraphrase-multilingual-MiniLM is a
-            // SYMMETRIC sentence-transformer (no query/passage instruction prefixes), so the policy is
-            // {kind:'symmetric'} — the same one the registry assigns its own symmetric models. On
-            // alpha.18 the extra field is ignored; without it alpha.20 threw and the vector tier fell
-            // to lexical SILENTLY (mirror writes answered {indexed:0, error} — measured 2026-08-24).
-            rolePolicy: { kind: 'symmetric' },
-        });
-        await emb.initialize();
         const dbFile = resolveAgentdbPath(projectRoot, opts.dbPath);
+        // D1 (embed-daemon-memory, ADR-001): a single embedder per process — the SAME cached pipeline
+        // `resolveAgentdbEmbedder` hands to search/the daemon, never a private `new EmbeddingService(...)`
+        // built here. `dbFile` (not just `projectRoot`) so an EXISTING store's dtype (manifest, D2) wins
+        // over the config for an ordinary incremental index — only `reindexAgentdbRows` re-stamps the
+        // manifest first and thereby moves the dtype (see resolveStoreEmbedDtype's own doc comment).
+        const emb = await resolveAgentdbEmbedder(projectRoot, dbFile);
+        if ('error' in emb)
+            return { indexed: 0, error: emb.error };
         const db = new Database(dbFile);
         try {
             db.pragma('journal_mode = WAL');
@@ -282,7 +397,22 @@ export async function indexPatternsToAgentdb(projectRoot, rows, opts = {}) {
             // whichever of the two calls below throws, the generation is already correct for the rows that
             // are already on disk.
             const bump = bumpStoreGeneration(projectRoot, opts.dbPath);
-            writeEmbedManifest(dbFile, currentEmbedManifest(model, guard.manifest.version, 'agentdb'));
+            // Fix-round 1 (CRITICAL, item 1a): `writeEmbedManifest` can throw (a directory sitting at the
+            // manifest sidecar path — see the AM-3 test). Before this fix, that throw escaped to the outer
+            // `catch` below, which returned the GENERIC `{indexed: 0, error: ...}` — discarding the two
+            // facts already true by this point: `indexed` rows are on disk, and `bump` already ran. A
+            // caller reading `indexed === 0` would conclude "nothing happened" and skip its own rescue-bump
+            // logic even though the store had genuinely changed — the under-bump C-1 forbids. Catching the
+            // throw HERE, with the real `indexed`/bump outcome already captured in scope, preserves both.
+            try {
+                writeEmbedManifest(dbFile, currentEmbedManifest(model, guard.manifest.version, 'agentdb'));
+            }
+            catch (manifestErr) {
+                const manifestError = `index failed: ${safeErrorMessage(manifestErr)}`;
+                return bump.ok
+                    ? { indexed, generationBumped: true, error: manifestError }
+                    : { indexed, generationBumped: false, generationReason: bump.error, error: manifestError };
+            }
             return bump.ok
                 ? { indexed, generationBumped: true }
                 : { indexed, generationBumped: false, generationReason: bump.error };
@@ -292,7 +422,7 @@ export async function indexPatternsToAgentdb(projectRoot, rows, opts = {}) {
         }
     }
     catch (err) {
-        return { indexed: 0, error: `index failed: ${err instanceof Error ? err.message : String(err)}` };
+        return { indexed: 0, error: `index failed: ${safeErrorMessage(err)}` };
     }
 }
 /* ------------------------------------------------------------------ */
@@ -332,18 +462,147 @@ const DEPS_MISSING = 'agentdb/better-sqlite3 not installed in project (run: dz s
  */
 const embedderCache = new Map();
 let embedderCacheInitializations = 0;
+/**
+ * Fix round 1 (F6, Codex #6): `embedderCacheInitializations` only counts calls to
+ * {@link resolveAgentdbEmbedder} that missed the cache — it proves cache REUSE, not that a real
+ * pipeline was actually constructed. This counter increments at the exact two call sites where a
+ * pipeline construction primitive actually runs: the direct `pipeline('feature-extraction', …)` call
+ * in {@link initAgentdbEmbedder} and `EmbeddingService.initialize()` in
+ * {@link initViaAgentdbEmbeddingService} (the COMPAT FALLBACK path) — never merely on entry to
+ * `initAgentdbEmbedder`, which can also return an `{error}` (dtype:'q8' with no resolvable
+ * transformers, NFR-4) without ever attempting either.
+ */
+let embedderCachePipelinesBuilt = 0;
 /** Test-only (and future warm-start) reset — callers (`vector-tier.ts`, `backlog.ts`) are unaffected. */
 export function resetAgentdbEmbedderCache() {
     embedderCache.clear();
     embedderCacheInitializations = 0;
+    embedderCachePipelinesBuilt = 0;
 }
 /** `entries` = cached keys right now — a SUCCESSFUL pipeline or an IN-FLIGHT initialization (the promise is
  * cached before it settles, FR-4; a failed one is evicted, FR-3); `initializations` = pipelines actually
- * started since the last reset. (Codex round-1, 2026-09-14: the earlier wording said "successful" only.) */
+ * started since the last reset. (Codex round-1, 2026-09-14: the earlier wording said "successful" only.)
+ * `pipelinesBuilt` (fix round 1, F6) = the count of REAL pipeline-construction primitives that actually
+ * ran (`pipeline()` or `EmbeddingService.initialize()`), never merely the number of times the resolver
+ * was entered — see {@link embedderCachePipelinesBuilt}'s own doc comment for why the two can diverge. */
 export function getAgentdbEmbedderCacheStats() {
-    return { entries: embedderCache.size, initializations: embedderCacheInitializations };
+    return { entries: embedderCache.size, initializations: embedderCacheInitializations, pipelinesBuilt: embedderCachePipelinesBuilt };
+}
+/**
+ * Walk UP from `startDir` (inclusive) looking for `<dir>/node_modules/<name>` as a real, existing
+ * path — a PLAIN FILESYSTEM CHECK, deliberately never `require.resolve()` alone. MEASURED
+ * 2026-09-16: under this package's own vitest harness, `createRequire(join(projectRoot,
+ * 'package.json')).resolve('@huggingface/transformers')` succeeds even for a deliberately isolated
+ * `/tmp` fixture that installs no such dependency at all (`agentdb-embedder-cache.test.ts`'s AC-3) —
+ * the test runner's module loader resolves more liberally than plain Node does, reaching the
+ * monorepo's real install regardless of `projectRoot`. `require.resolve` is used only AFTER this
+ * filesystem walk has already named a legitimate ancestor, so it can no longer be fooled that way.
+ * Returns the ancestor directory whose OWN `node_modules/<name>` exists, or `undefined` if none does
+ * all the way to the filesystem root (a handful of synchronous `existsSync` calls either way).
+ */
+function findAncestorWithModule(startDir, name) {
+    let dir = resolve(startDir);
+    for (;;) {
+        if (existsSync(join(dir, 'node_modules', name)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * C-3 (`embed-daemon-memory`): the SAME resolution order the daemon's own `resolveDeps` uses
+ * (`.claude/helpers/dz-embed-daemon.mjs`) — project `package.json` first, then `agentdb`'s own
+ * declared dependency (possibly hoisted elsewhere) — so core and the daemon agree on which install
+ * of transformers they find, in a monorepo or a plain install alike. Each candidate root is
+ * confirmed by {@link findAncestorWithModule} BEFORE `require.resolve` is trusted (see its own doc
+ * comment for why the plain try/catch this replaced was not safe under this package's test runner).
+ *
+ * Exported (fix round 1, F4, same convention as {@link safeErrorMessage}/{@link resetAgentdbEmbedderCache}):
+ * `embedder-single-owner.test.ts`'s live-dep skip gate needs the SAME resolution order the production
+ * code uses to decide, BEFORE running, whether a live embedder failure is a dependency gap (named skip)
+ * or a real defect (must fail) — a text-matching heuristic on the error message cannot tell those apart.
+ */
+export function resolveTransformersModule(projectRoot) {
+    const candidates = ['@huggingface/transformers', '@xenova/transformers'];
+    for (const name of candidates) {
+        const ancestor = findAncestorWithModule(projectRoot, name);
+        if (ancestor === undefined)
+            continue;
+        try {
+            return { url: pathToFileURL(createRequire(join(ancestor, 'package.json')).resolve(name)).href };
+        }
+        catch {
+            /* an ancestor that named the directory but whose require still can't resolve it (e.g. a
+               broken symlink) — try the next candidate */
+        }
+    }
+    let agentdbDir;
+    try {
+        agentdbDir = dirname(createRequire(join(projectRoot, 'package.json')).resolve('agentdb'));
+    }
+    catch {
+        return { error: DEPS_MISSING };
+    }
+    for (const name of candidates) {
+        const ancestor = findAncestorWithModule(agentdbDir, name);
+        if (ancestor === undefined)
+            continue;
+        try {
+            return { url: pathToFileURL(createRequire(join(ancestor, 'package.json')).resolve(name)).href };
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return { error: DEPS_MISSING };
+}
+/**
+ * D1 (ADR-001): builds the `transformers` pipeline DIRECTLY — the exact call agentdb's own
+ * `EmbeddingService.embed` makes for a symmetric model (`pipeline(text, { pooling:'mean',
+ * normalize:true })`, `EmbeddingService.js:205`), never through agentdb's wrapper class. This is
+ * the ONLY way to request `dtype:'q8'` at pipeline construction (D2) — `EmbeddingService.initialize`
+ * hardcodes `transformers.pipeline('feature-extraction', model)` with no dtype option at all, so a
+ * quantized store is unreachable through it at any dtype but fp32.
+ *
+ * COMPAT FALLBACK (deviation from the ADR's literal "иначе ядро отдаёт {error} как сегодня" —
+ * documented in `features/embed-daemon-memory/07_code_changes/change_manifest.md`): when
+ * `@huggingface/transformers`/`@xenova/transformers` cannot be resolved directly AND the requested
+ * dtype is the default `fp32`, this falls back to agentdb's `EmbeddingService` exactly as this
+ * function's pre-T2 body did. Measured (2026-09-16): seven OTHER features' test files
+ * (`agentdb-index.test.ts`, `agentdb-snapshot-{consistency,lock,rotation}.test.ts`, `brain.test.ts`,
+ * `quarantine-mirror-projection.test.ts`, `store-generation.test.ts`, `vector-tier{,​-rvf}.test.ts`)
+ * fake ONLY `agentdb/controllers/EmbeddingService.js` for their offline fixtures, never a
+ * `@huggingface/transformers`/`@xenova/transformers` stub — a literal "no fallback" implementation
+ * reddens all of them (out of scope here: `.claude/rules/cross-runtime-concurrency.md` and this
+ * feature's own hard rule both forbid touching another feature's files). `dtype:'q8'` NEVER falls
+ * back (NFR-4) — an unresolvable transformers module with `dtype:'q8'` requested is a hard `{error}`
+ * naming the model and dtype, exactly as the ADR specifies; only the fp32 path is widened.
+ */
+async function initAgentdbEmbedder(projectRoot, agentdbDir, model, dim, dtype) {
+    const transformers = resolveTransformersModule(projectRoot);
+    if (!('error' in transformers)) {
+        try {
+            const { pipeline } = (await import(transformers.url));
+            const extractor = await pipeline('feature-extraction', model, dtype === 'q8' ? { dtype: 'q8' } : {});
+            embedderCachePipelinesBuilt += 1; // F6: the real primitive ran and returned a usable extractor
+            return { embed: async (t) => Float32Array.from((await extractor(t, { pooling: 'mean', normalize: true })).data) };
+        }
+        catch (err) {
+            return { error: `embedder init failed (model ${model}, dtype ${dtype}): ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    if (dtype === 'q8') {
+        // NFR-4: a quantized store must never silently downgrade to fp32 for lack of a transformers
+        // install — the caller needs to know exactly why q8 is unreachable here.
+        return { error: `embedder init failed (model ${model}, dtype ${dtype}): ${transformers.error}` };
+    }
+    return initViaAgentdbEmbeddingService(agentdbDir, model, dim);
 }
-async function initAgentdbEmbedder(agentdbDir, model, dim) {
+/** The pre-T2 implementation, preserved verbatim as the fp32-only COMPAT FALLBACK documented on
+ * {@link initAgentdbEmbedder} above. */
+async function initViaAgentdbEmbeddingService(agentdbDir, model, dim) {
     try {
         const { EmbeddingService } = (await import(pathToFileURL(join(agentdbDir, 'controllers', 'EmbeddingService.js')).href));
         const emb = new EmbeddingService({
@@ -360,6 +619,7 @@ async function initAgentdbEmbedder(agentdbDir, model, dim) {
             rolePolicy: { kind: 'symmetric' },
         });
         await emb.initialize();
+        embedderCachePipelinesBuilt += 1; // F6: the COMPAT FALLBACK's own primitive ran
         return { embed: (t) => emb.embed(t) };
     }
     catch (err) {
@@ -367,11 +627,45 @@ async function initAgentdbEmbedder(agentdbDir, model, dim) {
     }
 }
 /**
- * Resolve agentdb's `EmbeddingService` from the PROJECT (same dynamic-resolution discipline as
- * {@link indexPatternsToAgentdb}); every dz call site uses the same resolved model so query and row
- * vectors stay in the same space. Cached per process — see {@link embedderCache} above.
+ * D2 (`embed-daemon-memory`): the dtype a QUERY/write is embedded with is the STORE's own dtype
+ * (its manifest) when the store already exists, falling back to the CONFIGURED dtype only for a
+ * store that does not exist yet (its first-ever write picks up the config). This is the ONE place
+ * that decision is made — {@link resolveAgentdbEmbedder} calls it so every caller (search, an
+ * ordinary incremental index) agrees; `reindexAgentdbRows` is the sole exception (T2/plan): it
+ * stamps the manifest with the NEW configured dtype BEFORE it re-embeds, so by the time this
+ * function runs during a reindex the manifest already names the new dtype — config and manifest
+ * necessarily agree at that point, which is what makes reindex "the one place dtype changes".
  */
-export async function resolveAgentdbEmbedder(projectRoot) {
+export function resolveStoreEmbedDtype(projectRoot, dbPath) {
+    const configured = resolveEmbedModel(projectRoot);
+    if ('error' in configured)
+        return { error: configured.error };
+    const manifest = readEmbedManifest(resolveAgentdbPath(projectRoot, dbPath));
+    // Fix round 1 (Codex #4): a manifest dtype that is PRESENT but unrecognized must refuse, not fall
+    // through to the configured default — the same discipline guardEmbedSpace applies, needed here too
+    // because THIS is what resolveAgentdbEmbedder actually keys its cache and pipeline construction on.
+    if (manifest?.readError !== undefined) {
+        return { error: `embedding manifest unreadable (${manifest.readError}); run dz vector reindex` };
+    }
+    if (manifest?.dtypeError !== undefined) {
+        return { error: `unknown embedding dtype "${manifest.dtypeError}" in manifest; run dz vector reindex` };
+    }
+    return manifest?.dtype ?? configured.dtype;
+}
+/**
+ * Resolve the shared embedder from the PROJECT (same dynamic-resolution discipline as
+ * {@link indexPatternsToAgentdb}); every dz call site uses the same resolved model/dtype so query
+ * and row vectors stay in the same space. Cached per process — see {@link embedderCache} above.
+ *
+ * Fix round 1 (F1, doc correction — the prior wording was misleading): `dbPath` is passed straight
+ * to {@link resolveStoreEmbedDtype}, which calls {@link resolveAgentdbPath}`(projectRoot, dbPath)` —
+ * and THAT function already returns the project's DEFAULT store path (`<project>/.dz/agentdb.db`,
+ * or `AGENTDB_PATH`) when `dbPath` is omitted, not "no path". So an omitted `dbPath` still reads the
+ * default store's OWN manifest when one exists; the CONFIGURED dtype is used only as the fallback
+ * for a store that has no manifest yet (i.e. does not exist, or predates this feature) — never as
+ * the default behaviour for "no dbPath given".
+ */
+export async function resolveAgentdbEmbedder(projectRoot, dbPath) {
     let agentdbDir;
     try {
         const req = createRequire(join(projectRoot, 'package.json'));
@@ -383,12 +677,15 @@ export async function resolveAgentdbEmbedder(projectRoot) {
     const model = resolveEmbedModel(projectRoot);
     if ('error' in model)
         return { error: model.error };
-    const key = `${agentdbDir}|${model.model}|${model.dim}`;
+    const dtype = resolveStoreEmbedDtype(projectRoot, dbPath);
+    if (typeof dtype === 'object' && 'error' in dtype)
+        return { error: dtype.error };
+    const key = `${agentdbDir}|${model.model}|${model.dim}|${dtype}`;
     const hit = embedderCache.get(key);
     if (hit !== undefined)
         return hit;
     embedderCacheInitializations += 1;
-    const promise = initAgentdbEmbedder(agentdbDir, model.model, model.dim);
+    const promise = initAgentdbEmbedder(projectRoot, agentdbDir, model.model, model.dim, dtype);
     embedderCache.set(key, promise);
     // FR-3: an init failure must not stick — evict so the next call retries instead of replaying
     // the same {error} forever. `.catch` here only guards a rejection that slips past
@@ -525,7 +822,10 @@ export async function searchAgentdbPatterns(projectRoot, query, opts = {}) {
         });
         if (!guard.ok)
             return { hits: [], error: guard.error };
-        const emb = await resolveAgentdbEmbedder(projectRoot);
+        // D2: the query is embedded with the STORE's own dtype (the guard above already proved the
+        // manifest and the config agree) — pass the resolved store path so resolveAgentdbEmbedder reads
+        // the same manifest guardEmbedSpace just read, never the config's dtype in isolation.
+        const emb = await resolveAgentdbEmbedder(projectRoot, resolveAgentdbPath(projectRoot, opts.dbPath));
         if ('error' in emb)
             return { hits: [], error: emb.error };
         let qvec;
@@ -909,6 +1209,27 @@ export function bumpAgentdbUses(projectRoot, dzIds, opts = {}) {
         return { bumped: 0, error: `uses bump failed: ${err instanceof Error ? err.message : String(err)}` };
     }
 }
+/**
+ * Fix-round 1 (CRITICAL, item 1b — the belt): whether {@link reindexAgentdbRows} must run its own
+ * rescue bump, given the DELETE's own observed `changes` count and the nested
+ * {@link indexPatternsToAgentdb} call's result. Exported test-only (same convention as
+ * {@link resetAgentdbEmbedderCache}) so the DECISION can be exercised directly and deterministically,
+ * independent of forcing a real concurrent bump-lock race.
+ *
+ * `!nestedBumped && (deleteChanges > 0 || indexed.indexed > 0 || indexed.error !== undefined)`:
+ * - `deleteChanges > 0` — the DELETE genuinely removed rows; the store changed regardless of the
+ *   nested call's outcome.
+ * - `indexed.indexed > 0` — the nested call committed rows itself but its OWN bump failed
+ *   (`generationBumped: false`) or was never attempted.
+ * - `indexed.error !== undefined` — the nested call's post-write state is UNKNOWN (item 1a: an error
+ *   here may still carry accurate `indexed`/`generationBumped` facts, but a caller must not assume a
+ *   future error path will). C-1: when in doubt, bump — an extra bump only over-invalidates a cache
+ *   (safe), a missed one serves stale data (not safe).
+ */
+export function needsRescueBump(deleteChanges, indexed) {
+    const nestedBumped = indexed.generationBumped === true;
+    return !nestedBumped && (deleteChanges > 0 || indexed.indexed > 0 || indexed.error !== undefined);
+}
 export async function reindexAgentdbRows(projectRoot, rows, opts = {}) {
     const dbFile = resolveAgentdbPath(projectRoot, opts.dbPath);
     const ms = Date.now();
@@ -1086,6 +1407,11 @@ export async function reindexAgentdbRows(projectRoot, rows, opts = {}) {
             }
         };
         let stale = [];
+        // T1 (`store-generation-residuals`, record `3cfcec83`): the OBSERVED fact — `changes` from the
+        // DELETE's own prepared-statement result, never inferred from `rows.length` or any other adjacent
+        // signal (06_implementation_plan.md's T1 section names exactly that inference as the mistake to
+        // avoid). Declared outside the `db` block so it survives to the bump decision below `db.close()`.
+        let deleteChanges = 0;
         try {
             mkdirSync(dirname(dbFile), { recursive: true });
             const db = new Database(dbFile);
@@ -1105,9 +1431,9 @@ export async function reindexAgentdbRows(projectRoot, rows, opts = {}) {
                 const delPat = db.prepare(`DELETE FROM reasoning_patterns WHERE task_type IN (${placeholders})`);
                 const tx = db.transaction(() => {
                     delEmb.run(...taskTypes);
-                    delPat.run(...taskTypes);
+                    return delPat.run(...taskTypes).changes;
                 });
-                tx();
+                deleteChanges = tx();
             }
             finally {
                 db.close();
@@ -1121,6 +1447,16 @@ export async function reindexAgentdbRows(projectRoot, rows, opts = {}) {
             writeEmbedManifest(dbFile, currentEmbedManifest(model, version, 'agentdb'));
             const indexed = await indexPatternsToAgentdb(projectRoot, rows, { dbPath: dbFile });
             if (indexed.error !== undefined) {
+                // Fix-round 1 (CRITICAL, item 1b — the belt): before this fix, NO bump was attempted anywhere
+                // on this branch, regardless of `deleteChanges` — the DELETE above may have genuinely removed
+                // rows from the store (a real change on disk) and the counter would never move to reflect it,
+                // even though `rollback()` below may itself fail and leave that changed state in place. An
+                // error from the nested call means the post-write state is UNKNOWN — C-1 resolves unknown in
+                // favour of bumping (a spurious extra bump only over-invalidates a cache; a missed one serves
+                // stale data). `needsRescueBump` is the SAME decision used on the success path below — one
+                // rule, not two that could drift apart.
+                if (needsRescueBump(deleteChanges, indexed))
+                    bumpStoreGeneration(projectRoot, opts.dbPath);
                 const rb = await rollback();
                 if (rb.restored === 'failed')
                     rollbackFailed = true; // AM-3: the `finally` below must not clear the marker
@@ -1147,13 +1483,36 @@ export async function reindexAgentdbRows(projectRoot, rows, opts = {}) {
                     throw err;
                 snapshots = { kept: [], removed: [], removedBytes: 0, keep: keepSnapshots, errors: [`lock busy: ${err.message}`] };
             }
-            // AM-1 (fix-round): `reindexAgentdbRows` is itself a mutator (the DELETE above rebuilds the
-            // owned task types) — it must not rely SOLELY on `indexPatternsToAgentdb`'s own internal bump,
-            // because that call is a no-op (and bumps nothing) when `rows` is empty, yet the DELETE it ran
-            // just above unconditionally changed the store. Bumping again here when `rows` was non-empty
-            // (the common case, already bumped once inside `indexPatternsToAgentdb`) is harmless — the
-            // counter is a monotonic "did anything change" signal, not a per-operation tally.
-            bumpStoreGeneration(projectRoot, opts.dbPath);
+            // T1 (`store-generation-residuals`, record `3cfcec83` — supersedes the AM-1 comment this
+            // replaces, which documented the double-bump as "harmless" rather than fixing it). AM-1's
+            // underlying concern stands unchanged: `reindexAgentdbRows` is ITSELF a mutator (the DELETE
+            // above rebuilds the owned task types) and must not rely solely on `indexPatternsToAgentdb`'s
+            // own internal bump, because that nested call is a no-op — bumps nothing, sets no
+            // `generationBumped` — when `rows` is empty, yet the DELETE just above may have changed the
+            // store regardless of whether there was anything to re-insert.
+            //
+            // The rule (now the shared {@link needsRescueBump} helper — fix-round 1, item 1b — used
+            // identically on the error branch above) uses OBSERVED facts, never inferred from an adjacent
+            // signal (the mistake named in the plan's T1 section, fresh from the worker-ceiling fix that
+            // predates this one): `deleteChanges` is the DELETE's own `changes` count, read directly off the
+            // prepared-statement result; `indexed.generationBumped` is a field `indexPatternsToAgentdb` sets
+            // ONLY where its own bump actually ran (never guessed from `indexed.indexed > 0`, which is
+            // itself a real fact but a DIFFERENT one — see below).
+            //
+            // The condition is intentionally `!nestedBumped && (deleteChanges > 0 || indexed.indexed > 0 ||
+            // indexed.error !== undefined)`, NOT the narrower `deleteChanges > 0 && !nestedBumped` the
+            // plan's prose formula reads as: a bare `deleteChanges > 0` gate would MISS the case where the
+            // DELETE removed nothing (a first-ever reindex of these task types) but the nested insert then
+            // ran and its OWN bump failed (`indexed.generationBumped === false`, e.g. a transient lock
+            // timeout) — under the narrower gate the store would have changed on disk with no rescue bump at
+            // all, a genuine under-bump. C-1 (`01_requirements.md`) makes correctness here non-negotiable:
+            // "при сомнении поднимать счётчик ЛИШНИЙ раз безопаснее, чем не поднять" — so the OR-of-facts
+            // form below is what actually ships; it satisfies every case FR-1's AC-1 enumerates AND closes
+            // the gaps the plan's literal formula and the pre-fix-round-1 condition left open, verified by
+            // exhaustive case analysis in `features/store-generation-residuals/07_code_changes/change_manifest.md`.
+            if (needsRescueBump(deleteChanges, indexed)) {
+                bumpStoreGeneration(projectRoot, opts.dbPath);
+            }
             return {
                 reembedded: indexed.indexed,
                 model: model.model,