r2mcp 0.2.0

package/dist/compiler/run.js

@@ -0,0 +1,186 @@
+/**
+ * Compile orchestrator — composes tier and topic synthesis, writes files,
+ * cleans stale outputs, and produces the run summary.
+ *
+ * `runCompile()` is dependency-injected so tests can run it without a DB:
+ * pass in the memory list and a mocked LLMProvider, get back the summary
+ * plus an in-memory file map for assertions.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { compileTier } from './tier.js';
+import { compileTopic } from './topic.js';
+import { topicToSlug } from './clustering.js';
+import { emitFrontmatter } from './frontmatter.js';
+import { computeStaleFiles, manifestPath, readManifest, writeManifest, } from './manifest.js';
+const TIERS = ['preferences', 'project-context', 'conversations'];
+const realFs = {
+    ensureDir: (p) => mkdir(p, { recursive: true }).then(() => undefined),
+    writeFile: (p, c) => writeFile(p, c, 'utf-8'),
+    deleteFile: (p) => (existsSync(p) ? rm(p, { force: true }) : Promise.resolve()),
+    readManifest,
+    writeManifest,
+    exists: existsSync,
+};
+export async function runCompile(opts, deps) {
+    const fs = deps.fs ?? realFs;
+    const stdout = deps.stdout ?? ((s) => process.stdout.write(s));
+    validateOptions(opts);
+    const memories = await deps.loadMemories();
+    const costMeter = { totalCostUsd: 0, hitCap: false };
+    const filesWritten = [];
+    const filesDeleted = [];
+    const newManifest = {
+        run_id: opts.runId,
+        generated_at: opts.startedAt,
+        tiers: [],
+        topics: [],
+    };
+    const tiersInScope = [];
+    const topicsInScope = [];
+    // ---- Tier compile ----
+    const tiersToBuild = opts.all ? [...TIERS] : opts.tier ? [opts.tier] : [];
+    for (const tier of tiersToBuild) {
+        if (costMeter.hitCap)
+            break;
+        tiersInScope.push(tier);
+        const tierMemories = memories.filter((m) => m.tier === tier && m.type !== 'archived');
+        const result = await compileTier({
+            tier,
+            memories: tierMemories,
+            provider: deps.provider,
+            runId: opts.runId,
+            maxCostUsd: opts.maxCostUsd,
+            costMeter,
+        });
+        const fm = {
+            generated_at: opts.startedAt,
+            compile_run_id: opts.runId,
+            source_count: result.source_memory_ids.length,
+            source_memory_ids: result.source_memory_ids,
+            provider: deps.provider.name,
+            source_git_sha: opts.sourceGitSha,
+            tier,
+        };
+        const fileContent = emitFrontmatter(fm) + '\n' + result.body;
+        const relPath = `${tier}.md`;
+        const absPath = resolve(opts.compiledDir, relPath);
+        if (opts.dryRun) {
+            stdout(`\n--- DRY RUN: ${relPath} ---\n`);
+            stdout(fileContent);
+        }
+        else {
+            await fs.ensureDir(opts.compiledDir);
+            await fs.writeFile(absPath, fileContent);
+            filesWritten.push(absPath);
+        }
+        newManifest.tiers.push({ tier, path: relPath, source_memory_ids: result.source_memory_ids });
+    }
+    // ---- Topic compile ----
+    if (opts.topic) {
+        topicsInScope.push(opts.topic);
+        const slug = topicToSlug(opts.topic);
+        const result = await compileTopic({
+            topic: opts.topic,
+            memories: memories.filter((m) => m.type !== 'archived'),
+            provider: deps.provider,
+            runId: opts.runId,
+            maxCostUsd: opts.maxCostUsd,
+            costMeter,
+        });
+        const fm = {
+            generated_at: opts.startedAt,
+            compile_run_id: opts.runId,
+            source_count: result.source_memory_ids.length,
+            source_memory_ids: result.source_memory_ids,
+            provider: deps.provider.name,
+            source_git_sha: opts.sourceGitSha,
+            topic: opts.topic,
+        };
+        const fileContent = emitFrontmatter(fm) + '\n' + result.body;
+        const relPath = join('topics', `${slug}.md`);
+        const absPath = resolve(opts.compiledDir, relPath);
+        if (opts.dryRun) {
+            stdout(`\n--- DRY RUN: ${relPath} ---\n`);
+            stdout(fileContent);
+        }
+        else {
+            await fs.ensureDir(dirname(absPath));
+            await fs.writeFile(absPath, fileContent);
+            filesWritten.push(absPath);
+        }
+        newManifest.topics.push({
+            topic: opts.topic,
+            path: relPath,
+            source_memory_ids: result.source_memory_ids,
+        });
+    }
+    // ---- Manifest + stale cleanup ----
+    let manifestAbs = manifestPath(opts.compiledDir);
+    if (!opts.dryRun && filesWritten.length > 0) {
+        // Merge with prior manifest entries that we DIDN'T touch this run, so a
+        // tier-only invocation doesn't drop unrelated topic entries.
+        const prev = await fs.readManifest(opts.compiledDir);
+        const merged = mergeManifest(prev, newManifest, {
+            tiersTouched: tiersInScope,
+            topicsTouched: topicsInScope,
+        });
+        const stale = computeStaleFiles(prev, merged, {
+            tiers: tiersInScope,
+            topics: topicsInScope,
+            allTopics: false,
+        });
+        for (const rel of stale) {
+            const abs = resolve(opts.compiledDir, rel);
+            await fs.deleteFile(abs);
+            filesDeleted.push(abs);
+        }
+        manifestAbs = await fs.writeManifest(opts.compiledDir, merged);
+    }
+    return {
+        run_id: opts.runId,
+        started_at: opts.startedAt,
+        ended_at: new Date().toISOString(),
+        files_written: filesWritten.map((p) => relative(opts.compiledDir, p)),
+        files_deleted: filesDeleted.map((p) => relative(opts.compiledDir, p)),
+        total_cost_usd: costMeter.totalCostUsd,
+        hit_cost_cap: costMeter.hitCap,
+        provider: deps.provider.name,
+        source_git_sha: opts.sourceGitSha,
+        manifest_path: manifestAbs,
+        dry_run: !!opts.dryRun,
+    };
+}
+function validateOptions(opts) {
+    const modes = [opts.tier, opts.all, opts.topic].filter(Boolean).length;
+    if (modes !== 1) {
+        throw new Error('compile() requires exactly one of: tier, all, topic');
+    }
+}
+/**
+ * Combine a fresh per-tier/per-topic manifest with the prior run's manifest,
+ * keeping prior entries that weren't in this run's scope. Per-tier or per-
+ * topic compiles don't wipe untouched entries (B.R8 nuance).
+ */
+function mergeManifest(prev, next, scope) {
+    if (!prev)
+        return next;
+    const merged = {
+        run_id: next.run_id,
+        generated_at: next.generated_at,
+        tiers: [...next.tiers],
+        topics: [...next.topics],
+    };
+    // Keep prior tier entries we didn't touch
+    for (const t of prev.tiers) {
+        if (!scope.tiersTouched.includes(t.tier))
+            merged.tiers.push(t);
+    }
+    // Keep prior topic entries we didn't touch
+    for (const t of prev.topics) {
+        if (!scope.topicsTouched.includes(t.topic))
+            merged.topics.push(t);
+    }
+    return merged;
+}

