@rigour-labs/core 6.5.2 → 6.5.3

package/dist/gates/unindexed-reads/sql.js

@@ -0,0 +1,131 @@
+/**
+ * Just enough SQL lexing to replay Postgres migrations: statements, top-level
+ * lists, and identifiers. Anything this cannot read is reported as unknown so
+ * the gate stays silent rather than guess.
+ */
+/** Statements in order, comments removed; a `$tag$ … $tag$` body stays inside its statement. */
+export function splitStatements(sql) {
+    const statements = [];
+    let current = '';
+    let i = 0;
+    while (i < sql.length) {
+        const rest = sql.slice(i);
+        const dollar = /^\$[A-Za-z_]*\$/.exec(rest);
+        if (rest.startsWith('--')) {
+            const end = sql.indexOf('\n', i);
+            i = end === -1 ? sql.length : end;
+        }
+        else if (rest.startsWith('/*')) {
+            const end = sql.indexOf('*/', i + 2);
+            i = end === -1 ? sql.length : end + 2;
+            current += ' ';
+        }
+        else if (dollar) {
+            const end = sql.indexOf(dollar[0], i + dollar[0].length);
+            const stop = end === -1 ? sql.length : end + dollar[0].length;
+            current += sql.slice(i, stop);
+            i = stop;
+        }
+        else if (sql[i] === "'" || sql[i] === '"') {
+            const stop = quotedEnd(sql, i);
+            current += sql.slice(i, stop);
+            i = stop;
+        }
+        else if (sql[i] === ';') {
+            if (current.trim())
+                statements.push(current.trim());
+            current = '';
+            i++;
+        }
+        else {
+            current += sql[i++];
+        }
+    }
+    if (current.trim())
+        statements.push(current.trim());
+    return statements.map(s => s.replace(/\s+/g, ' '));
+}
+/** Index just past a quoted string or identifier starting at `start` (a doubled quote is an escape). */
+function quotedEnd(text, start) {
+    const quote = text[start];
+    let i = start + 1;
+    while (i < text.length) {
+        if (text[i] === quote && text[i + 1] === quote)
+            i += 2;
+        else if (text[i] === quote)
+            return i + 1;
+        else
+            i++;
+    }
+    return text.length;
+}
+/** Split on `separator` outside parentheses and quotes. */
+export function splitTopLevel(text, separator) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === "'" || ch === '"') {
+            i = quotedEnd(text, i);
+            continue;
+        }
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        else if (depth === 0) {
+            const match = separator.exec(text.slice(i));
+            if (match && match.index === 0) {
+                parts.push(text.slice(start, i).trim());
+                i += match[0].length;
+                start = i;
+                continue;
+            }
+        }
+        i++;
+    }
+    parts.push(text.slice(start).trim());
+    return parts.filter(Boolean);
+}
+/** The text inside the parentheses that open at `open`, or undefined when they never close. */
+export function parenthesized(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === "'" || ch === '"') {
+            i = quotedEnd(text, i) - 1;
+            continue;
+        }
+        if (ch === '(')
+            depth++;
+        else if (ch === ')' && --depth === 0)
+            return { inner: text.slice(open + 1, i), end: i + 1 };
+    }
+    return undefined;
+}
+/** Strip parentheses that enclose the whole expression, as often as they do: `((a))` → `a`, but `(a) or (b)` stays. */
+export function unwrap(text) {
+    let current = text.trim();
+    while (current.startsWith('(')) {
+        const group = parenthesized(current, 0);
+        if (!group || group.end !== current.length)
+            break;
+        current = group.inner.trim();
+    }
+    return current;
+}
+/** A relation name as Rigour keys it: unquoted names fold to lower case, `public.` is implied. */
+export function relationName(raw) {
+    const parts = raw.split('.').map(identifier);
+    if (parts.length === 2 && parts[0] === 'public')
+        return parts[1];
+    return parts.join('.');
+}
+export function identifier(raw) {
+    const trimmed = raw.trim();
+    return trimmed.startsWith('"') ? trimmed.slice(1, -1).replace(/""/g, '"') : trimmed.toLowerCase();
+}
+/** One identifier, optionally schema-qualified and quoted: the `name` in `CREATE TABLE name (`. */
+export const NAME = String.raw `(?:"(?:[^"]|"")+"|[A-Za-z_][\w$]*)(?:\.(?:"(?:[^"]|"")+"|[A-Za-z_][\w$]*))?`;

