agentic-qe 3.12.1 → 3.12.3

package/dist/integrations/ruvector/rvf-store-integrity.js

@@ -0,0 +1,137 @@
+/**
+ * RVF store integrity helpers (issue #563).
+ *
+ * An export that is killed mid-write leaves a store that was created but never
+ * completed. Such a file cannot be opened (`RVF error 0x0106: ManifestNotFound`)
+ * and cannot be created over either, because the path already exists
+ * (`RVF error 0x0303: FsyncFailed`). Both paths fail forever, so the RVF
+ * backend stays disabled for the life of the project until someone deletes the
+ * file by hand.
+ *
+ * Recovery has to be evidence-based rather than fingerprint-based. Measured
+ * against @ruvector/rvf-node 0.1.8:
+ *
+ *   • A *valid, empty* store is 162 bytes with magic `SFVR` — byte-for-byte
+ *     the size the issue reports as "truncated: header only". Size and magic
+ *     therefore cannot distinguish a broken store from a healthy empty one.
+ *   • `<store>.lock` is a 104-byte record with magic `FLVR` and the owning pid
+ *     as a little-endian u32 at offset 4. `FLVR` in a lock is the *normal*
+ *     case — the issue reads it as "RVF store bytes leaked into the lock", but
+ *     the store magic is `SFVR`; a 104-byte `FLVR` lock is just a live-or-stale
+ *     lock record.
+ *
+ * So the only sound trigger is "open failed *and* create failed": at that point
+ * the file is provably unusable. The lock's pid is used as a *guard* — if it is
+ * held by a live process, the store is presumed healthy and left alone.
+ */
+import { existsSync, openSync, readSync, closeSync, renameSync, unlinkSync } from 'fs';
+/** Magic of a lock record (the store's own magic is `SFVR`). */
+const LOCK_MAGIC = 'FLVR';
+/** Byte offset of the owning pid within a lock record (u32 LE). */
+const LOCK_PID_OFFSET = 4;
+/** Sidecars that belong to a store and must be quarantined alongside it. */
+const STORE_SIDECAR_SUFFIXES = ['', '.idmap.json', '.manifest.json'];
+/** Read the first `n` bytes of a file, or null if unreadable/shorter. */
+function readHead(path, n) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const buf = Buffer.alloc(n);
+        if (readSync(fd, buf, 0, n, 0) < n)
+            return null;
+        return buf;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/** True when a process with `pid` exists (signal 0 probes without delivering). */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but belongs to another user — still alive.
+        return err.code === 'EPERM';
+    }
+}
+/** The pid recorded in `<rvfPath>.lock`, or null if there is no readable lock. */
+export function readLockOwnerPid(rvfPath) {
+    const head = readHead(`${rvfPath}.lock`, LOCK_PID_OFFSET + 4);
+    if (!head || head.subarray(0, 4).toString('latin1') !== LOCK_MAGIC)
+        return null;
+    const pid = head.readUInt32LE(LOCK_PID_OFFSET);
+    return pid > 0 ? pid : null;
+}
+/**
+ * True when the store's lock is held by a process that is still running.
+ *
+ * Deliberately conservative: an unreadable or pid-less lock reports false (the
+ * caller's open already failed, so there is nothing to protect), while a live
+ * pid reports true and blocks recovery. Pid reuse can only produce a false
+ * "alive", which fails safe — we leave the store alone.
+ */
+export function isLockHeldByLiveProcess(rvfPath) {
+    const pid = readLockOwnerPid(rvfPath);
+    if (pid === null)
+        return false;
+    return pid !== process.pid && isPidAlive(pid);
+}
+/**
+ * Move an unusable store and its sidecars aside so the next create succeeds.
+ * Returns the quarantine base path, or null if nothing was quarantined.
+ *
+ * Only call this once open *and* create have both failed — that is the proof
+ * the file is unusable. The store is a derived cache, rebuilt from the unified
+ * DB, so quarantining is recoverable; we move rather than delete because the
+ * bytes may hold writes that never reached SQLite, and they are the only
+ * evidence if this recurs.
+ */
+export function quarantineUnusableStore(rvfPath, reason) {
+    if (!existsSync(rvfPath))
+        return null;
+    // Never pull a store out from under a live peer.
+    if (isLockHeldByLiveProcess(rvfPath)) {
+        console.warn(`[RVF] ${rvfPath} is unusable but its lock is held by a live process — ` +
+            'leaving it alone and degrading to SQLite for this run.');
+        return null;
+    }
+    // Keyed by pid, not a timestamp: a crash-loop quarantining the same file
+    // repeatedly overwrites its own copy instead of filling .agentic-qe/ with
+    // one corrupt store per startup.
+    const quarantineBase = `${rvfPath}.corrupt-${process.pid}`;
+    for (const sidecar of STORE_SIDECAR_SUFFIXES) {
+        const from = `${rvfPath}${sidecar}`;
+        if (!existsSync(from))
+            continue;
+        try {
+            renameSync(from, `${quarantineBase}${sidecar}`);
+        }
+        catch {
+            // A failed quarantine must not throw and take down the caller; the
+            // caller's retry will simply fail again and degrade as before.
+        }
+    }
+    // The store is gone, so its lock — stale by definition here — goes with it.
+    try {
+        if (existsSync(`${rvfPath}.lock`))
+            unlinkSync(`${rvfPath}.lock`);
+    }
+    catch {
+        // best-effort
+    }
+    console.warn(`[RVF] Quarantined unusable store ${rvfPath} → ${quarantineBase} (${reason}). ` +
+        'It is a derived cache and will be rebuilt from the unified DB. ' +
+        'Please report a recurrence with the quarantined files (issue #563).');
+    return quarantineBase;
+}
+//# sourceMappingURL=rvf-store-integrity.js.map