package/dist/compiler/tier.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tier-level wiki compile (preferences / project-context / conversations).
+ *
+ * Compiler-controlled structure (headers, citations) → LLM-controlled prose.
+ * This split keeps headers and source_memory_ids deterministic across runs
+ * (B.R5 / B.AC3) while allowing prose-level variance under the 5% Levenshtein
+ * threshold.
+ */
+import type { CompileSectionResult, CompileTierInput } from './types.js';
+export declare function compileTier(input: CompileTierInput): Promise<CompileSectionResult>;

package/dist/compiler/tier.js

@@ -0,0 +1,85 @@
+/**
+ * Tier-level wiki compile (preferences / project-context / conversations).
+ *
+ * Compiler-controlled structure (headers, citations) → LLM-controlled prose.
+ * This split keeps headers and source_memory_ids deterministic across runs
+ * (B.R5 / B.AC3) while allowing prose-level variance under the 5% Levenshtein
+ * threshold.
+ */
+import { clusterByTopic, topicTitle } from './clustering.js';
+import { tierSystemPrompt, tierClusterUserPrompt } from './prompts.js';
+import { withLLMCallSpan } from '../telemetry.js';
+const TIER_HEADERS = {
+    preferences: 'Preferences and Decisions',
+    'project-context': 'Project Context',
+    conversations: 'Relationship and Continuity',
+};
+const MAX_TOKENS_PER_CLUSTER = 400;
+export async function compileTier(input) {
+    const { tier, memories, provider, maxCostUsd, costMeter } = input;
+    const clusters = clusterByTopic(memories);
+    const headers = [`## ${TIER_HEADERS[tier]}`];
+    const sourceIds = new Set();
+    const lines = [`## ${TIER_HEADERS[tier]}`, ''];
+    let partial = false;
+    let sectionCost = 0;
+    if (clusters.length === 0) {
+        lines.push('_No memories in this tier yet._');
+        return {
+            body: lines.join('\n') + '\n',
+            source_memory_ids: [],
+            headers,
+            cost_usd: 0,
+            partial: false,
+        };
+    }
+    for (const cluster of clusters) {
+        if (costMeter.totalCostUsd >= maxCostUsd) {
+            partial = true;
+            costMeter.hitCap = true;
+            break;
+        }
+        // Reserve estimate (worst-case) before issuing the call.
+        if (costMeter.totalCostUsd + estimatedCallCost() > maxCostUsd) {
+            partial = true;
+            costMeter.hitCap = true;
+            break;
+        }
+        const heading = `### ${topicTitle(cluster.topic)}`;
+        headers.push(heading);
+        // claw-1ejd: wrap LLM call for cross-process trace inheritance.
+        const result = await withLLMCallSpan('memory.compile_wiki.call', { provider: provider.name, model: 'haiku' }, () => provider.complete({
+            model: 'haiku',
+            system: tierSystemPrompt(tier),
+            prompt: tierClusterUserPrompt(cluster.topic, cluster.memories),
+            max_tokens: MAX_TOKENS_PER_CLUSTER,
+        }));
+        costMeter.totalCostUsd += result.cost_usd;
+        sectionCost += result.cost_usd;
+        const prose = result.response.trim();
+        lines.push('');
+        lines.push(heading);
+        lines.push('');
+        lines.push(prose === '' ? '_(synthesis returned empty paragraph)_' : prose);
+        lines.push('');
+        const cites = cluster.memories.map((m) => `<m:${m.id}>`).join(' ');
+        lines.push(`Sources: ${cites}`);
+        for (const m of cluster.memories)
+            sourceIds.add(m.id);
+    }
+    return {
+        body: lines.join('\n') + '\n',
+        source_memory_ids: [...sourceIds].sort(),
+        headers,
+        cost_usd: sectionCost,
+        partial,
+    };
+}
+/**
+ * Conservative pre-call estimate. Tracks Anthropic's haiku list price for
+ * an 800-token input + 400-token output: 0.0008*0.80 + 0.0004*4.00 ≈ $0.0022.
+ * Used for cap-respect math; not for final cost reporting (which uses actuals).
+ */
+function estimatedCallCost() {
+    return 0.003;
+}