package/dist/gates/unindexed-reads/unindexed-reads.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gates/unindexed-reads/unindexed-reads.test.js

@@ -0,0 +1,90 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { UnindexedReadsGate } from './index.js';
+let repo;
+const write = (rel, body) => {
+    fs.mkdirSync(path.dirname(path.join(repo, rel)), { recursive: true });
+    fs.writeFileSync(path.join(repo, rel), body);
+};
+const run = (config = { enabled: true }) => new UnindexedReadsGate(config).run({ cwd: repo, patterns: ['src/**/*.ts'] });
+const TABLE = `create table orders (
+  id uuid primary key,
+  customer_id uuid,
+  status text not null,
+  placed_at timestamptz,
+  campaign_id uuid
+);
+create index orders_customer_idx on orders (customer_id, status, placed_at desc);
+create index orders_campaign_window_idx on orders (placed_at, id) where status = 'open' and campaign_id is not null;
+`;
+const WINDOW_READ = `
+export async function openOrders(db: Db, since: string, until: string) {
+  return db
+    .from('orders')
+    .select('id, placed_at')
+    .eq('status', 'open')
+    .not('customer_id', 'is', null)
+    .gt('placed_at', since)
+    .lte('placed_at', until)
+    .order('placed_at')
+    .order('id');
+}
+`;
+beforeEach(() => { repo = fs.mkdtempSync(path.join(os.tmpdir(), 'unindexed-')); });
+afterEach(() => fs.rmSync(repo, { recursive: true, force: true }));
+describe('UnindexedReadsGate', () => {
+    it('flags a window read whose only candidate index is partial on a filter the read does not have', async () => {
+        write('supabase/migrations/20260101000000_orders.sql', TABLE);
+        write('src/orders.ts', WINDOW_READ);
+        const failures = await run();
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ id: 'unindexed-reads', files: ['src/orders.ts'], line: 4 });
+        expect(failures[0].details).toContain('`orders`');
+        expect(failures[0].details).toContain('`placed_at`');
+    });
+    it('is silent once a later migration adds an index that serves the read', async () => {
+        write('supabase/migrations/20260101000000_orders.sql', TABLE);
+        write('supabase/migrations/20260102000000_orders_open.sql', `create index concurrently orders_open_window_idx on public.orders (placed_at, id) where status = 'open' and customer_id is not null;`);
+        write('src/orders.ts', WINDOW_READ);
+        expect(await run()).toEqual([]);
+    });
+    it('is silent for a primary-key lookup, a table outside the migrations, and an uncertain table', async () => {
+        write('db/migrations/001_orders.sql', TABLE + 'create table notes (id int, body text);\nalter table notes rename column body to text;\n');
+        write('src/reads.ts', `
+          db.from('orders').select('*').eq('id', id);
+          db.from('auth_users').select('*').eq('email', email);
+          db.from('notes').select('*').eq('text', q);
+        `);
+        expect(await run()).toEqual([]);
+    });
+    it('is silent unless enabled, and for a read that narrows nothing', async () => {
+        write('supabase/migrations/20260101000000_orders.sql', TABLE);
+        write('src/orders.ts', WINDOW_READ + `\ndb.from('orders').select('*').limit(10);\n`);
+        expect(await run({ enabled: false })).toEqual([]);
+        expect(await new UnindexedReadsGate({ enabled: true }).run({ cwd: repo, patterns: ['src/**/*.ts'] })).toHaveLength(1);
+    });
+    it('needs every migration set that defines the table to lack a serving index', async () => {
+        write('apps/a/supabase/migrations/1_orders.sql', TABLE);
+        write('apps/b/supabase/migrations/1_orders.sql', TABLE + `create index orders_status_idx on orders (status);`);
+        write('src/orders.ts', WINDOW_READ);
+        expect(await run()).toEqual([]);
+    });
+    it('counts a row-level policy as a filter: names its column, and is silent once that column is indexed', async () => {
+        const subs = `create table subs (id text primary key, user_id uuid not null, status text);
+create policy "own subs" on subs for select using (auth.uid() = user_id);`;
+        write('supabase/migrations/1_subs.sql', subs);
+        write('src/subs.ts', `export const active = (db: Db) => db.from('subs').select('*').in('status', ['active']).maybeSingle();\n`);
+        const [finding] = await run();
+        expect(finding.details).toContain('`user_id`');
+        write('supabase/migrations/2_subs_user.sql', 'create index subs_user_idx on subs (user_id);');
+        expect(await run()).toEqual([]);
+    });
+    it('is silent for a table whose policy it cannot read', async () => {
+        write('supabase/migrations/1_docs.sql', `create table docs (id int primary key, org_id int, title text);
+create policy "members" on docs for select using (exists (select 1 from members m where m.org_id = docs.org_id));`);
+        write('src/docs.ts', `db.from('docs').select('*').eq('title', t);\n`);
+        expect(await run()).toEqual([]);
+    });
+});

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, les
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules, type RepoRule } from './review-learning/repo-rules.js';
 export { diffFromGit, GitDiffError, type DiffSource } from './review/git-diff.js';