package/dist/integrations/ruvector/shared-rvf-adapter.js

@@ -13,6 +13,9 @@
 // Issue #516: lightweight, sqlite-free project-root resolver (static import so it
 // resolves under the test runner; avoids pulling unified-memory's sqlite graph).
 import { findProjectRoot } from '../../kernel/project-root.js';
+// Issue #563: static import — this module is fs-only, and a require() here
+// would not resolve under the test runner.
+import { quarantineUnusableStore, isLockHeldByLiveProcess, readLockOwnerPid, } from './rvf-store-integrity.js';
 let sharedAdapter = null;
 let initAttempted = false;
 // ---------------------------------------------------------------------------
@@ -131,16 +134,23 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
     // .lock that subsequent invocations interpret as `LockHeld`. Since AQE
     // CLI is overwhelmingly single-shot serial, the realistic case is "the
     // prior process is dead and the lock is stale". We unlink the .lock and
-    // retry open exactly once. If a genuinely-live peer existed, it still
-    // holds the file open — but the binding's lock is content-based (lock
-    // file presence), so this is a best-effort cooperative recovery rather
-    // than an OS-level lock break.
+    // retry open exactly once.
+    //
+    // Issue #563: the lock record turns out to carry its owner's pid (u32 LE at
+    // offset 4, after the `FLVR` magic), so "is it stale?" is now a check rather
+    // than an assumption. This previously unlinked the lock unconditionally,
+    // which breaks a genuinely-live peer — the one case the old comment admitted
+    // it could not distinguish.
     if (!opened && isLockHeld(openErr)) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const fs = require('fs');
             const lockPath = `${rvfPath}.lock`;
