agentic-qe 3.9.15 → 3.9.17

package/dist/integrations/ruvector/brain-diff.js

@@ -0,0 +1,281 @@
+/**
+ * Brain Export Diff
+ *
+ * Compares two brain exports (JSONL directory or RVF file) and returns a
+ * structured diff.
+ *
+ * Two levels of comparison:
+ *   - Manifest-level (always available): version, checksum, per-table record
+ *     counts, exported_at, domain list delta.
+ *   - Record-level (JSONL exports only): for each table with a PK, the set of
+ *     added / removed / changed record IDs. For append-only tables only counts
+ *     are reported.
+ *
+ * For RVF exports, record-level diff is not supported by this module (the
+ * kernel is opaque without @ruvector/rvf-node). Export as JSONL for full diff.
+ */
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { safeJsonParse } from '../../shared/safe-json.js';
+import { brainInfoFromRvf } from './brain-rvf-exporter.js';
+import { readJsonl, sha256, TABLE_CONFIGS, PK_COLUMNS, } from './brain-shared.js';
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Compute the diff between two brain exports.
+ *
+ * Both paths may be JSONL directories or `.rvf` files. Record-level diff is
+ * only available when both sides are JSONL.
+ */
+export function diffBrains(pathA, pathB, options = {}) {
+    const resolvedA = resolve(pathA);
+    const resolvedB = resolve(pathB);
+    const formatA = detectFormat(resolvedA);
+    const formatB = detectFormat(resolvedB);
+    const manifestA = readManifestSummary(resolvedA, formatA);
+    const manifestB = readManifestSummary(resolvedB, formatB);
+    const recordLevel = formatA === 'jsonl' && formatB === 'jsonl';
+    const tableDiffs = computeTableDiffs({
+        pathA: resolvedA,
+        pathB: resolvedB,
+        manifestA,
+        manifestB,
+        recordLevel,
+        tableFilter: options.tableFilter,
+        maxIdsPerBucket: options.maxIdsPerBucket ?? 500,
+    });
+    const domainsA = new Set(manifestA.domains);
+    const domainsB = new Set(manifestB.domains);
+    const domainsOnlyInA = manifestA.domains.filter((d) => !domainsB.has(d));
+    const domainsOnlyInB = manifestB.domains.filter((d) => !domainsA.has(d));
+    const checksumMatch = manifestA.checksum === manifestB.checksum;
+    const versionMatch = manifestA.version === manifestB.version;
+    const identical = checksumMatch &&
+        versionMatch &&
+        tableDiffs.every((t) => t.delta === 0 &&
+            (t.added?.length ?? 0) === 0 &&
+            (t.removed?.length ?? 0) === 0 &&
+            (t.changed?.length ?? 0) === 0);
+    return {
+        pathA: resolvedA,
+        pathB: resolvedB,
+        formatA,
+        formatB,
+        manifestA,
+        manifestB,
+        checksumMatch,
+        versionMatch,
+        identical,
+        recordLevel,
+        tableDiffs,
+        domainsOnlyInA,
+        domainsOnlyInB,
+    };
+}
+// ============================================================================
+// Format detection + manifest reading
+// ============================================================================
+function detectFormat(path) {
+    if (!existsSync(path)) {
+        throw new Error(`Path not found: ${path}`);
+    }
+    if (path.endsWith('.rvf'))
+        return 'rvf';
+    const s = statSync(path);
+    if (s.isFile()) {
+        // Any single file that isn't .rvf is treated as an error — JSONL exports
+        // are directories.
+        throw new Error(`Unsupported brain export: ${path} (expected a .rvf file or a JSONL directory)`);
+    }
+    // Directory: assume JSONL
+    return 'jsonl';
+}
+function readManifestSummary(path, format) {
+    if (format === 'rvf') {
+        return readRvfManifestSummary(path);
+    }
+    return readJsonlManifestSummary(path);
+}
+function readJsonlManifestSummary(dir) {
+    const manifestPath = join(dir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Manifest not found at ${manifestPath}`);
+    }
+    const raw = safeJsonParse(readFileSync(manifestPath, 'utf-8'));
+    return toManifestSummary(raw, 'jsonl');
+}
+function readRvfManifestSummary(rvfPath) {
+    // Delegate to the RVF exporter's info path so we honour its format handling.
+    const raw = brainInfoFromRvf(rvfPath);
+    return toManifestSummary(raw, 'rvf');
+}
+function toManifestSummary(raw, format) {
+    return {
+        format,
+        version: raw.version ?? 'unknown',
+        exportedAt: raw.exportedAt ?? 'unknown',
+        sourceDb: raw.sourceDb ?? 'unknown',
+        checksum: raw.checksum ?? '',
+        totalRecords: raw.stats?.totalRecords ?? 0,
+        domains: raw.domains ?? [],
+        tableRecordCounts: raw.tableRecordCounts ?? {},
+    };
+}
+function computeTableDiffs(input) {
+    const configs = input.tableFilter
+        ? TABLE_CONFIGS.filter((c) => c.tableName === input.tableFilter)
+        : TABLE_CONFIGS;
+    if (input.tableFilter && configs.length === 0) {
+        throw new Error(`Unknown table: ${input.tableFilter}`);
+    }
+    const diffs = [];
+    for (const config of configs) {
+        const countA = input.manifestA.tableRecordCounts[config.tableName] ?? 0;
+        const countB = input.manifestB.tableRecordCounts[config.tableName] ?? 0;
+        const delta = countB - countA;
+        let added;
+        let removed;
+        let changed;
+        if (input.recordLevel && hasIdentity(config)) {
+            const recordDiff = recordLevelDiff(join(input.pathA, config.fileName), join(input.pathB, config.fileName), config, input.maxIdsPerBucket);
+            added = recordDiff.added;
+            removed = recordDiff.removed;
+            changed = recordDiff.changed;
+        }
+        diffs.push({
+            tableName: config.tableName,
+            countA,
+            countB,
+            delta,
+            ...(added !== undefined ? { added } : {}),
+            ...(removed !== undefined ? { removed } : {}),
+            ...(changed !== undefined ? { changed } : {}),
+        });
+    }
+    return diffs;
+}
+function hasIdentity(_config) {
+    // PK tables always have identity; append-only tables can be deduped via
+    // their dedup columns, which is good enough to compute added/removed.
+    return true;
+}
+function pkFor(config) {
+    if (config.dedupColumns && config.dedupColumns.length > 0) {
+        // Composite identity — joined with a separator unlikely to occur in values.
+        return config.dedupColumns.join('
');
+    }
+    return PK_COLUMNS[config.tableName] ?? 'id';
+}
+function recordLevelDiff(fileA, fileB, config, maxIdsPerBucket) {
+    const mapA = buildIdentityMap(fileA, config);
+    const mapB = buildIdentityMap(fileB, config);
+    const added = [];
+    const removed = [];
+    const changed = [];
+    // In A but not in B → removed.
+    for (const [id, hashA] of mapA) {
+        const hashB = mapB.get(id);
+        if (hashB === undefined) {
+            if (removed.length < maxIdsPerBucket)
+                removed.push(id);
+        }
+        else if (hashB !== hashA) {
+            // Append-only tables use dedup columns as identity, so if the identity
+            // matches the record IS the same — guard via dedup flag.
+            if (config.dedupColumns && config.dedupColumns.length > 0)
+                continue;
+            if (changed.length < maxIdsPerBucket)
+                changed.push(id);
+        }
+    }
+    // In B but not in A → added.
+    for (const id of mapB.keys()) {
+        if (!mapA.has(id)) {
+            if (added.length < maxIdsPerBucket)
+                added.push(id);
+        }
+    }
+    added.sort();
+    removed.sort();
+    changed.sort();
+    return { added, removed, changed };
+}
+/**
+ * Read a JSONL file and build a Map<identity, contentHash>.
+ *
+ * For PK tables the identity is the PK column value. For append-only tables
+ * the identity is a concatenation of the dedup columns (collisions are
+ * treated as "same record").
+ */
+function buildIdentityMap(filePath, config) {
+    const map = new Map();
+    if (!existsSync(filePath))
+        return map;
+    const rows = readJsonl(filePath, safeJsonParse);
+    for (const row of rows) {
+        const id = identityOf(row, config);
+        if (id === undefined)
+            continue;
+        // Stable content hash: JSON-stringify with sorted keys.
+        const content = stableStringify(row);
+        map.set(id, sha256Hex(content));
+    }
+    return map;
+}
+function identityOf(row, config) {
+    if (config.dedupColumns && config.dedupColumns.length > 0) {
+        const parts = [];
+        for (const col of config.dedupColumns) {
+            const v = row[col];
+            if (v === undefined || v === null)
+                return undefined;
+            parts.push(String(v));
+        }
+        return parts.join('
');
+    }
+    const pk = PK_COLUMNS[config.tableName] ?? 'id';
+    const v = row[pk];
+    if (v === undefined || v === null)
+        return undefined;
+    return String(v);
+}
+function stableStringify(obj) {
+    const keys = Object.keys(obj).sort();
+    const ordered = {};
+    for (const k of keys)
+        ordered[k] = obj[k];
+    return JSON.stringify(ordered);
+}
+function sha256Hex(s) {
+    // sha256() from brain-shared operates on utf-8 strings; both paths yield the
+    // same hash for the same input. Kept as a thin wrapper for readability.
+    return sha256(s);
+}
+export function summarizeDiff(result) {
+    let tablesChanged = 0;
+    let totalAdded = 0;
+    let totalRemoved = 0;
+    let totalChanged = 0;
+    for (const t of result.tableDiffs) {
+        const hasChange = t.delta !== 0 ||
+            (t.added && t.added.length > 0) ||
+            (t.removed && t.removed.length > 0) ||
+            (t.changed && t.changed.length > 0);
+        if (hasChange)
+            tablesChanged++;
+        totalAdded += t.added?.length ?? 0;
+        totalRemoved += t.removed?.length ?? 0;
+        totalChanged += t.changed?.length ?? 0;
+    }
+    return {
+        tablesChanged,
+        totalAdded,
+        totalRemoved,
+        totalChanged,
+        recordCountDelta: result.manifestB.totalRecords - result.manifestA.totalRecords,
+    };
+}
+// Export internal helpers for test access without widening the public API.
+export const __test__ = { stableStringify, identityOf, buildIdentityMap, pkFor };
+//# sourceMappingURL=brain-diff.js.map

package/dist/integrations/ruvector/brain-search.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Brain Export Search
+ *
+ * Offline, read-only filtered search over a JSONL brain export directory.
+ * Useful for exploring what a snapshot contains without importing it.
+ *
+ * Defaults to searching qe_patterns but can target any of the 25 exported
+ * tables via the `table` option. Supports filters by domain, pattern_type,
+ * date range, and a substring query that matches `name` + `description`.
+ *
+ * RVF exports are not supported directly by this module — callers should use
+ * `aqe brain export --format jsonl` for searchable snapshots.
+ */
+export interface BrainSearchOptions {
+    /** Table to search. Defaults to 'qe_patterns'. */
+    readonly table?: string;
+    /** Restrict to these domains (matched against the table's domain column). */
+    readonly domains?: readonly string[];
+    /** Restrict to rows with this exact pattern_type (qe_patterns only). */
+    readonly patternType?: string;
+    /** ISO timestamp — only rows at or after this are included. */
+    readonly since?: string;
+    /** ISO timestamp — only rows at or before this are included. */
+    readonly until?: string;
+    /** Case-insensitive substring matched against name + description. */
+    readonly query?: string;
+    /** Max rows to return. Defaults to 20. */
+    readonly limit?: number;
+}
+export interface BrainSearchHit {
+    /** Primary-key identity string (best effort per table). */
+    readonly id: string;
+    /** Minimal surface shown in default CLI output. */
+    readonly display: {
+        readonly name?: string;
+        readonly description?: string;
+        readonly domain?: string;
+        readonly patternType?: string;
+        readonly confidence?: number;
+        readonly updatedAt?: string;
+    };
+    /** Full raw row for callers that want more (used by --json). */
+    readonly row: Record<string, unknown>;
+}
+export interface BrainSearchResult {
+    readonly table: string;
+    readonly inputPath: string;
+    readonly totalScanned: number;
+    readonly totalMatched: number;
+    readonly limit: number;
+    readonly hits: readonly BrainSearchHit[];
+    readonly truncated: boolean;
+}
+/**
+ * Search a brain export directory for rows matching the given filters.
+ *
+ * Throws if the path isn't a JSONL export directory, if the requested table
+ * isn't known, or if the JSONL file for that table is missing.
+ */
+export declare function searchBrain(inputPath: string, options?: BrainSearchOptions): BrainSearchResult;
+interface FilterContext {
+    readonly domainColumn?: string;
+    readonly domains?: Set<string>;
+    readonly patternType?: string;
+    readonly since?: string;
+    readonly until?: string;
+    readonly queryLower?: string;
+}
+declare function rowMatches(row: Record<string, unknown>, ctx: FilterContext): boolean;
+declare function pickTimestamp(row: Record<string, unknown>): string | undefined;
+declare function toHit(row: Record<string, unknown>, tableName: string, domainColumn: string | undefined): BrainSearchHit;
+export declare const __test__: {
+    pickTimestamp: typeof pickTimestamp;
+    rowMatches: typeof rowMatches;
+    toHit: typeof toHit;
+};
+export {};
+//# sourceMappingURL=brain-search.d.ts.map

package/dist/integrations/ruvector/brain-search.js

@@ -0,0 +1,154 @@
+/**
+ * Brain Export Search
+ *
+ * Offline, read-only filtered search over a JSONL brain export directory.
+ * Useful for exploring what a snapshot contains without importing it.
+ *
+ * Defaults to searching qe_patterns but can target any of the 25 exported
+ * tables via the `table` option. Supports filters by domain, pattern_type,
+ * date range, and a substring query that matches `name` + `description`.
+ *
+ * RVF exports are not supported directly by this module — callers should use
+ * `aqe brain export --format jsonl` for searchable snapshots.
+ */
+import { existsSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { safeJsonParse } from '../../shared/safe-json.js';
+import { readJsonl, TABLE_CONFIGS } from './brain-shared.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_LIMIT = 20;
+const DEFAULT_TABLE = 'qe_patterns';
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Search a brain export directory for rows matching the given filters.
+ *
+ * Throws if the path isn't a JSONL export directory, if the requested table
+ * isn't known, or if the JSONL file for that table is missing.
+ */
+export function searchBrain(inputPath, options = {}) {
+    const resolved = resolve(inputPath);
+    assertJsonlExport(resolved);
+    const tableName = options.table ?? DEFAULT_TABLE;
+    const config = TABLE_CONFIGS.find((c) => c.tableName === tableName);
+    if (!config) {
+        throw new Error(`Unknown table: ${tableName}`);
+    }
+    const filePath = join(resolved, config.fileName);
+    if (!existsSync(filePath)) {
+        throw new Error(`Table file not found: ${config.fileName} ` +
+            `(expected in ${resolved}). Was this export generated with --format jsonl?`);
+    }
+    const rows = readJsonl(filePath, safeJsonParse);
+    const domainColumn = config.domainColumn;
+    const limit = Math.max(1, options.limit ?? DEFAULT_LIMIT);
+    const queryLower = options.query ? options.query.toLowerCase() : undefined;
+    const domains = options.domains && options.domains.length > 0 ? new Set(options.domains) : undefined;
+    const since = options.since;
+    const until = options.until;
+    const patternType = options.patternType;
+    let matched = 0;
+    const hits = [];
+    for (const row of rows) {
+        if (!rowMatches(row, { domainColumn, domains, patternType, since, until, queryLower })) {
+            continue;
+        }
+        matched++;
+        if (hits.length < limit) {
+            hits.push(toHit(row, config.tableName, domainColumn));
+        }
+    }
+    return {
+        table: tableName,
+        inputPath: resolved,
+        totalScanned: rows.length,
+        totalMatched: matched,
+        limit,
+        hits,
+        truncated: matched > limit,
+    };
+}
+function rowMatches(row, ctx) {
+    // Domain filter — only applied if table has a domain column.
+    if (ctx.domains) {
+        if (!ctx.domainColumn)
+            return false; // caller asked for a domain filter on a table that has none
+        const v = row[ctx.domainColumn];
+        if (typeof v !== 'string' || !ctx.domains.has(v))
+            return false;
+    }
+    // Pattern type filter — only meaningful for qe_patterns.
+    if (ctx.patternType !== undefined) {
+        const v = row['pattern_type'];
+        if (v !== ctx.patternType)
+            return false;
+    }
+    // Date range — matched against updated_at | created_at | timestamp (in that order).
+    if (ctx.since !== undefined || ctx.until !== undefined) {
+        const ts = pickTimestamp(row);
+        if (ts === undefined)
+            return false;
+        if (ctx.since !== undefined && ts < ctx.since)
+            return false;
+        if (ctx.until !== undefined && ts > ctx.until)
+            return false;
+    }
+    // Substring query — matched against name + description (case-insensitive).
+    if (ctx.queryLower !== undefined) {
+        const name = typeof row['name'] === 'string' ? row['name'].toLowerCase() : '';
+        const desc = typeof row['description'] === 'string' ? row['description'].toLowerCase() : '';
+        if (!name.includes(ctx.queryLower) && !desc.includes(ctx.queryLower))
+            return false;
+    }
+    return true;
+}
+function pickTimestamp(row) {
+    for (const col of ['updated_at', 'created_at', 'timestamp']) {
+        const v = row[col];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+// ============================================================================
+// Result formatting
+// ============================================================================
+function toHit(row, tableName, domainColumn) {
+    const id = (typeof row['id'] === 'string' || typeof row['id'] === 'number'
+        ? String(row['id'])
+        : undefined) ?? `${tableName}:?`;
+    const display = {
+        name: typeof row['name'] === 'string' ? row['name'] : undefined,
+        description: typeof row['description'] === 'string' ? row['description'] : undefined,
+        domain: domainColumn && typeof row[domainColumn] === 'string' ? row[domainColumn] : undefined,
+        patternType: typeof row['pattern_type'] === 'string' ? row['pattern_type'] : undefined,
+        confidence: typeof row['confidence'] === 'number' ? row['confidence'] : undefined,
+        updatedAt: pickTimestamp(row),
+    };
+    return { id, display, row };
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function assertJsonlExport(path) {
+    if (!existsSync(path)) {
+        throw new Error(`Path not found: ${path}`);
+    }
+    const s = statSync(path);
+    if (s.isFile()) {
+        if (path.endsWith('.rvf')) {
+            throw new Error('Brain search does not support RVF exports. Re-export with --format jsonl, or use `aqe brain info` for RVF summaries.');
+        }
+        throw new Error(`Unsupported brain export: ${path} (expected a JSONL directory)`);
+    }
+    const manifest = join(path, 'manifest.json');
+    if (!existsSync(manifest)) {
+        throw new Error(`Manifest not found at ${manifest}. Is this a brain export directory?`);
+    }
+}
+// Re-export for test access / future helpers without widening the public API.
+export const __test__ = { pickTimestamp, rowMatches, toHit };
+//# sourceMappingURL=brain-search.js.map