+export { checkPrecisions, checkId, precisionOf, isMuted, MUTE_MIN_OUTCOMES, MUTE_BELOW, type CheckPrecision, type CheckOutcome } from './review/check-outcomes.js';
 export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys, type AgentEvent, type ReviewEffectiveness } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
@@ -47,7 +48,9 @@ export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, rese
 export type { RigourDB, CompactResult } from './storage/index.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
 export type { ProjectStats } from './storage/index.js';
-export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, queueLocalLessonsForTeam } from './storage/index.js';
+export { recordFixLessons, fixLessonSubject, fixLessonPrefix, FILES_TO_VALIDATE } from './storage/index.js';
+export { recordInteractionEvidence, countInteractionEvidence, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, shareMemoryLesson, queueLocalLessonsForTeam } from './storage/index.js';
+export { rankMemories, rankByMeaning, memoryText, SEMANTIC_FLOOR, RECALL_LIMIT, type MemoryEntry, type MemoryScope, type RankedMemory, type Ranked } from './memory/recall.js';
 export type { ApplicableLessons, InteractionEvidence, LessonRecord, LessonState, LessonVisibility, LocalLessonImportOptions, LocalLessonImportResult } from './storage/index.js';
 export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, explainTeamConnectionError, } from './storage/index.js';
 export type { TeamConfiguration, TeamSemanticConfiguration, TeamModeStatus, TeamDoctorResult, SemanticKnowledgeCandidate, SemanticKnowledgeResult, } from './storage/index.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, les
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules } from './review-learning/repo-rules.js';
 export { diffFromGit, GitDiffError } from './review/git-diff.js';
+export { checkPrecisions, checkId, precisionOf, isMuted, MUTE_MIN_OUTCOMES, MUTE_BELOW } from './review/check-outcomes.js';
 export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount } from './review/agent-fixes.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