package/dist/compiler/topic.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-topic wiki page compile.
+ *
+ * Output shape (B.AC4):
+ *   ## Summary
+ *   ## Key Decisions
+ *   ## Open Questions
+ *   ## Timeline
+ *
+ * Summary / Key Decisions / Open Questions are LLM-synthesized. Timeline is
+ * deterministic — built from `created_at` ordering — so it adds zero LLM cost
+ * and gives the page a stable scaffold even when the LLM declines to produce
+ * Open Questions content.
+ */
+import type { CompileSectionResult, CompileTopicInput } from './types.js';
+export declare function compileTopic(input: CompileTopicInput): Promise<CompileSectionResult>;

package/dist/compiler/topic.js

@@ -0,0 +1,105 @@
+/**
+ * Per-topic wiki page compile.
+ *
+ * Output shape (B.AC4):
+ *   ## Summary
+ *   ## Key Decisions
+ *   ## Open Questions
+ *   ## Timeline
+ *
+ * Summary / Key Decisions / Open Questions are LLM-synthesized. Timeline is
+ * deterministic — built from `created_at` ordering — so it adds zero LLM cost
+ * and gives the page a stable scaffold even when the LLM declines to produce
+ * Open Questions content.
+ */
+import { memoriesForTopic } from './clustering.js';
+import { topicSectionUserPrompt, topicSystemPrompt } from './prompts.js';
+import { withLLMCallSpan } from '../telemetry.js';
+const SECTION_NAMES = ['Summary', 'Key Decisions', 'Open Questions'];
+const MAX_TOKENS_PER_SECTION = 500;
+export async function compileTopic(input) {
+    const { topic, memories, provider, maxCostUsd, costMeter } = input;
+    const relevant = memoriesForTopic(memories, topic);
+    const headers = [];
+    const lines = [];
+    const sourceIds = new Set();
+    let partial = false;
+    let sectionCost = 0;
+    if (relevant.length === 0) {
+        headers.push('## Summary');
+        lines.push('## Summary', '', `_No memories tagged with topic '${topic}'._`, '');
+        return {
+            body: lines.join('\n') + '\n',
+            source_memory_ids: [],
+            headers,
+            cost_usd: 0,
+            partial: false,
+        };
+    }
+    for (const section of SECTION_NAMES) {
+        if (costMeter.totalCostUsd >= maxCostUsd) {
+            partial = true;
+            costMeter.hitCap = true;
+            break;
+        }
+        if (costMeter.totalCostUsd + 0.003 > maxCostUsd) {
+            partial = true;
+            costMeter.hitCap = true;
+            break;
+        }
+        const heading = `## ${section}`;
+        headers.push(heading);
+        // claw-1ejd: wrap LLM call for cross-process trace inheritance.
+        const result = await withLLMCallSpan('memory.compile_wiki.call', { provider: provider.name, model: 'haiku' }, () => provider.complete({
+            model: 'haiku',
+            system: topicSystemPrompt(),
+            prompt: topicSectionUserPrompt(topic, section, relevant),
+            max_tokens: MAX_TOKENS_PER_SECTION,
+        }));
+        costMeter.totalCostUsd += result.cost_usd;
+        sectionCost += result.cost_usd;
+        lines.push(heading, '');
+        const prose = result.response.trim();
+        if (prose === 'NONE' || prose === '') {
+            lines.push('_(no relevant content)_');
+        }
+        else {
+            lines.push(prose);
+        }
+        lines.push('');
+        const citeIds = sectionMemoryIds(section, relevant);
+        if (citeIds.length > 0) {
+            const cites = citeIds.map((id) => `<m:${id}>`).join(' ');
+            lines.push(`Sources: ${cites}`);
+            lines.push('');
+            for (const id of citeIds)
+                sourceIds.add(id);
+        }
+    }
+    // Timeline is deterministic — no LLM call.
+    if (!partial) {
+        headers.push('## Timeline');
+        lines.push('## Timeline', '');
+        for (const m of relevant) {
+            const date = (m.created_at || '').slice(0, 10) || 'unknown';
+            const excerpt = m.content.length > 120 ? m.content.slice(0, 117) + '...' : m.content;
+            lines.push(`- ${date} — <m:${m.id}> ${excerpt}`);
+            sourceIds.add(m.id);
+        }
+        lines.push('');
+    }
+    return {
+        body: lines.join('\n') + '\n',
+        source_memory_ids: [...sourceIds].sort(),
+        headers,
+        cost_usd: sectionCost,
+        partial,
+    };
+}
+function sectionMemoryIds(section, memories) {
+    // For now, every section cites the same set of source memories (the entire
+    // topic-tagged set). A future refinement can attribute differently per
+    // section, but the contract is "stable across runs" — and "all memories
+    // for the topic" is trivially stable.
+    return [...memories.map((m) => m.id)].sort();
+}