-            if (fs.existsSync(lockPath)) {
+            if (fs.existsSync(lockPath) && isLockHeldByLiveProcess(rvfPath)) {
+                console.warn(`[RVF] ${rvfPath} is locked by a live process (pid ${readLockOwnerPid(rvfPath)}) — ` +
+                    'not breaking the lock; degrading to SQLite for this run.');
+            }
+            else if (fs.existsSync(lockPath)) {
                 fs.unlinkSync(lockPath);
                 console.warn(`[RVF] Removed stale lock file at ${lockPath} (prior process exited without closing). ` +
                     'Retrying open. If you see this repeatedly under live concurrency, file an issue.');
@@ -187,6 +197,14 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
             return reopened;
         }
         catch {
+            // Pass 4 (#563): open failed, create failed, re-open failed. The file is
+            // provably unusable — the signature of an export killed mid-write, which
+            // used to disable the RVF backend permanently. Quarantine it (unless a
+            // live process holds its lock) and rebuild the derived cache.
+            const quarantined = quarantineUnusableStore(rvfPath, createErr instanceof Error ? createErr.message : String(createErr));
+            if (quarantined) {
+                return createFn(rvfPath, dimensions);
+            }
             // Fall through with the more informative original error.
             throw createErr instanceof Error ? createErr : new Error(String(createErr));
         }

package/dist/learning/pattern-store.js

@@ -11,7 +11,13 @@ import { v4 as uuidv4 } from 'uuid';
 import { findProjectRoot } from '../kernel/project-root.js';
 import { ok, err } from '../shared/types/index.js';
 import { RvfPatternStore } from './rvf-pattern-store.js';
-import { createRvfStore as _createRvfStore, isRvfNativeAvailable } from '../integrations/ruvector/rvf-native-adapter.js';
+import { createRvfStore as _createRvfStore, openRvfStore as _openRvfStore, isRvfNativeAvailable, } from '../integrations/ruvector/rvf-native-adapter.js';
+// Issue #563: static imports — a require() of a source module resolves in the
+// esbuild bundle but throws under the test runner, which silently changed which
+// code path tests exercised. Neither module loads the native binding at import
+// time, so this costs nothing at startup.
+import { quarantineUnusableStore } from '../integrations/ruvector/rvf-store-integrity.js';
+import { getSharedRvfAdapter } from '../integrations/ruvector/shared-rvf-adapter.js';
 import { toErrorMessage, toError } from '../shared/error-utils.js';
 import { calculateQualityScore, shouldPromotePattern, validateQEPattern, mapQEDomainToAQE, PROMOTION_THRESHOLD, } from './qe-patterns.js';
 import { applyFilterSync } from '../integrations/ruvector/filter-adapter.js';
@@ -1419,7 +1425,9 @@ export function createPatternStore(memory, config) {
                 // deadlock on the native lock.
                 let useSharedAdapter = false;
                 try {
-                    const { getSharedRvfAdapter } = require('../integrations/ruvector/shared-rvf-adapter.js');
+                    // Statically imported (#563): this require() throws "Cannot find
+                    // module" under the test runner, so every test silently took the
+                    // fallback ladder below instead of this preferred path.
                     const shared = getSharedRvfAdapter(rvfDir, mergedConfig.embeddingDimension);
                     if (shared) {
                         useSharedAdapter = true;
@@ -1439,11 +1447,13 @@ export function createPatternStore(memory, config) {
                     // open first, fall back to create, retry open on create-race.
                     // (Jordi #439 / RUFLO P020.)
                     const store = new RvfPatternStore((path, dim) => {
-                        // eslint-disable-next-line @typescript-eslint/no-require-imports
-                        const { openRvfStore } = require('../integrations/ruvector/rvf-native-adapter.js');
+                        // Statically imported (#563): a require() here resolves in the
+                        // esbuild bundle but throws "Cannot find module" under the test
+                        // runner, so this ladder — including its corruption recovery —
+                        // was unreachable from any test.
                         const tryOpen = () => {
                             try {
-                                return openRvfStore(path);
+                                return _openRvfStore(path);
                             }
                             catch {
                                 return null;
@@ -1467,6 +1477,14 @@ export function createPatternStore(memory, config) {
                             adapter = tryOpen();
                             if (adapter && adapter.dimension() === dim)
                                 return adapter;
+                            // Issue #563: open failed, create failed, re-open failed — the
+                            // store is provably unusable (an export killed mid-write leaves
+                            // exactly this). Without recovery, RvfPatternStore.initialize()
+                            // logs "vector search is DISABLED" and stays that way for the
+                            // life of the process.
+                            if (quarantineUnusableStore(path, createErr instanceof Error ? createErr.message : String(createErr))) {
+                                return _createRvfStore(path, dim);
+                            }
                             throw createErr;
                         }
                     }, { rvfPath, base: mergedConfig });

package/dist/learning/qe-flywheel/platform-signer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Witness-key bridge (qe-harness issue #7) — sign flywheel receipts with the ONE
+ * Cognitum platform identity instead of a self-generated key, so every QE receipt
+ * (engine campaign · flywheel promotion · coherence verdict) chains to the same
+ * externally-verifiable key (`QE_WITNESS_PUBLIC_KEYS_JSON` allowlist, fingerprint
+ * `f1ac28607da49ec1`).
+ *
+ * `createSigner` already accepts a 32-byte Ed25519 seed → deterministic keypair.
+ * The platform key is delivered as `QE_WITNESS_SIGNING_KEY` — a JSON
+ * `{ publicKey, privateKey }` of PEM strings (same shape qe-harness Stage-B reads
+ * from Secret Manager). We derive the seed from that private key and hand it to
+ * `createSigner`, reproducing the exact platform keypair.
+ *
+ * Graceful: returns null when the env var is absent/malformed, so the flywheel
+ * keeps its self-generated-key behaviour where the platform key isn't provided.
+ * Env-reading lives HERE, not in the dependency-free `receipt.ts` core.
+ */
+import { type Signer } from './receipt.js';
+/**
+ * Extract the raw 32-byte Ed25519 seed from a PKCS#8 private-key PEM. Throws if the
+ * key is not an Ed25519 PKCS#8 key (wrong curve / format).
+ */
+export declare function seedFromPkcs8Pem(privateKeyPem: string): Buffer;
+/**
+ * Build a {@link Signer} bound to the Cognitum platform identity from
+ * `QE_WITNESS_SIGNING_KEY`, or null when it is unset/malformed (graceful fallback).
+ * The returned signer's `keyId` equals the platform witness fingerprint, so a
+ * verifier can attribute the receipt to the platform via the same allowlist that
+ * accepts qe-harness evidence bundles.
+ */
+export declare function platformSigner(env?: NodeJS.ProcessEnv): Signer | null;
+//# sourceMappingURL=platform-signer.d.ts.map

package/dist/learning/qe-flywheel/platform-signer.js

@@ -0,0 +1,60 @@
+/**
+ * Witness-key bridge (qe-harness issue #7) — sign flywheel receipts with the ONE
+ * Cognitum platform identity instead of a self-generated key, so every QE receipt
+ * (engine campaign · flywheel promotion · coherence verdict) chains to the same
+ * externally-verifiable key (`QE_WITNESS_PUBLIC_KEYS_JSON` allowlist, fingerprint
+ * `f1ac28607da49ec1`).
+ *
+ * `createSigner` already accepts a 32-byte Ed25519 seed → deterministic keypair.
+ * The platform key is delivered as `QE_WITNESS_SIGNING_KEY` — a JSON
+ * `{ publicKey, privateKey }` of PEM strings (same shape qe-harness Stage-B reads
+ * from Secret Manager). We derive the seed from that private key and hand it to
+ * `createSigner`, reproducing the exact platform keypair.
+ *
+ * Graceful: returns null when the env var is absent/malformed, so the flywheel
+ * keeps its self-generated-key behaviour where the platform key isn't provided.
+ * Env-reading lives HERE, not in the dependency-free `receipt.ts` core.
+ */
+import { createPrivateKey } from 'node:crypto';
+import { createSigner } from './receipt.js';
+/** DER prefix of an Ed25519 PKCS#8 private key (16 bytes) preceding the 32-byte seed. */
+const ED25519_PKCS8_PREFIX = '302e020100300506032b657004220420';
+/**
+ * Extract the raw 32-byte Ed25519 seed from a PKCS#8 private-key PEM. Throws if the
+ * key is not an Ed25519 PKCS#8 key (wrong curve / format).
+ */
+export function seedFromPkcs8Pem(privateKeyPem) {
+    const der = createPrivateKey(privateKeyPem).export({ format: 'der', type: 'pkcs8' });
+    if (der.length !== 48 || der.subarray(0, 16).toString('hex') !== ED25519_PKCS8_PREFIX) {
+        throw new Error('not an Ed25519 PKCS#8 private key (cannot derive a 32-byte seed)');
+    }
+    return Buffer.from(der.subarray(16, 48));
+}
+/**
+ * Build a {@link Signer} bound to the Cognitum platform identity from
+ * `QE_WITNESS_SIGNING_KEY`, or null when it is unset/malformed (graceful fallback).
+ * The returned signer's `keyId` equals the platform witness fingerprint, so a
+ * verifier can attribute the receipt to the platform via the same allowlist that
+ * accepts qe-harness evidence bundles.
+ */
+export function platformSigner(env = process.env) {
+    const raw = env.QE_WITNESS_SIGNING_KEY;
+    if (!raw)
+        return null;
+    let key;
+    try {
+        key = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!key.privateKey)
+        return null;
+    try {
+        return createSigner(seedFromPkcs8Pem(key.privateKey));
+    }
+    catch {
+        return null; // wrong key type / unparseable — fall back to a self-generated signer
+    }
+}
+//# sourceMappingURL=platform-signer.js.map

package/dist/learning/qe-flywheel/receipt.js

@@ -10,9 +10,16 @@
  * Ed25519 via Node's built-in crypto — dependency-free (ADR-118 §6).
  */
 import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, } from 'node:crypto';
-/** Derive a stable key id from a public key PEM. */
+/**
+ * Derive a stable key id from a public key PEM. The PEM is trimmed first so the id
+ * is invariant to trailing whitespace (PEM exports carry a trailing newline) AND
+ * matches the Cognitum platform witness fingerprint scheme — `sha256(pem.trim())`
+ * truncated to 16 hex (qe-harness `witness.ts` / meta-llm `qe-witness.ts`). This lets
+ * a flywheel receipt signed with the platform key carry the SAME id the platform
+ * allowlist (`QE_WITNESS_PUBLIC_KEYS_JSON`) recognizes. See platform-signer.ts.
+ */
 function keyIdOf(publicKeyPem) {
-    return createHash('sha256').update(publicKeyPem).digest('hex').slice(0, 16);
+    return createHash('sha256').update(publicKeyPem.trim()).digest('hex').slice(0, 16);
 }
 /**
  * Create an Ed25519 signer. With a 32-byte seed (hex or Buffer) the keypair is