@@ -47,7 +48,9 @@ export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
-export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, queueLocalLessonsForTeam } from './storage/index.js';
+export { recordFixLessons, fixLessonSubject, fixLessonPrefix, FILES_TO_VALIDATE } from './storage/index.js';
+export { recordInteractionEvidence, countInteractionEvidence, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, shareMemoryLesson, queueLocalLessonsForTeam } from './storage/index.js';
+export { rankMemories, rankByMeaning, memoryText, SEMANTIC_FLOOR, RECALL_LIMIT } from './memory/recall.js';
 export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, explainTeamConnectionError, } from './storage/index.js';
 // Temporal Drift Engine (v5 — cross-session trend analysis + per-provenance EWMA)
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';

package/dist/inference/brain-placeholder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/inference/brain-placeholder.test.js

@@ -0,0 +1,28 @@
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+const PACKAGES = path.resolve(__dirname, '../../..');
+const scripts = fs.readdirSync(PACKAGES)
+    .filter(name => name.startsWith('brain-') && !name.includes('win'))
+    .map(name => path.join(PACKAGES, name, 'bin', 'rigour-brain'));
+describe('rigour-brain placeholder', () => {
+    it.runIf(process.platform !== 'win32')('prints its message without running the command it names', () => {
+        const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-'));
+        const marker = path.join(bin, 'ran');
+        fs.writeFileSync(path.join(bin, 'rigour'), `#!/bin/sh\necho "$@" > "${marker}"\n`, { mode: 0o755 });
+        try {
+            expect(scripts.length).toBeGreaterThan(0);
+            for (const script of scripts) {
+                const result = spawnSync('sh', [script, '--version'], { env: { PATH: `${bin}:/usr/bin:/bin` }, encoding: 'utf8' });
+                expect(result.status).toBe(1);
+                expect(result.stderr).toContain('rigour deep pull');
+                expect(fs.existsSync(marker)).toBe(false);
+            }
+        }
+        finally {
+            fs.rmSync(bin, { recursive: true, force: true });
+        }
+    });
+});

package/dist/inference/llama-engine-checksum.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/inference/llama-engine-checksum.test.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Readable } from 'stream';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+/** Install into a scratch folder: the real one is ~/.rigour. */
+const home = vi.hoisted(() => {
+    const p = require('path');
+    return p.join(require('os').tmpdir(), `rigour-engine-${process.pid}`);
+});
+vi.mock('../storage/db.js', async (importOriginal) => ({ ...(await importOriginal()), RIGOUR_DIR: home }));
+const { installLlamaEngine, managedEngineDir, releaseAssetFor } = await import('./llama-engine.js');
+afterAll(() => fs.rmSync(home, { recursive: true, force: true }));
+describe('llama.cpp engine install', () => {
+    it('pins a checksum for every published platform', () => {
+        for (const key of ['darwin-arm64', 'darwin-x64', 'linux-x64', 'win32-x64']) {
+            expect(releaseAssetFor(key)?.sha256).toMatch(/^[0-9a-f]{64}$/);
+        }
+        expect(releaseAssetFor('linux-arm64')).toBeUndefined();
+    });
+    it.runIf(releaseAssetFor(`${os.platform()}-${os.arch()}`))('refuses an archive that does not match its pinned checksum, and installs nothing', async () => {
+        const tampered = async () => ({ statusCode: 200, headers: {}, body: Readable.from([Buffer.from('not the real llama.cpp archive')]) });
+        await expect(installLlamaEngine(undefined, tampered)).rejects.toThrow(/does not match its pinned checksum/);
+        expect(fs.existsSync(managedEngineDir())).toBe(false);
+        expect(fs.readdirSync(path.dirname(managedEngineDir())).filter(f => f.endsWith('.zip'))).toEqual([]);
+    });
+});

package/dist/inference/llama-engine.d.ts

@@ -4,7 +4,10 @@ export declare function llamaBinaryName(): string;
 /** Install directory for the pinned release: ~/.rigour/bin/llama-<tag>. */
 export declare function managedEngineDir(): string;
 export declare function managedEnginePath(): string;