package/dist/compiler/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared types for the wiki compile step (SPEC-044 Section B).
+ */
+import type { LLMProvider } from '../providers/types.js';
+export type Tier = 'preferences' | 'project-context' | 'conversations';
+/** A memory row as the compiler sees it — only the fields synthesis needs. */
+export interface MemoryForCompile {
+    id: string;
+    tier: Tier;
+    type: string;
+    content: string;
+    topics: string[];
+    people: string[];
+    created_at: string;
+    /** Optional inbound supersedes/contradicts edges for prose framing (B.R9). */
+    edges?: EdgeForCompile[];
+}
+export interface EdgeForCompile {
+    from_memory_id: string;
+    to_memory_id: string;
+    relation: 'supports' | 'contradicts' | 'supersedes' | 'evolved_into' | 'depends_on' | 'related_to';
+    rationale: string;
+    confidence: number;
+}
+export interface CompileFrontmatter {
+    generated_at: string;
+    compile_run_id: string;
+    source_count: number;
+    source_memory_ids: string[];
+    provider: string;
+    source_git_sha: string | null;
+    tier?: Tier;
+    topic?: string;
+}
+export interface CompileTierInput {
+    tier: Tier;
+    memories: MemoryForCompile[];
+    provider: LLMProvider;
+    runId: string;
+    /** If exceeded mid-run, the compile exits gracefully with hit_cost_cap=true. */
+    maxCostUsd: number;
+    /** Counter shared with the orchestrator so cap is enforced across tiers. */
+    costMeter: {
+        totalCostUsd: number;
+        hitCap: boolean;
+    };
+}
+export interface CompileTopicInput {
+    topic: string;
+    memories: MemoryForCompile[];
+    provider: LLMProvider;
+    runId: string;
+    maxCostUsd: number;
+    costMeter: {
+        totalCostUsd: number;
+        hitCap: boolean;
+    };
+}
+export interface CompileSectionResult {
+    /** Full markdown body (frontmatter prepended by caller). */
+    body: string;
+    /** Memory IDs that contributed to this section (for frontmatter, B.R3). */
+    source_memory_ids: string[];
+    /** Set of `## H2` and `### H3` headers (B.R5/B.AC3 stability check). */
+    headers: string[];
+    /** Cost spent producing this section. */
+    cost_usd: number;
+    /** True when the run hit `maxCostUsd` mid-synthesis. */
+    partial: boolean;
+}
+export interface CompileSummary {
+    run_id: string;
+    started_at: string;
+    ended_at: string;
+    files_written: string[];
+    files_deleted: string[];
+    total_cost_usd: number;
+    hit_cost_cap: boolean;
+    provider: string;
+    source_git_sha: string | null;
+    /** Path to the manifest written this run. */
+    manifest_path: string;
+    /** True for dry-run; preview emitted to stdout. */
+    dry_run: boolean;
+}
+export interface CompileManifest {
+    run_id: string;
+    generated_at: string;
+    /** Per-tier files written this run, with their `source_memory_ids`. */
+    tiers: Array<{
+        tier: Tier;
+        path: string;
+        source_memory_ids: string[];
+    }>;
+    /** Per-topic files written this run. */
+    topics: Array<{
+        topic: string;
+        path: string;
+        source_memory_ids: string[];
+    }>;
+}

