agentic-qe 3.14.5 → 3.14.7

package/.claude/skills/skills-manifest.json

@@ -940,7 +940,7 @@
   },
   "metadata": {
     "generatedBy": "Agentic QE Fleet",
-    "fleetVersion": "3.14.5",
+    "fleetVersion": "3.14.7",
     "manifestVersion": "1.4.0",
     "lastUpdated": "2026-04-13T00:00:00.000Z",
     "contributors": [

package/CHANGELOG.md

@@ -5,6 +5,156 @@ All notable changes to the Agentic QE project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.14.7] - 2026-10-02
+
+This patch makes browser setup opt-in, so installing AQE no longer downloads
+Chrome. The MCP server now always shuts down cleanly: it releases its pattern
+store lock and closes the learning database however it is stopped. Pattern
+search uses keyword and vector matching together, with a keyword index that
+repairs itself. Test generation can build real assertions from examples you
+supply, and no longer guesses expected values.
+
+### Changed
+
+- **Browser setup is now opt-in.** `npm install agentic-qe` and `aqe init` no
+  longer install Vibium or download a browser. Run
+  `aqe init --browser-engine` when you need browser-based testing (visual,
+  accessibility, e2e). Vibium 26.8.21 is now an optional peer dependency, and
+  `--no-browser-engine` skips browser setup explicitly. Existing installs are
+  not affected ([#797], [#812]).
+- **Test generation no longer guesses expected values.** Without examples and
+  without an LLM, `test_generate_enhanced` and `aqe test generate` produce a
+  clearly marked, skipped scaffold instead of generic assertions such as
+  `toBeDefined()`. The coverage estimate is reported as unmeasured rather than
+  as an invented percentage ([#795]).
+- `aqe test generate` now exits with code 1 when generation is rejected, for
+  example when an example names a function the file doesn't export. CI scripts
+  can rely on the exit code ([#811]).
+- Pattern search for routing and `task_orchestrate` uses keyword (FTS5) and
+  vector matching together. Pattern hints now report `similarity`, `score`,
+  `matchType` and `canReuse`, so you can see why a pattern matched. An
+  experience reinforces an existing pattern only when it describes the same
+  task, so unrelated tasks no longer strengthen each other's patterns ([#796]).
+
+### Added
+
+- Behavior examples for test generation: pass `behaviorExamples` to
+  `test_generate_enhanced`, or `--behavior-examples <file>` to
+  `aqe test generate`. Each example gives a function, its arguments and the
+  expected result. The generated assertions come only from those examples
+  (Vitest, Jest and Node's test runner). See
+  `docs/test-generation/deterministic-examples.md` ([#795]).
+- The task audit log reports whether its retained window is complete or
+  truncated, with recorded, retained and dropped counts, through the new
+  `getSnapshot()` and in `getStatistics()` ([#803]).
+
+### Fixed
+
+- The MCP server releases `patterns.rvf.lock` and closes the learning database
+  cleanly on every kind of shutdown: input stream closed, JSON-RPC `shutdown`,
+  SIGTERM/SIGINT, and the shutdown watchdog. This holds for both `aqe-mcp` and
+  `aqe mcp`. Previously the lock was left behind, so the next start had to
+  recover a stale lock, and the database's write-ahead log was not
+  checkpointed ([#802], [#808]).
+- The learning database repairs its keyword search index when it opens.
+  Databases whose sync triggers had gone missing kept a stale index: patterns
+  added later were invisible to keyword search, and deleted ones still matched.
+  The repair recreates the triggers and rebuilds the index without changing
+  any stored patterns. Read-only opens are skipped ([#809]).
+- Invalid behavior examples are rejected with a clear error before any work
+  starts, and no longer trip the test-generation circuit breaker. Previously
+  two bad requests could block test generation for everyone on that MCP
+  server for about 30 seconds ([#795]).
+- Updated `brace-expansion` and `@grpc/grpc-js` in the development dependency
+  tree ([#806]).
+
+[#795]: https://github.com/proffesor-for-testing/agentic-qe/pull/795
+[#796]: https://github.com/proffesor-for-testing/agentic-qe/pull/796
+[#797]: https://github.com/proffesor-for-testing/agentic-qe/pull/797
+[#802]: https://github.com/proffesor-for-testing/agentic-qe/pull/802
+[#803]: https://github.com/proffesor-for-testing/agentic-qe/pull/803
+[#806]: https://github.com/proffesor-for-testing/agentic-qe/pull/806
+[#808]: https://github.com/proffesor-for-testing/agentic-qe/pull/808
+[#809]: https://github.com/proffesor-for-testing/agentic-qe/pull/809
+[#811]: https://github.com/proffesor-for-testing/agentic-qe/pull/811
+[#812]: https://github.com/proffesor-for-testing/agentic-qe/pull/812
+
+## [3.14.6] - 2026-09-29
+
+This patch fixes an `aqe audit verify` crash on stores with no audit chain yet.
+It adds `aqe audit repair` for stores forked by concurrent writers before
+3.14.5, makes repeat `aqe init --auto` runs leave an unchanged project
+untouched, and makes GOAP planning work from the live fleet state. It also
+redacts secrets from AQE's logs and lets keyword matches improve pattern
+search.
+
+### Security
+
+- Secrets are redacted from AQE's structured logs and from logged errors. This
+  covers API keys (`sk-ant-`, `sk-`, `ghp_`, `github_pat_`, `AKIA…`),
+  Bearer/Basic credentials, credentials in URLs, JWTs, PEM private keys,
+  cookies, and values under sensitive keys (`password`, `token`, `apiKey`,
+  `access_token`, …) in objects, JSON text and query strings. Command output
+  such as `aqe memory get` is not changed ([#789]).
+
+### Added
+
+- `aqe audit verify --chain audit` now keeps checking past accidental forks
+  left by pre-3.14.5 concurrent writers, and reports them separately from
+  tampering (`status: "forked"`, `tampered: false`). The new
+  `aqe audit repair --chain audit [--dry-run]` acknowledges those forks with
+  one signed entry. It refuses if anything was tampered with, backs up the
+  database first, and never edits or deletes an existing row. Afterwards verify
+  passes again ([#784]).
+- `goap_status {type:"plans"}` lists saved GOAP plans ([#791]).
+
+### Changed
+
+- Running `aqe init --auto` again on an unchanged project no longer rewrites
+  generated files or creates `.claude/settings.json.backup`. Fresh and repeat
+  runs now produce the same settings: all 13 domains, and pattern promotion at
+  3 successes / 0.7 success rate, which is what the learning runtime actually
+  enforces ([#783]).
+- Keyword matches now contribute to pattern search alongside vector
+  similarity. A keyword-only hit is weighted by how many of the query's terms
+  it matches ([#779]).
+- `qe_coherence_consensus` rejects malformed votes with a clear error. Only a
+  unanimous vote is flagged as possible false consensus, and every
+  recommendation states the real tally ([#781]).
+- `goap_plan` rejects unknown constraint keys and supports
+  `constraints.maxSteps` ([#785]).
+
+### Fixed
+
+- `aqe audit verify --chain audit` and `aqe audit repair --dry-run` no longer
+  crash with `SQLITE_READONLY` on a store that has no audit chain yet (for
+  example after `aqe init --minimal`) or on older stores without the archive
+  table. A store whose live chain was deleted while archived rows remain is
+  now reported as tampered instead of valid ([#788]).
+- GOAP world state is read from the live fleet, and coverage from a coverage
+  report when one exists. Values it can't measure are reported as `null` with
+  `dataSource: "estimated"` instead of defaults labelled as real. Planning for
+  goals such as `achieve-90-percent-coverage` works again, and a plan can be
+  dry-run executed by its ID. A step whose domain call returns an error now
+  fails instead of being recorded as completed ([#785]).
+- A repeat `fleet_init` reports the fleet settings actually in effect instead
+  of echoing the requested ones ([#790]).
+- When another live process holds an RVF lock, AQE logs one clear warning and
+  falls back to SQLite, without a second, misleading `LockHeld` error ([#782]).
+- Updated `ip-address` to 10.7.2 ([#776]).
+
+[#776]: https://github.com/proffesor-for-testing/agentic-qe/pull/776
+[#779]: https://github.com/proffesor-for-testing/agentic-qe/pull/779
+[#781]: https://github.com/proffesor-for-testing/agentic-qe/pull/781
+[#782]: https://github.com/proffesor-for-testing/agentic-qe/pull/782
+[#783]: https://github.com/proffesor-for-testing/agentic-qe/pull/783
+[#784]: https://github.com/proffesor-for-testing/agentic-qe/pull/784
+[#785]: https://github.com/proffesor-for-testing/agentic-qe/pull/785
+[#788]: https://github.com/proffesor-for-testing/agentic-qe/pull/788
+[#789]: https://github.com/proffesor-for-testing/agentic-qe/pull/789
+[#790]: https://github.com/proffesor-for-testing/agentic-qe/pull/790
+[#791]: https://github.com/proffesor-for-testing/agentic-qe/pull/791
+
 ## [3.14.5] - 2026-09-29
 
 This patch makes Agentic QE's results trustworthy for scripts and CI: failed

package/assets/skills/skills-manifest.json

@@ -940,7 +940,7 @@
   },
   "metadata": {
     "generatedBy": "Agentic QE Fleet",
-    "fleetVersion": "3.14.5",
+    "fleetVersion": "3.14.7",
     "manifestVersion": "1.4.0",
     "lastUpdated": "2026-04-13T00:00:00.000Z",
     "contributors": [

package/dist/adapters/ag-ui/event-types.d.ts

@@ -366,7 +366,7 @@ export interface AQEToolResult<T = unknown> {
         readonly domain?: string;
         readonly taskId?: string;
         readonly toolName?: string;
-        readonly dataSource?: 'real' | 'demo' | 'fallback';
+        readonly dataSource?: 'real' | 'demo' | 'fallback' | 'estimated';
     };
 }
 /**

package/dist/audit/witness-chain-hash.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Witness Chain hash primitives (ADR-070).
+ *
+ * Shared by the chain itself, its verifier and the brain-import audit writer
+ * so the link format can never drift between the code that writes a link and
+ * the code that checks it.
+ */
+import type { WitnessEntry } from './witness-chain.js';
+export declare const GENESIS_PREV_HASH: string;
+export declare function sha256(data: string): string;
+/** SHAKE-256 (32-byte output) with SHA-256 fallback for older Node.js runtimes. */
+export declare function shake256(data: string): string;
+export declare function hashWith(algo: string, data: string): string;
+/** Serialize a WitnessEntry to a deterministic string (original 7-field format). */
+export declare function serializeEntry(entry: WitnessEntry): string;
+/** The bytes an Ed25519 witness signature covers (unchanged since ADR-070 Phase 6.2). */
+export declare function signaturePayload(entry: Pick<WitnessEntry, 'prev_hash' | 'action_hash' | 'action_type' | 'timestamp' | 'actor'>): Buffer;
+//# sourceMappingURL=witness-chain-hash.d.ts.map

package/dist/audit/witness-chain-hash.js

@@ -0,0 +1,37 @@
+/**
+ * Witness Chain hash primitives (ADR-070).
+ *
+ * Shared by the chain itself, its verifier and the brain-import audit writer
+ * so the link format can never drift between the code that writes a link and
+ * the code that checks it.
+ */
+import { createHash } from 'crypto';
+export const GENESIS_PREV_HASH = '0'.repeat(64);
+export function sha256(data) {
+    return createHash('sha256').update(data, 'utf-8').digest('hex');
+}
+/** SHAKE-256 (32-byte output) with SHA-256 fallback for older Node.js runtimes. */
+export function shake256(data) {
+    try {
+        return createHash('shake256', { outputLength: 32 }).update(data, 'utf-8').digest('hex');
+    }
+    catch {
+        return sha256(data);
+    }
+}
+export function hashWith(algo, data) {
+    return algo === 'shake256' ? shake256(data) : sha256(data);
+}
+/** Serialize a WitnessEntry to a deterministic string (original 7-field format). */
+export function serializeEntry(entry) {
+    return JSON.stringify({
+        id: entry.id, prev_hash: entry.prev_hash, action_hash: entry.action_hash,
+        action_type: entry.action_type, action_data: entry.action_data,
+        timestamp: entry.timestamp, actor: entry.actor,
+    });
+}
+/** The bytes an Ed25519 witness signature covers (unchanged since ADR-070 Phase 6.2). */
+export function signaturePayload(entry) {
+    return Buffer.from(entry.prev_hash + entry.action_hash + entry.action_type + entry.timestamp + entry.actor, 'utf-8');
+}
+//# sourceMappingURL=witness-chain-hash.js.map

package/dist/audit/witness-chain-repair.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Witness Chain fork repair (re-anchor) — ADR-070, issue #753.
+ *
+ * Stores written before v3.14.5 can contain accidental forks from concurrent
+ * `append()` calls. `verify()` classifies them (witness-chain-verifier.ts) but
+ * keeps `valid: false` until they are acknowledged, so an existing consumer
+ * never sees a previously-broken store silently turn valid.
+ *
+ * Repair acknowledges them by appending ONE signed (when a key is available)
+ * `CHAIN_REANCHOR` entry that lists each unacknowledged fork row (id, parent
+ * id, prev_hash, action_hash), pins the hash of every dead-end row (the
+ * losing race siblings nothing else links to) and records the tip it verified.
+ * It:
+ *
+ * - refuses when any tamper-class break or signature failure exists;
+ * - backs up the database first (`VACUUM INTO <db>.bak-<epoch>`, taken while
+ *   holding the write lock so it is exactly the state being modified) and
+ *   checks the backup (integrity_check, witness row counts) before writing;
+ * - never deletes, moves or rewrites an existing row — history stays as-is
+ *   and `verify()` still lists every fork (`status: 'valid-with-forks'`);
+ * - re-verifies, backs up and appends inside ONE `BEGIN IMMEDIATE`
+ *   transaction, so no writer can slip a row in between;
+ * - checks row counts before/after (live +1, archive unchanged);
+ * - is idempotent: a second run finds nothing unacknowledged and writes nothing.
+ */
+import { type Database as DatabaseType } from 'better-sqlite3';
+import type { WitnessKeyManager } from './witness-key-manager.js';
+import { type ChainStatus, type TamperReason } from './witness-chain-verifier.js';
+export interface WitnessRowCounts {
+    live: number;
+    archive: number;
+}
+export interface VerifySummary {
+    status: ChainStatus;
+    entriesChecked: number;
+    forks: number;
+    unacknowledgedForks: number;
+    tamperedAt?: number;
+    tamperReason?: TamperReason;
+}
+export type RepairAction = 'none' | 'would-reanchor' | 'reanchored' | 'refused';
+export interface RepairResult {
+    action: RepairAction;
+    dryRun: boolean;
+    message: string;
+    before: VerifySummary;
+    after?: VerifySummary;
+    rowsBefore: WitnessRowCounts;
+    rowsAfter: WitnessRowCounts;
+    /** Fork row ids this run acknowledged (or would, on a dry run). */
+    forksAcknowledged: number[];
+    reanchorId?: number;
+    backupPath?: string;
+}
+export interface RepairOptions {
+    /** Path of the database file `db` is opened on — the backup is written next to it. */
+    dbPath: string;
+    dryRun?: boolean;
+    /**
+     * Signs the CHAIN_REANCHOR row and verifies fork/re-anchor signatures.
+     * Pass a read-only (autoGenerate: false) manager for a dry run.
+     */
+    keyManager?: WitnessKeyManager | null;
+    actor?: string;
+}
+/**
+ * Re-anchor a witness chain whose only breaks are accidental forks.
+ * `db` must be a writable connection on `options.dbPath`.
+ */
+export declare function repairWitnessChainForks(db: DatabaseType, options: RepairOptions): Promise<RepairResult>;
+//# sourceMappingURL=witness-chain-repair.d.ts.map

package/dist/audit/witness-chain-repair.js

@@ -0,0 +1,203 @@
+/**
+ * Witness Chain fork repair (re-anchor) — ADR-070, issue #753.
+ *
+ * Stores written before v3.14.5 can contain accidental forks from concurrent
+ * `append()` calls. `verify()` classifies them (witness-chain-verifier.ts) but
+ * keeps `valid: false` until they are acknowledged, so an existing consumer
+ * never sees a previously-broken store silently turn valid.
+ *
+ * Repair acknowledges them by appending ONE signed (when a key is available)
+ * `CHAIN_REANCHOR` entry that lists each unacknowledged fork row (id, parent
+ * id, prev_hash, action_hash), pins the hash of every dead-end row (the
+ * losing race siblings nothing else links to) and records the tip it verified.
+ * It:
+ *
+ * - refuses when any tamper-class break or signature failure exists;
+ * - backs up the database first (`VACUUM INTO <db>.bak-<epoch>`, taken while
+ *   holding the write lock so it is exactly the state being modified) and
+ *   checks the backup (integrity_check, witness row counts) before writing;
+ * - never deletes, moves or rewrites an existing row — history stays as-is
+ *   and `verify()` still lists every fork (`status: 'valid-with-forks'`);
+ * - re-verifies, backs up and appends inside ONE `BEGIN IMMEDIATE`
+ *   transaction, so no writer can slip a row in between;
+ * - checks row counts before/after (live +1, archive unchanged);
+ * - is idempotent: a second run finds nothing unacknowledged and writes nothing.
+ */
+import { existsSync } from 'node:fs';
+import { basename } from 'node:path';
+import { openDatabase } from '../shared/safe-db.js';
+import { WitnessChain } from './witness-chain.js';
+import { sha256, shake256, serializeEntry } from './witness-chain-hash.js';
+import { ownHash, tableExists, } from './witness-chain-verifier.js';
+const VERIFY_OPTIONS = { includeArchive: true };
+function countRows(db) {
+    const n = (table) => (tableExists(db, table)
+        ? db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n
+        : 0);
+    return { live: n('witness_chain'), archive: n('witness_chain_archive') };
+}
+function summarize(r) {
+    return {
+        status: r.status,
+        entriesChecked: r.entriesChecked,
+        forks: r.forks.length,
+        unacknowledgedForks: r.forks.length - r.acknowledgedForks.length,
+        ...(r.tamperedAt !== undefined ? { tamperedAt: r.tamperedAt } : {}),
+        ...(r.tamperReason ? { tamperReason: r.tamperReason } : {}),
+    };
+}
+function unacknowledged(r) {
+    return r.forkDetails.filter((f) => !f.acknowledged)
+        .map(({ id, parentId, prevHash, actionHash }) => ({ id, parentId, prevHash, actionHash }));
+}
+/**
+ * Dead-end rows: every row except the tip whose hash no row's prev_hash
+ * references — the losing sibling of each race. Nothing else vouches for
+ * their content, so the re-anchor pins it. (Checked under both hash algos,
+ * since a child hashes its parent with the CHILD's algorithm.)
+ */
+function deadEndPins(db, tipId) {
+    const referenced = new Set();
+    const prevs = db.prepare('SELECT prev_hash FROM witness_chain UNION ALL SELECT prev_hash FROM witness_chain_archive').pluck().iterate();
+    for (const h of prevs)
+        referenced.add(h);
+    const pins = [];
+    const seen = new Set();
+    for (const table of ['witness_chain', 'witness_chain_archive']) {
+        const rows = db.prepare(`SELECT * FROM ${table} ORDER BY id ASC`).iterate();
+        for (const row of rows) {
+            if (row.id === tipId || seen.has(row.id))
+                continue;
+            seen.add(row.id);
+            const ser = serializeEntry(row);
+            if (!referenced.has(shake256(ser)) && !referenced.has(sha256(ser)))
+                pins.push({ id: row.id, hash: ownHash(row) });
+        }
+    }
+    return pins.sort((a, b) => a.id - b.id);
+}
+function refusal(r) {
+    return `Refusing to repair: tampering detected at id=${r.tamperedAt} (${r.tamperReason}). ` +
+        'Only accidental forks can be re-anchored; restore from a backup and investigate.';
+}
+function nextBackupPath(dbPath) {
+    const base = `${dbPath}.bak-${Math.floor(Date.now() / 1000)}`;
+    if (!existsSync(base))
+        return base;
+    let i = 1;
+    while (existsSync(`${base}-${i}`))
+        i++;
+    return `${base}-${i}`;
+}
+/**
+ * Snapshot the database with VACUUM INTO from a SECOND, read-only connection.
+ * Called while the repairing connection holds the write lock (BEGIN IMMEDIATE)
+ * and before it writes anything, so the snapshot is exactly the state about to
+ * be modified: no other process can commit in between (issue found in review).
+ * The backup must then open clean and hold exactly `expected` witness rows.
+ */
+function backupDatabase(dbPath, expected) {
+    const backupPath = nextBackupPath(dbPath);
+    const reader = openDatabase(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        reader.prepare('VACUUM INTO ?').run(backupPath);
+    }
+    finally {
+        reader.close();
+    }
+    const copy = openDatabase(backupPath, { readonly: true, fileMustExist: true });
+    try {
+        const check = copy.pragma('integrity_check', { simple: true });
+        if (check !== 'ok')
+            throw new Error(`backup integrity_check failed: ${String(check)}`);
+        const counts = countRows(copy);
+        if (counts.live !== expected.live || counts.archive !== expected.archive) {
+            throw new Error(`backup holds ${JSON.stringify(counts)} witness rows, expected ${JSON.stringify(expected)}`);
+        }
+    }
+    finally {
+        copy.close();
+    }
+    return backupPath;
+}
+/**
+ * Re-anchor a witness chain whose only breaks are accidental forks.
+ * `db` must be a writable connection on `options.dbPath`.
+ */
+export async function repairWitnessChainForks(db, options) {
+    const dryRun = options.dryRun === true;
+    const chain = new WitnessChain(db, options.keyManager ?? undefined);
+    await chain.initialize();
+    const rowsBefore = countRows(db);
+    const before = chain.verify(VERIFY_OPTIONS);
+    const base = { dryRun, before: summarize(before), rowsBefore, rowsAfter: rowsBefore };
+    if (before.tampered) {
+        return { ...base, action: 'refused', message: refusal(before), forksAcknowledged: [] };
+    }
+    const pending = unacknowledged(before);
+    if (pending.length === 0) {
+        const message = before.forks.length > 0
+            ? `Nothing to repair: all ${before.forks.length} fork(s) are already re-anchored.`
+            : 'Nothing to repair: the audit chain has no forks.';
+        return { ...base, action: 'none', message, forksAcknowledged: [] };
+    }
+    if (dryRun) {
+        return {
+            ...base, action: 'would-reanchor', forksAcknowledged: pending.map((f) => f.id),
+            message: `Dry run: would back up the database and append a CHAIN_REANCHOR entry acknowledging ${pending.length} fork(s). Nothing was written.`,
+        };
+    }
+    // Re-verify, back up and append under ONE write lock: nothing can land
+    // between the check, the snapshot and the write.
+    let backupPath;
+    const reanchor = db.transaction(() => {
+        const txBefore = countRows(db);
+        const check = chain.verify(VERIFY_OPTIONS);
+        if (check.tampered)
+            return { kind: 'refused', check };
+        const forks = unacknowledged(check);
+        if (forks.length === 0)
+            return { kind: 'noop' };
+        backupPath = backupDatabase(options.dbPath, txBefore);
+        const tip = db.prepare('SELECT * FROM witness_chain ORDER BY id DESC LIMIT 1').get();
+        const entry = chain.append('CHAIN_REANCHOR', {
+            reason: 'fork-repair',
+            issue: 'https://github.com/proffesor-for-testing/agentic-qe/issues/753',
+            note: 'Acknowledges accidental forks from pre-3.14.5 concurrent appends; no rows were changed.',
+            forkCount: forks.length,
+            forks,
+            pins: deadEndPins(db, tip.id),
+            verifiedTipId: tip.id,
+            verifiedTipHash: ownHash(tip),
+            entriesChecked: check.entriesChecked,
+            rows: txBefore,
+            backup: basename(backupPath),
+        }, options.actor ?? 'aqe-audit-repair');
+        const txAfter = countRows(db);
+        if (txAfter.live !== txBefore.live + 1 || txAfter.archive !== txBefore.archive) {
+            throw new Error(`row-count check failed: before ${JSON.stringify(txBefore)}, after ${JSON.stringify(txAfter)}`);
+        }
+        return { kind: 'reanchored', entry, forks, txAfter };
+    }).immediate();
+    if (reanchor.kind === 'refused') {
+        return { ...base, action: 'refused', message: refusal(reanchor.check), forksAcknowledged: [] };
+    }
+    if (reanchor.kind === 'noop') {
+        return { ...base, action: 'none', message: 'Nothing to repair (another process re-anchored first).', forksAcknowledged: [] };
+    }
+    const after = chain.verify(VERIFY_OPTIONS);
+    const ok = after.valid && !after.tampered;
+    return {
+        ...base,
+        action: 'reanchored',
+        after: summarize(after),
+        rowsAfter: reanchor.txAfter,
+        forksAcknowledged: reanchor.forks.map((f) => f.id),
+        reanchorId: reanchor.entry.id,
+        backupPath,
+        message: ok
+            ? `Re-anchored ${reanchor.forks.length} fork(s) with CHAIN_REANCHOR id=${reanchor.entry.id}; chain now ${after.status}. Backup: ${backupPath}`
+            : `Appended CHAIN_REANCHOR id=${reanchor.entry.id}, but the chain still verifies as ${after.status}. Backup: ${backupPath}`,
+    };
+}
+//# sourceMappingURL=witness-chain-repair.js.map

package/dist/audit/witness-chain-verifier.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Witness Chain verification with break classification (ADR-070, issue #753).
+ *
+ * Before v3.14.5, two AQE processes appending at once could both read the
+ * same tail and write a row whose `prev_hash` points at an older row: an
+ * accidental FORK. `verify()` used to stop at the first such break, so the
+ * rows after it were never checked and a forked store looked exactly like a
+ * tampered one.
+ *
+ * Every row is now classified:
+ *
+ * - linked: `prev_hash` is the hash of its predecessor (array-adjacent row,
+ *   or row `id - 1` in either table, which covers the archival boundary), and
+ *   no id between the two is missing from live ∪ archive.
+ * - fork: the row's own `action_hash` recomputes, its `prev_hash` is the exact
+ *   hash of an EARLIER row that still exists (live or archive), every id
+ *   between that parent and the row still exists (no deleted history), and,
+ *   when the row is signed with a key this verifier holds, the Ed25519
+ *   signature verifies. The walk records the fork and CONTINUES, checking the
+ *   next row against the fork row exactly as before.
+ * - tamper: anything else. The walk stops there.
+ *
+ * A fork alone does not make the chain valid: it is only accepted once a later,
+ * normally linked `CHAIN_REANCHOR` entry (written by `aqe audit repair`) lists
+ * that exact row (id + prev_hash + action_hash + parent id). Forks that appear
+ * after a re-anchor are unacknowledged again. The re-anchor also pins the hash
+ * of every dead-end row (a losing race sibling that no later row links to), so
+ * editing or deleting one after the repair is reported as tampering.
+ *
+ * Limits (documented in ADR-070): for UNSIGNED rows the fork class is
+ * structural, not cryptographic. A row whose prev_hash is the genesis sentinel
+ * mid-chain (the legacy #759 brain-import splice) is reported as tamper: the
+ * sentinel proves nothing about this chain and is exactly what a forged or
+ * history-deleting edit produces.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+import type { WitnessEntry } from './witness-chain.js';
+import type { WitnessKeyManager } from './witness-key-manager.js';
+export declare const CHAIN_REANCHOR_ACTION = "CHAIN_REANCHOR";
+export interface VerifyOptions {
+    /** Also verify Ed25519 signatures of every row. Requires keyManager on the chain. */
+    checkSignatures?: boolean;
+    /**
+     * Also walk `witness_chain_archive` and validate it as part of the same
+     * hash chain (archived rows are hash-linked to each other and to the live
+     * table exactly like un-archived rows). Off by default: the live-only walk
+     * is enough to catch tampering with current data and already correctly
+     * bridges the archival boundary; this option adds full historical coverage
+     * for a deep CI gate at the cost of reading the (potentially large) archive.
+     */
+    includeArchive?: boolean;
+}
+/**
+ * - `valid`: no breaks.
+ * - `valid-with-forks`: forks exist and every one is acknowledged by a CHAIN_REANCHOR.
+ * - `forked`: unacknowledged forks, no tampering. `valid` is false.
+ * - `tampered`: a tamper-class break or a signature failure. `valid` is false.
+ */
+export type ChainStatus = 'valid' | 'valid-with-forks' | 'forked' | 'tampered';
+export type TamperReason = 'action-hash-mismatch' | 'genesis-link-mismatch' | 'unlinked-genesis-prev-hash' | 'unlinked-prev-hash' | 'id-gap' | 'live-chain-missing' | 'fork-signature-invalid' | 'reanchor-signature-invalid' | 'reanchored-row-changed' | 'signature-invalid';
+export interface WitnessForkInfo {
+    id: number;
+    parentId: number;
+    prevHash: string;
+    actionHash: string;
+    table: 'live' | 'archive';
+    acknowledged: boolean;
+}
+export interface VerifyResult {
+    /** True only for status `valid` or `valid-with-forks`. */
+    valid: boolean;
+    /**
+     * First break that makes the chain invalid, in walk order: the first
+     * unacknowledged fork, else the tamper row. Same id pre-#753 verify reported.
+     */
+    brokenAt?: number;
+    /** Rows walked (all rows unless a tamper stopped the walk). */
+    entriesChecked: number;
+    signatureFailures?: number;
+    status: ChainStatus;
+    /** True for any tamper-class break or signature failure. Never true for forks alone. */
+    tampered: boolean;
+    tamperedAt?: number;
+    tamperReason?: TamperReason;
+    /** Ids of every fork-class row found (acknowledged or not). */
+    forks: number[];
+    /** Subset of `forks` acknowledged by a verified CHAIN_REANCHOR entry. */
+    acknowledgedForks: number[];
+    forkDetails: WitnessForkInfo[];
+}
+/** One fork acknowledgement inside a CHAIN_REANCHOR entry's action_data. */
+export interface ReanchorForkRecord {
+    id: number;
+    parentId: number;
+    prevHash: string;
+    actionHash: string;
+}
+/** A row hash frozen by a CHAIN_REANCHOR entry (dead-end rows nothing else links to). */
+export interface ReanchorPin {
+    id: number;
+    hash: string;
+}
+/** Row hash under the row's own algorithm (how pins are recorded). */
+export declare function ownHash(row: WitnessEntry): string;
+/** Stateful single-use walker; see file header for the classification rules. */
+export declare class WitnessChainVerifier {
+    private readonly db;
+    private readonly keyManager;
+    private readonly options;
+    private archiveRows;
+    private readonly parentIndex;
+    private readonly acks;
+    private readonly pins;
+    private readonly forks;
+    private tamper;
+    private signatureFailures;
+    private firstSignatureFailure;
+    private entriesChecked;
+    private archiveExists;
+    constructor(db: DatabaseType, keyManager: WitnessKeyManager | null, options?: VerifyOptions);
+    run(): VerifyResult;
+    private walk;
+    private classify;
+    private findEntryById;
+    private getArchive;
+    /** Stores written before archiving existed (or opened read-only) may lack the archive table. */
+    private hasArchive;
+    /** hash → id over every row (live + archive), built lazily per hash algo on the first fork candidate. */
+    private lookupParent;
+    /**
+     * True when every id strictly between `from` and `to` exists in live ∪
+     * archive. AUTOINCREMENT ids are never reused and a rolled-back insert does
+     * not consume one, so a missing id means a row was deleted.
+     */
+    private idsContiguous;
+    /**
+     * Signature status of one row against the keys this verifier holds. A row
+     * signed by a key it does not hold is `unverifiable` (e.g. a key from before
+     * persistent key storage) — classified on structure alone, like unsigned rows.
+     */
+    private checkSignature;
+    /** Legacy `checkSignatures` option: every signed row must verify (unknown key = failure). */
+    private checkAllSignatures;
+    private registerReanchor;
+    /** Rows frozen by a verified re-anchor must still exist with the same hash. */
+    private checkPins;
+    private result;
+}
+export declare function verifyWitnessChain(db: DatabaseType, keyManager: WitnessKeyManager | null, options?: VerifyOptions): VerifyResult;
+/** True when `name` is a table in the connected database. */
+export declare function tableExists(db: DatabaseType, name: string): boolean;
+//# sourceMappingURL=witness-chain-verifier.d.ts.map