-export declare function releaseAssetFor(platformKey: string): string | undefined;
+export declare function releaseAssetFor(platformKey: string): {
+    file: string;
+    sha256: string;
+} | undefined;
 export interface ProbeResult {
     ok: boolean;
     version?: string;

package/dist/inference/llama-engine.js

@@ -16,12 +16,16 @@ export const LLAMA_RELEASE_TAG = 'b5604';
 const LLAMA_RELEASE_BASE = `https://github.com/ggml-org/llama.cpp/releases/download/${LLAMA_RELEASE_TAG}`;
 const PROBE_TIMEOUT_MS = 5_000;
 const EXTRACT_TIMEOUT_MS = 120_000;
-/** Platform → llama.cpp release asset. linux-arm64 has no published build. */
+/**
+ * Platform → llama.cpp release asset and its SHA-256, checked against the digest GitHub publishes
+ * for the release. A download that does not match is refused: the engine runs code on the
+ * user's machine. linux-arm64 has no published build.
+ */
 const LLAMA_RELEASE_ASSETS = {
-    'darwin-arm64': `llama-${LLAMA_RELEASE_TAG}-bin-macos-arm64.zip`,
-    'darwin-x64': `llama-${LLAMA_RELEASE_TAG}-bin-macos-x64.zip`,
-    'linux-x64': `llama-${LLAMA_RELEASE_TAG}-bin-ubuntu-x64.zip`,
-    'win32-x64': `llama-${LLAMA_RELEASE_TAG}-bin-win-cpu-x64.zip`,
+    'darwin-arm64': { file: `llama-${LLAMA_RELEASE_TAG}-bin-macos-arm64.zip`, sha256: '673c5f8c4a7a2226ca6f3db5141d1ed78dcdf178d902c1486b77b3dda41e6a61' },
+    'darwin-x64': { file: `llama-${LLAMA_RELEASE_TAG}-bin-macos-x64.zip`, sha256: 'ab9ba59f3e355aebe6bc2c632b3489d4ab98d727f0ee03b9df6b4a6207452ad2' },
+    'linux-x64': { file: `llama-${LLAMA_RELEASE_TAG}-bin-ubuntu-x64.zip`, sha256: '3981c1e353399fbc35ea23316854b3c302877c00fb6b7fa4063a0623ad9e0309' },
+    'win32-x64': { file: `llama-${LLAMA_RELEASE_TAG}-bin-win-cpu-x64.zip`, sha256: 'df32d58de0b57c3c9de2e68e44b947efbac1b8a3e417536b6703cbd8da11eddd' },
 };
 export function llamaBinaryName() {
     return os.platform() === 'win32' ? 'llama-cli.exe' : 'llama-cli';
@@ -84,13 +88,16 @@ export async function installLlamaEngine(onProgress, get) {
     }
     const installDir = managedEngineDir();
     const workDir = `${installDir}.partial`;
-    const zipPath = path.join(path.dirname(installDir), asset);
+    const zipPath = path.join(path.dirname(installDir), asset.file);
     await fs.ensureDir(path.dirname(installDir));
     await fs.remove(workDir);
     onProgress?.(`⬇ Downloading inference engine (llama.cpp ${LLAMA_RELEASE_TAG})...`);
     try {
-        await downloadToFile(`${LLAMA_RELEASE_BASE}/${asset}`, zipPath, { get });
-        onProgress?.('  Extracting...');
+        const { sha256 } = await downloadToFile(`${LLAMA_RELEASE_BASE}/${asset.file}`, zipPath, { get });
+        if (sha256 !== asset.sha256) {
+            throw new Error(`llama.cpp ${asset.file} does not match its pinned checksum (got ${sha256.slice(0, 12)}…, expected ${asset.sha256.slice(0, 12)}…); not installing it.`);
+        }
+        onProgress?.('  Verified checksum. Extracting...');
         await extractZip(zipPath, workDir);
         await installBinFolder(workDir, installDir);
     }

package/dist/memory/recall.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Recall by meaning: the few memories that match what an agent is about to do,
+ * instead of every memory at once.
+ *
+ * Ranking uses the same local embedding model as the pattern index and team
+ * knowledge (all-MiniLM-L6-v2, loaded lazily so its native dependency never
+ * loads for anything else). When the model is unavailable it falls back to
+ * keyword overlap and says so in each result's `match`.
+ */
+export type MemoryScope = 'repo' | 'user';
+export interface MemoryEntry {
+    scope: MemoryScope;
+    key: string;
+    value: string;
+    timestamp?: string;
+}
+export type RankedMemory = Ranked<MemoryEntry>;
+/**
+ * The similarity a memory needs to be returned, for local memory and team knowledge alike. Measured
+ * with scripts/eval/memory-recall.mjs: at 0.25 recall and precision are both 81% and no unrelated
+ * query gets anything; at the previous 0.45, 62% of right memories were missed.
+ */
+export declare const SEMANTIC_FLOOR = 0.25;
+/** Share of the query's words a memory must contain when ranking falls back to keywords. */
+export declare const KEYWORD_FLOOR = 0.5;
+export declare const RECALL_LIMIT = 3;
+type Embed = (text: string) => Promise<number[]>;
+export type Ranked<T> = T & {
+    score: number;
+    match: 'semantic' | 'keyword';
+};
+export declare function rankMemories(query: string, entries: MemoryEntry[], embed?: Embed): Promise<RankedMemory[]>;
+/** The items whose text best matches the query by meaning, at most RECALL_LIMIT, each above the floor. */
+export declare function rankByMeaning<T>(query: string, items: T[], textOf: (item: T) => string, embed?: Embed): Promise<Array<Ranked<T>>>;
+/** What a memory is searched by: its key reads as a title (`db_access` → "db access"). */
+export declare function memoryText(entry: Pick<MemoryEntry, 'key' | 'value'>): string;
+export {};

package/dist/memory/recall.js

@@ -0,0 +1,93 @@
+/**
+ * Recall by meaning: the few memories that match what an agent is about to do,
+ * instead of every memory at once.
+ *
+ * Ranking uses the same local embedding model as the pattern index and team
+ * knowledge (all-MiniLM-L6-v2, loaded lazily so its native dependency never
+ * loads for anything else). When the model is unavailable it falls back to
+ * keyword overlap and says so in each result's `match`.
+ */
+/**
+ * The similarity a memory needs to be returned, for local memory and team knowledge alike. Measured
+ * with scripts/eval/memory-recall.mjs: at 0.25 recall and precision are both 81% and no unrelated
+ * query gets anything; at the previous 0.45, 62% of right memories were missed.
+ */
+export const SEMANTIC_FLOOR = 0.25;
+/** Share of the query's words a memory must contain when ranking falls back to keywords. */
+export const KEYWORD_FLOOR = 0.5;
+export const RECALL_LIMIT = 3;
+/** Memories considered per recall; more are skipped so a large store cannot stall an agent. */
+const MAX_CANDIDATES = 300;
+/**
+ * Embeddings by text, kept for the life of the process: the MCP server is long-lived and the same
+ * memories and lessons are ranked on every recall, so each text is embedded once, not per query.
+ */
+const EMBEDDING_CACHE_LIMIT = 2000;
+const embeddingCache = new Map();
+async function cachedEmbedding(embed, text) {
+    const hit = embeddingCache.get(text);
+    if (hit)
+        return hit;
+    const vector = await embed(text);
+    if (vector.length === 0)
+        return vector; // unavailable: do not remember a failure
+    if (embeddingCache.size >= EMBEDDING_CACHE_LIMIT)
+        embeddingCache.delete(embeddingCache.keys().next().value);
+    embeddingCache.set(text, vector);
+    return vector;
+}
+export async function rankMemories(query, entries, embed) {
+    return rankByMeaning(query, entries, memoryText, embed);
+}
+/** The items whose text best matches the query by meaning, at most RECALL_LIMIT, each above the floor. */
+export async function rankByMeaning(query, items, textOf, embed) {
+    const candidates = items.slice(0, MAX_CANDIDATES);
+    if (candidates.length === 0)
+        return [];
+    const embedText = embed ?? (await import('../pattern-index/embeddings.js')).generateEmbedding;
+    const queryVector = await embedText(query);
+    const ranked = queryVector.length > 0
+        ? await bySimilarity(queryVector, candidates, textOf, embedText)
+        : byKeywords(query, candidates, textOf);
+    return ranked.sort((a, b) => b.score - a.score).slice(0, RECALL_LIMIT);
+}
+async function bySimilarity(queryVector, items, textOf, embed) {
+    const ranked = [];
+    for (const item of items) {
+        const score = cosine(queryVector, await cachedEmbedding(embed, textOf(item)));
+        if (score >= SEMANTIC_FLOOR)
+            ranked.push({ ...item, score, match: 'semantic' });
+    }
+    return ranked;
+}
+function byKeywords(query, items, textOf) {
+    const wanted = words(query);
+    if (wanted.size === 0)
+        return [];
+    return items.flatMap(item => {
+        const have = words(textOf(item));
+        const score = [...wanted].filter(word => have.has(word)).length / wanted.size;
+        return score >= KEYWORD_FLOOR ? [{ ...item, score, match: 'keyword' }] : [];
+    });
+}
+/** What a memory is searched by: its key reads as a title (`db_access` → "db access"). */
+export function memoryText(entry) {
+    return `${entry.key.replace(/[_-]+/g, ' ')}: ${entry.value}`;
+}
+const STOP_WORDS = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'how', 'what', 'when', 'use', 'our', 'are', 'not']);
+function words(text) {
+    return new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter(word => word.length > 2 && !STOP_WORDS.has(word)));
+}
+function cosine(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    return normA && normB ? dot / Math.sqrt(normA * normB) : 0;
+}