package/dist/compiler/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for the wiki compile step (SPEC-044 Section B).
+ */
+export {};

package/dist/db.d.ts

@@ -0,0 +1,10 @@
+import pg from 'pg';
+/**
+ * claw-8cjf.2: refuse to guess a database. The old localhost fallback sent
+ * writes to the wrong database on misconfiguration and helped nobody — the
+ * Docker default is a different URL anyway (r2mcp:r2mcp@localhost, not bare).
+ */
+export declare const MISSING_DATABASE_URL_MESSAGE: string;
+export declare function getPool(): pg.Pool;
+export declare function initDb(): Promise<void>;
+export declare function closeDb(): Promise<void>;

package/dist/db.js

@@ -0,0 +1,46 @@
+import pg from 'pg';
+import pgvector from 'pgvector/pg';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let pool = null;
+/**
+ * claw-8cjf.2: refuse to guess a database. The old localhost fallback sent
+ * writes to the wrong database on misconfiguration and helped nobody — the
+ * Docker default is a different URL anyway (r2mcp:r2mcp@localhost, not bare).
+ */
+export const MISSING_DATABASE_URL_MESSAGE = 'R2MCP_DATABASE_URL is not set. r2mcp refuses to guess a database. Set it via:\n' +
+    '  • .mcp.json: add R2MCP_DATABASE_URL to the server\'s "env" block (recommended), or\n' +
+    '  • .env in the project root: R2MCP_DATABASE_URL=postgresql://...\n' +
+    'For local Docker (docker compose up -d, then npm run setup) use:\n' +
+    '  postgresql://r2mcp:r2mcp@localhost:5432/r2mcp';
+export function getPool() {
+    if (!pool) {
+        const connectionString = process.env.R2MCP_DATABASE_URL;
+        if (!connectionString) {
+            throw new Error(MISSING_DATABASE_URL_MESSAGE);
+        }
+        pool = new pg.Pool({ connectionString });
+    }
+    return pool;
+}
+export async function initDb() {
+    const p = getPool();
+    // pgvector.registerTypes requires a client (not pool) for setTypeParser
+    const client = await p.connect();
+    try {
+        await pgvector.registerTypes(client);
+    }
+    finally {
+        client.release();
+    }
+    const schema = readFileSync(join(__dirname, 'schema.sql'), 'utf-8');
+    await p.query(schema);
+}
+export async function closeDb() {
+    if (pool) {
+        await pool.end();
+        pool = null;
+    }
+}

package/dist/edges/candidate-pairs.d.ts