package/dist/memory/recall.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/memory/recall.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { RECALL_LIMIT, rankMemories } from './recall.js';
+const memories = [
+    { scope: 'repo', key: 'retry_policy', value: 'Wrap network calls in withRetry from lib/net; never hand-roll backoff.' },
+    { scope: 'repo', key: 'db_access', value: 'Reports read from the replica, never the primary.' },
+    { scope: 'user', key: 'pr_size', value: 'Keep pull requests under 400 lines.' },
+];
+/** A stand-in embedding: one dimension per topic word, so similarity is predictable. */
+const TOPICS = ['retry', 'backoff', 'network', 'replica', 'report', 'pull', 'request'];
+const embed = async (text) => TOPICS.map(topic => (text.toLowerCase().includes(topic) ? 1 : 0));
+describe('rankMemories', () => {
+    it('returns the memories that match by meaning, best first, above the floor', async () => {
+        const ranked = await rankMemories('add exponential backoff to a flaky network call', memories, embed);
+        expect(ranked.map(m => [m.key, m.match])).toEqual([['retry_policy', 'semantic']]);
+    });
+    it('returns nothing rather than the closest weak match', async () => {
+        expect(await rankMemories('rename a css class', memories, embed)).toEqual([]);
+    });
+    it('falls back to keyword overlap when the model is unavailable, and says so', async () => {
+        const ranked = await rankMemories('replica reports', memories, async () => []);
+        expect(ranked.map(m => [m.key, m.match])).toEqual([['db_access', 'keyword']]);
+    });
+    it(`returns at most ${RECALL_LIMIT}`, async () => {
+        const many = Array.from({ length: 10 }, (_, i) => ({ scope: 'repo', key: `retry_${i}`, value: 'network retry backoff' }));
+        expect(await rankMemories('network retry backoff', many, embed)).toHaveLength(RECALL_LIMIT);
+    });
+    it('embeds each text once, not on every recall', async () => {
+        let calls = 0;
+        const counting = async (text) => { calls++; return embed(text); };
+        const fresh = memories.map(m => ({ ...m, value: `${m.value} (cache test)` }));
+        await rankMemories('network retry', fresh, counting);
+        const first = calls;
+        await rankMemories('replica reports', fresh, counting);
+        expect(calls - first).toBe(1); // only the new query
+    });
+});

package/dist/pattern-index/assess.d.ts

@@ -0,0 +1,16 @@
+import type { PatternIndex, PatternMatch, StalenessIssue } from './types.js';
+export interface PatternQuery {
+    name: string;
+    type?: string;
+    intent?: string;
+    signature?: string;
+    keywords?: string[];
+}
+export interface PatternAssessment {
+    action: 'BLOCK' | 'WARN' | 'ALLOW';
+    match?: PatternMatch;
+    suggestion: string;
+    /** Deprecated usage inside the matched function, if any. */
+    deprecations: StalenessIssue[];
+}
+export declare function assessPattern(cwd: string, index: PatternIndex, query: PatternQuery): Promise<PatternAssessment>;

package/dist/pattern-index/assess.js

@@ -0,0 +1,37 @@
+/**
+ * Before writing a function: does the codebase already have it, and is what
+ * would be reused itself out of date? Shared by the MCP rigour_check_pattern
+ * tool and the CLI `rigour check-pattern`.
+ *
+ * BLOCK means an exact or near-certain match (reuse it); WARN means a similar
+ * function exists (look before writing). Deprecations come from the matched
+ * function's own source, never from its name.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { PatternMatcher } from './matcher.js';
+import { StalenessDetector } from './staleness.js';
+export async function assessPattern(cwd, index, query) {
+    const result = await new PatternMatcher(index).match(query);
+    if (result.status !== 'FOUND_SIMILAR')
+        return { action: 'ALLOW', suggestion: '', deprecations: [] };
+    const match = result.matches[0];
+    const source = await readPatternSource(cwd, match.pattern);
+    const staleness = source ? await new StalenessDetector(cwd).checkStaleness(source, match.pattern.file) : undefined;
+    return {
+        action: result.action,
+        match,
+        suggestion: result.suggestion,
+        deprecations: staleness && staleness.status !== 'FRESH' ? staleness.issues : [],
+    };
+}
+/** The lines a pattern spans, or undefined when its file cannot be read. */
+async function readPatternSource(cwd, pattern) {
+    try {
+        const lines = (await fs.readFile(path.join(cwd, pattern.file), 'utf8')).split('\n');
+        return lines.slice(Math.max(0, pattern.line - 1), pattern.endLine).join('\n');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/pattern-index/embeddings.d.ts

@@ -7,6 +7,25 @@
  * Generate an embedding for a piece of text.
  */
 export declare function generateEmbedding(text: string): Promise<number[]>;
+/**
+ * Version of the text patterns are embedded by. An index embedded with an older text is
+ * re-embedded on its next enrichment.
+ *   2: the name split into words (`retryWithBackoff` → "retry with backoff"). Measured by
+ *      scripts/eval/pattern-intent.mjs: recall by intent 87% at 0.30 with no false matches,
+ *      against 13% for the raw name at the old 0.60 bar.
+ */
+export declare const EMBEDDING_TEXT_VERSION = 2;
+export declare function patternEmbeddingText(pattern: {
+    name: string;
+    type: string;
+    description?: string;
+}): string;
+/** A pattern's embedding, rounded to 4 decimals: a third of the size on disk, no change to ranking. */
+export declare function embedPattern(pattern: {
+    name: string;
+    type: string;
+    description?: string;
+}): Promise<number[]>;
 /**
  * Calculate cosine similarity between two vectors.
  */