@@ -0,0 +1,24 @@
+import type pg from 'pg';
+export interface CandidatePair {
+    from_id: string;
+    to_id: string;
+    shared_topics: string[];
+    shared_people: string[];
+}
+export interface CandidateOptions {
+    sinceDays?: number;
+}
+/**
+ * Find candidate memory pairs eligible for edge classification (spec R5).
+ *
+ * Eligibility:
+ *   - share >=2 topics, OR
+ *   - share >=1 person
+ *
+ * Returns each unordered pair once (using id order to deduplicate).
+ * Excludes self-pairs.
+ *
+ * If `sinceDays` is set, at least one memory in the pair must have been
+ * created within that window — used by --since to limit incremental runs.
+ */
+export declare function findCandidatePairs(pool: pg.Pool, opts: CandidateOptions): Promise<CandidatePair[]>;

package/dist/edges/candidate-pairs.js

@@ -0,0 +1,35 @@
+/**
+ * Find candidate memory pairs eligible for edge classification (spec R5).
+ *
+ * Eligibility:
+ *   - share >=2 topics, OR
+ *   - share >=1 person
+ *
+ * Returns each unordered pair once (using id order to deduplicate).
+ * Excludes self-pairs.
+ *
+ * If `sinceDays` is set, at least one memory in the pair must have been
+ * created within that window — used by --since to limit incremental runs.
+ */
+export async function findCandidatePairs(pool, opts) {
+    const sinceClause = opts.sinceDays
+        ? `AND (m1.created_at >= NOW() - ($1 || ' days')::interval
+            OR m2.created_at >= NOW() - ($1 || ' days')::interval)`
+        : '';
+    const params = opts.sinceDays ? [String(opts.sinceDays)] : [];
+    const sql = `
+    SELECT m1.id AS from_id, m2.id AS to_id,
+           ARRAY(SELECT unnest(m1.topics) INTERSECT SELECT unnest(m2.topics)) AS shared_topics,
+           ARRAY(SELECT unnest(m1.people) INTERSECT SELECT unnest(m2.people)) AS shared_people
+    FROM memories m1
+    JOIN memories m2
+      ON m1.id < m2.id
+     AND (
+           cardinality(ARRAY(SELECT unnest(m1.topics) INTERSECT SELECT unnest(m2.topics))) >= 2
+           OR cardinality(ARRAY(SELECT unnest(m1.people) INTERSECT SELECT unnest(m2.people))) >= 1
+         )
+    WHERE TRUE ${sinceClause}
+  `;
+    const res = await pool.query(sql, params);
+    return res.rows;
+}

package/dist/edges/classifier.d.ts

@@ -0,0 +1,45 @@
+import type { CandidatePair } from './candidate-pairs.js';
+import type { Stage1Result } from './stage1-haiku.js';
+import type { Stage2Result, MemoryForClassify } from './stage2-opus.js';
+import type { StateStore, RunSummary, RunSummaryWriter } from './state.js';
+import type { EdgeRelation } from './types.js';
+export interface ClassifierDeps {
+    findCandidatePairs: (opts: {
+        sinceDays?: number;
+    }) => Promise<CandidatePair[]>;
+    fetchMemoryById: (id: string) => Promise<MemoryForClassify | null>;
+    stage1Filter: (pair: {
+        from: {
+            id: string;
+            content: string;
+        };
+        to: {
+            id: string;
+            content: string;
+        };
+    }) => Promise<Stage1Result>;
+    stage2Classify: (pair: {
+        from: MemoryForClassify;
+        to: MemoryForClassify;
+    }) => Promise<Stage2Result>;
+    insertEdge: (fromId: string, toId: string, relation: EdgeRelation, confidence: number, rationale: string, classifierVersion: string) => Promise<string>;
+    state: StateStore;
+    summaryWriter: RunSummaryWriter;
+    classifierVersion: string;
+    estimateCost?: (pairs: CandidatePair[]) => Promise<number>;
+    /**
+     * Per-provider concurrency cap. Defaults to 1 (sequential — preserves
+     * the SPEC-043 behavior). Set to LLMProvider.concurrencyLimit at the call
+     * site to enable concurrent dispatch (D.R6, D.AC8).
+     */
+    concurrencyLimit?: number;
+    /** Reports the active provider name into the run summary (D.R3). */
+    providerName?: string;
+}
+export interface RunOptions {
+    runId: string;
+    maxCostUsd: number;
+    dryRun: boolean;
+    sinceDays?: number;
+}
+export declare function runClassifier(opts: RunOptions, deps: ClassifierDeps): Promise<RunSummary>;