@zenithfoundry/slm-gate 1.2.1

package/dist/ledger/sync-config.js

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview Programmatic setup utility to initialize Langfuse Score Configs,
+ * Model Definitions, and Monitors via the Langfuse Management API.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG } from '../config.js';
+import { PRICING } from '../pricing/index.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Automatically creates Score Configs in Langfuse:
+ * - 'verified' (Categorical: 1='Passed', 0='Escalated') -> replaces '0' and '1' in Langfuse UI with informative labels!
+ * - 'cost_saved_usd' (Numeric)
+ * - 'tokens_saved' (Numeric)
+ * - 'quality_score' (Numeric)
+ */
+/**
+ * Score names an earlier build wrote and this one no longer does. Their rows stay in Langfuse
+ * until deleted; no card reads them. setup-dashboard removes widgets that still filter on them,
+ * and ledger:verify labels them instead of reporting them as an unexplained surplus.
+ */
+export const RETIRED_SCORE_NAMES = [
+    'cycle_extended_per_window_claude',
+    'cycle_extended_per_window_chatgpt',
+    'cycle_extended_per_window_gemini',
+];
+/** The score configs the gate registers. Also the list langfuse:wipe archives, and nothing else. */
+export const SCORE_CONFIGS = [
+    {
+        name: 'verified',
+        dataType: 'CATEGORICAL',
+        categories: [
+            { label: 'Passed (Local SLM)', value: 'Passed (Local SLM)' },
+            { label: 'Distilled (Forwarded)', value: 'Distilled (Forwarded)' },
+            { label: 'Escalated (Cloud)', value: 'Escalated (Cloud)' }
+        ],
+        description: 'Routing outcome: resolved locally, distilled then forwarded, or escalated to cloud'
+    },
+    {
+        name: 'cost_saved_cents',
+        dataType: 'NUMERIC',
+        description: 'Estimated cloud API dollars avoided (converted to Cents) by the local SLM'
+    },
+    {
+        name: 'tokens_saved',
+        dataType: 'NUMERIC',
+        description: 'Number of cloud LLM tokens avoided via local SLM routing'
+    },
+    {
+        name: 'accuracy_rate_pct',
+        dataType: 'NUMERIC',
+        maxValue: 100,
+        minValue: 0,
+        description: 'Accuracy of the SLM gate output against the expected cloud model standard (%)'
+    },
+    // Each provider is registered twice: the same quantity in minutes and in seconds.
+    // A score row carries a number and no unit, and a dashboard widget cannot convert
+    // between units, so a card that reads in seconds needs a score already in seconds.
+    {
+        name: 'cycle_extended_minutes_chatgpt',
+        dataType: 'NUMERIC',
+        description: 'Extra MINUTES of a 3h ChatGPT window freed by this single request (summed for the range total)'
+    },
+    {
+        name: 'cycle_extended_seconds_chatgpt',
+        dataType: 'NUMERIC',
+        description: 'Extra SECONDS of a 3h ChatGPT window freed by this single request (averaged for the per-prompt figure)'
+    },
+    {
+        name: 'cycle_extended_minutes_claude',
+        dataType: 'NUMERIC',
+        description: 'Extra MINUTES of a 5h Claude window freed by this single request (summed for the range total)'
+    },
+    {
+        name: 'cycle_extended_seconds_claude',
+        dataType: 'NUMERIC',
+        description: 'Extra SECONDS of a 5h Claude window freed by this single request (averaged for the per-prompt figure)'
+    },
+    {
+        name: 'cycle_extended_minutes_gemini',
+        dataType: 'NUMERIC',
+        description: 'Extra MINUTES of a 5h Gemini window freed by this single request (summed for the range total)'
+    },
+    {
+        name: 'cycle_extended_seconds_gemini',
+        dataType: 'NUMERIC',
+        description: 'Extra SECONDS of a 5h Gemini window freed by this single request (averaged for the per-prompt figure)'
+    }
+];
+export async function syncScoreConfigs() {
+    if (!CONFIG.LANGFUSE_PUBLIC_KEY || !CONFIG.LANGFUSE_SECRET_KEY || !CONFIG.LANGFUSE_HOST) {
+        return;
+    }
+    const authHeader = 'Basic ' + Buffer.from(`${CONFIG.LANGFUSE_PUBLIC_KEY}:${CONFIG.LANGFUSE_SECRET_KEY}`).toString('base64');
+    const baseUrl = CONFIG.LANGFUSE_HOST.replace(/\/$/, '');
+    console.log('Initializing Langfuse Score Configurations...');
+    for (const config of SCORE_CONFIGS) {
+        try {
+            const res = await fetch(`${baseUrl}/api/public/score-configs`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': authHeader,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(config)
+            });
+            if (res.ok) {
+                console.log(`  ✓ Score config registered: ${config.name}`);
+            }
+            else if (res.status === 409 || res.status === 400) {
+                // Already exists or duplicate name
+                console.log(`  • Score config already active: ${config.name}`);
+            }
+            else {
+                console.warn(`  ! Score config ${config.name} response: ${res.statusText}`);
+            }
+        }
+        catch (err) {
+            console.warn(`  ! Could not sync score config ${config.name}: ${err.message}`);
+        }
+    }
+}
+/**
+ * Automatically creates Model Definitions and Pricing in Langfuse
+ */
+export async function syncModelDefinitions() {
+    if (!CONFIG.LANGFUSE_PUBLIC_KEY || !CONFIG.LANGFUSE_SECRET_KEY || !CONFIG.LANGFUSE_HOST) {
+        return;
+    }
+    const authHeader = 'Basic ' + Buffer.from(`${CONFIG.LANGFUSE_PUBLIC_KEY}:${CONFIG.LANGFUSE_SECRET_KEY}`).toString('base64');
+    const baseUrl = CONFIG.LANGFUSE_HOST.replace(/\/$/, '');
+    console.log('Initializing Langfuse Model Definitions...');
+    for (const [modelName, rates] of Object.entries(PRICING)) {
+        try {
+            const modelPayload = {
+                modelName,
+                matchPattern: `(?i)^${modelName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*$`,
+                unit: 'TOKENS',
+                inputPrice: rates.in / 1e6,
+                outputPrice: rates.out / 1e6,
+            };
+            const res = await fetch(`${baseUrl}/api/public/models`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': authHeader,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(modelPayload)
+            });
+            if (res.ok) {
+                console.log(`  ✓ Model definition registered: ${modelName}`);
+            }
+            else if (res.status === 409 || res.status === 400) {
+                console.log(`  • Model definition already active: ${modelName}`);
+            }
+        }
+        catch (err) {
+            console.warn(`  ! Could not sync model ${modelName}: ${err.message}`);
+        }
+    }
+}
+export async function initLangfuseConfigs() {
+    await syncScoreConfigs();
+    await syncModelDefinitions();
+}
+// Direct execution
+if (process.argv[1] && (process.argv[1].endsWith('sync-config.ts') || process.argv[1].endsWith('sync-config.js'))) {
+    initLangfuseConfigs()
+        .then(() => {
+        console.log('Langfuse configurations successfully initialized.');
+        process.exit(0);
+    })
+        .catch((err) => {
+        console.error('Failed to initialize Langfuse configs:', err);
+        process.exit(1);
+    });
+}

package/dist/ledger/sync.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview CLI utility script to synchronize/backfill SQLite ledger records to Langfuse Cloud.
+ *
+ * Every id it sends is deterministic (trace = request_id, scores and generations derived
+ * from it), so a re-send updates in place and never duplicates. That makes it the backfill:
+ * re-running it gives old traces the current tags. Each event keeps the environment it was
+ * written under: Langfuse moves a re-sent trace to a new environment but never its scores
+ * (tested 2026-09-23), so moving history would split every trace from its own scores.
+ *
+ * Usage:
+ *   pnpm run ledger:sync [--all] [--limit <n>] [--after <rowid>] [--dry-run]
+ */
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { CONFIG, requireKeys } from '../config.js';
+import { waitWithBackoff } from '../utils/backoff.js';
+import { formatDuration } from '../utils/duration.js';
+import { computeCycleRateAvg, computeCycleRates, formatEventForLangfuse, getDb, LangfuseSink, logLedgerInfo } from './index.js';
+import { initLangfuseConfigs } from './sync-config.js';
+export { computeCycleRateAvg };
+/** Hobby projects allow 30 requests a minute; one batch every 2.1 s stays under it. */
+const REQUEST_SPACING_MS = 2100;
+const MAX_ATTEMPTS = 5;
+export async function syncLedgerToLangfuse(options = {}) {
+    const { limit, after = 0, dryRun = false } = options;
+    console.log('=== SLM Gate: SQLite to Langfuse Ledger Sync ===\n');
+    console.log(`Database Source : ${path.resolve(CONFIG.LEDGER_PATH)}`);
+    console.log(`Target Host     : ${CONFIG.LANGFUSE_HOST || '<Not Set>'}`);
+    console.log(`Mode            : ${dryRun ? 'DRY-RUN (No network requests)' : 'LIVE SYNC'}\n`);
+    logLedgerInfo('sync');
+    if (!dryRun) {
+        requireKeys(['LANGFUSE_PUBLIC_KEY', 'LANGFUSE_SECRET_KEY', 'LANGFUSE_HOST']);
+        await initLangfuseConfigs();
+    }
+    const db = getDb();
+    let query = 'SELECT rowid AS ledger_rowid, * FROM events WHERE rowid > ? ORDER BY rowid ASC';
+    if (limit && limit > 0) {
+        query += ` LIMIT ${limit}`;
+    }
+    const rows = db.prepare(query).all(after);
+    console.log(`Found ${rows.length} total event(s) in SQLite ledger.\n`);
+    if (rows.length === 0) {
+        console.log('No events to synchronize.');
+        return {
+            totalEvents: 0,
+            syncedTraces: 0,
+            localCalls: 0,
+            cloudCalls: 0,
+            localTokens: 0,
+            cloudTokens: 0,
+            baselineCostUsd: 0,
+            actualCostUsd: 0,
+            costSavedUsd: 0,
+            tokensSaved: 0,
+            baselineTokens: 0,
+            errors: 0,
+        };
+    }
+    const stats = {
+        totalEvents: rows.length,
+        syncedTraces: 0,
+        localCalls: 0,
+        cloudCalls: 0,
+        localTokens: 0,
+        cloudTokens: 0,
+        baselineCostUsd: 0,
+        actualCostUsd: 0,
+        costSavedUsd: 0,
+        tokensSaved: 0,
+        baselineTokens: 0,
+        errors: 0,
+    };
+    const BATCH_SIZE = 50;
+    let batchCount = 0;
+    // Rowid of the last event whose batch Langfuse accepted: where a stopped run resumes.
+    let lastAcceptedRowid = after;
+    let batchLastRowid = after;
+    let batch = [];
+    /**
+     * Sends the pending batch, paced under the rate limit and retried on 429, 5xx and network
+     * errors. Returns false when Langfuse still refuses it, so the caller stops instead of
+     * skipping a batch: a skipped batch would leave a gap nobody sees.
+     */
+    const flushBatch = async () => {
+        if (batch.length === 0)
+            return true;
+        const auth = Buffer.from(`${CONFIG.LANGFUSE_PUBLIC_KEY}:${CONFIG.LANGFUSE_SECRET_KEY}`).toString('base64');
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+            await setTimeout(REQUEST_SPACING_MS);
+            let res;
+            try {
+                res = await fetch(`${CONFIG.LANGFUSE_HOST}/api/public/ingestion`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Basic ${auth}`,
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify({ batch })
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (attempt === MAX_ATTEMPTS - 1) {
+                    console.error('\nNetwork error during sync:', message);
+                    break;
+                }
+                await waitWithBackoff(attempt, MAX_ATTEMPTS, `Langfuse network error (${message})`, null, 'sync');
+                continue;
+            }
+            let body = null;
+            try {
+                body = await res.json();
+            }
+            catch { /* not JSON */ }
+            if (res.ok) {
+                // A 207 accepts the batch but may reject single items; they are counted, and
+                // ledger:verify shows which score names came up short.
+                if (body && Array.isArray(body.errors) && body.errors.length > 0) {
+                    for (const e of body.errors) {
+                        console.error(`[sync] Langfuse per-item error: id=${e.id ?? 'unknown'} status=${e.status ?? 'unknown'} ${e.message ?? e.error ?? ''}`);
+                    }
+                    stats.errors += body.errors.length;
+                }
+                stats.syncedTraces += batchCount;
+                lastAcceptedRowid = batchLastRowid;
+                process.stdout.write(`\rProgress: ${stats.syncedTraces}/${rows.length} traces synced...`);
+                batch = [];
+                batchCount = 0;
+                return true;
+            }
+            const transient = res.status === 429 || res.status >= 500;
+            if (!transient || attempt === MAX_ATTEMPTS - 1) {
+                console.warn(`\nLangfuse sync failed (${res.status}): ${body ? JSON.stringify(body) : '(no body)'}`);
+                break;
+            }
+            await waitWithBackoff(attempt, MAX_ATTEMPTS, `Langfuse ingestion ${res.status}`, res.headers.get('retry-after'), 'sync');
+        }
+        stats.errors += batchCount;
+        return false;
+    };
+    const hasClient = !dryRun && LangfuseSink.hasValidConfig();
+    if (!dryRun && !hasClient) {
+        throw new Error('Could not initialize Langfuse sync. Verify LANGFUSE_* keys in .env.');
+    }
+    for (let i = 0; i < rows.length; i++) {
+        const event = rows[i];
+        try {
+            const payload = formatEventForLangfuse(event);
+            const meta = payload.trace.metadata || {};
+            stats.actualCostUsd += event.cost_usd || 0;
+            stats.baselineCostUsd += Number(meta.baseline_cost_usd || event.cost_usd || 0);
+            stats.costSavedUsd += Number(meta.cost_saved_usd || 0);
+            stats.tokensSaved += Number(meta.tokens_saved || 0);
+            stats.baselineTokens += Number(meta.baseline_tokens || 0);
+            if (event.is_local_call) {
+                stats.localCalls++;
+                stats.localTokens += (event.in_tok || 0) + (event.out_tok || 0);
+            }
+            if (event.api_model && (event.api_in_tok > 0 || event.api_out_tok > 0)) {
+                stats.cloudCalls++;
+                stats.cloudTokens += (event.api_in_tok || 0) + (event.api_out_tok || 0);
+            }
+            if (hasClient) {
+                // Langfuse stamps the ingestion envelope, not the body, and ScoreBody has no
+                // timestamp field. Using new Date() here backdated nothing: it collapsed the entire
+                // backfill onto the moment the sync ran, destroying the time series.
+                const envelopeTs = payload.eventTs ?? payload.trace?.timestamp ?? new Date(event.ts).toISOString();
+                batch.push({
+                    id: crypto.randomUUID(),
+                    type: 'trace-create',
+                    timestamp: envelopeTs,
+                    body: payload.trace
+                });
+                const generations = payload.generations || (payload.generation ? [payload.generation] : []);
+                for (const gen of generations) {
+                    batch.push({
+                        id: crypto.randomUUID(),
+                        type: 'generation-create',
+                        timestamp: envelopeTs,
+                        body: {
+                            ...gen,
+                            traceId: payload.trace.id
+                        }
+                    });
+                }
+                if (payload.scores && Array.isArray(payload.scores)) {
+                    for (const score of payload.scores) {
+                        batch.push({
+                            id: crypto.randomUUID(),
+                            type: 'score-create',
+                            timestamp: envelopeTs,
+                            body: {
+                                ...score,
+                                traceId: payload.trace.id
+                            }
+                        });
+                    }
+                }
+                if (payload.span) {
+                    batch.push({
+                        id: crypto.randomUUID(),
+                        type: 'span-create',
+                        timestamp: envelopeTs,
+                        body: {
+                            ...payload.span,
+                            traceId: payload.trace.id
+                        }
+                    });
+                }
+                batchCount++;
+                batchLastRowid = event.ledger_rowid;
+                if (batchCount >= BATCH_SIZE && !(await flushBatch())) {
+                    stats.resumeAfter = lastAcceptedRowid;
+                    break;
+                }
+            }
+            else {
+                stats.syncedTraces++;
+            }
+        }
+        catch (err) {
+            stats.errors++;
+            console.error(`\nError syncing event ${event.request_id}:`, err.message || err);
+        }
+    }
+    if (hasClient && stats.resumeAfter === undefined && !(await flushBatch())) {
+        stats.resumeAfter = lastAcceptedRowid;
+    }
+    if (stats.resumeAfter !== undefined) {
+        console.error(`\nStopped: Langfuse refused a batch after ${MAX_ATTEMPTS} attempts. Everything up to ledger rowid ${stats.resumeAfter} was accepted.`);
+        console.error(`Continue with: pnpm run ledger:sync --after ${stats.resumeAfter}`);
+    }
+    const avgRates = computeCycleRateAvg(rows);
+    const totalRates = computeCycleRates(rows);
+    /**
+     * One summary row per provider, rendered as real durations so the reader never has to
+     * convert a decimal fraction of a minute in their head.
+     *
+     * @param id Provider id as used by computeCycleRateAvg / computeCycleRates
+     * @param budgetVar Name of the env var that supplies the denominator
+     */
+    const cycleRow = (id, budgetVar) => {
+        const avgMinutes = avgRates[id];
+        if (avgMinutes === null) {
+            return `n/a (no traffic, or ${budgetVar} unset)`;
+        }
+        return `~${formatDuration(avgMinutes * 60)} per prompt · ~${formatDuration(totalRates[id] * 60)} total`;
+    };
+    const claudePlan = CONFIG.RESOLVED_PLAN_CLAUDE;
+    const chatgptPlan = CONFIG.RESOLVED_PLAN_CHATGPT;
+    const geminiPlan = CONFIG.RESOLVED_PLAN_GEMINI;
+    if (!dryRun) {
+        process.stdout.write(`\rProgress: ${stats.syncedTraces}/${rows.length} traces synced.\n\n`);
+    }
+    else {
+        console.log();
+    }
+    console.log('--- Sync Summary Table ---');
+    console.table([
+        { Metric: 'Total Events in SQLite', Value: stats.totalEvents },
+        { Metric: 'Traces Processed', Value: stats.syncedTraces },
+        { Metric: 'Local SLM Calls ($0.00)', Value: stats.localCalls },
+        { Metric: 'Local Tokens Processed', Value: stats.localTokens.toLocaleString() },
+        { Metric: 'Cloud API Calls', Value: stats.cloudCalls },
+        { Metric: 'Cloud Tokens Billed', Value: stats.cloudTokens.toLocaleString() },
+        { Metric: 'Baseline Estimated Cost', Value: `$${stats.baselineCostUsd.toFixed(4)}` },
+        { Metric: 'Actual Cost Incurred', Value: `$${stats.actualCostUsd.toFixed(4)}` },
+        { Metric: 'Net Dollars Saved', Value: `$${stats.costSavedUsd.toFixed(4)}` },
+        { Metric: 'Net Tokens Saved', Value: stats.tokensSaved.toLocaleString() },
+        { Metric: 'Sync Errors', Value: stats.errors },
+        { Metric: `Window Time Saved (ChatGPT ${chatgptPlan.windowMinutes}m window)`, Value: cycleRow('chatgpt', 'CHATGPT_WINDOW_BUDGET') },
+        { Metric: `Window Time Saved (Claude ${claudePlan.windowMinutes}m window)`, Value: cycleRow('claude', 'CLAUDE_WINDOW_BUDGET') },
+        { Metric: `Window Time Saved (Gemini ${geminiPlan.windowMinutes}m window)`, Value: cycleRow('gemini', 'GEMINI_WINDOW_BUDGET') },
+    ]);
+    console.log('Window time saved is an estimate within a margin of error: providers do not publish their window limits, so the *_WINDOW_BUDGET values are best guesses.');
+    return stats;
+}
+// Execution entry point
+const isDirectCall = process.argv[1] && (process.argv[1].endsWith('sync.ts') ||
+    process.argv[1].endsWith('sync.js'));
+if (isDirectCall) {
+    const args = process.argv.slice(2);
+    const dryRun = args.includes('--dry-run');
+    const limitIdx = args.indexOf('--limit');
+    let limit;
+    if (limitIdx >= 0 && args[limitIdx + 1]) {
+        limit = parseInt(args[limitIdx + 1], 10);
+    }
+    const afterIdx = args.indexOf('--after');
+    const after = afterIdx >= 0 ? Number(args[afterIdx + 1]) : 0;
+    if (!Number.isInteger(after) || after < 0) {
+        console.error('--after takes a ledger rowid (a whole number), as printed by a stopped sync.');
+        process.exit(1);
+    }
+    syncLedgerToLangfuse({ limit, after, dryRun })
+        .then((stats) => {
+        if (stats.resumeAfter !== undefined)
+            process.exit(1);
+        console.log('Sync process complete.');
+        process.exit(0);
+    })
+        .catch((err) => {
+        console.error('Fatal sync error:', err.message || err);
+        process.exit(1);
+    });
+}

package/dist/ledger/verify.js

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Read-only reconciliation of the local ledger against Langfuse.
+ *
+ * For a window of UTC days, prints how many events the ledger holds, how many traces
+ * Langfuse holds (from every writer and from the gate alone), and, per score name, how many
+ * scores the ledger's events produce against how many Langfuse holds. Run it before and
+ * after any repair. It never writes: the ledger is opened read-only (getDb() is not — it
+ * migrates and prunes on open) and only GET requests are sent.
+ *
+ * Usage:
+ *   pnpm run ledger:verify --from 2026-09-20 --to 2026-09-23   (both days included)
+ */
+import Database from 'better-sqlite3';
+import { CONFIG, requireKeys } from '../config.js';
+import { isEntryPoint } from '../utils/entry-point.js';
+import { waitWithBackoff } from '../utils/backoff.js';
+import { formatEventForLangfuse, SLM_GATE_SOURCE_TAG } from './index.js';
+import { RETIRED_SCORE_NAMES } from './sync-config.js';
+/** Hobby projects allow 30 requests a minute; one every 2.1 s stays under it. */
+const REQUEST_SPACING_MS = 2100;
+const MAX_RETRIES = 3;
+/**
+ * Reads `--from YYYY-MM-DD --to YYYY-MM-DD` (both days included, UTC).
+ *
+ * @throws When either date is missing or malformed, or --to is before --from.
+ */
+export function parseWindow(args) {
+    const day = (flag) => {
+        const value = args[args.indexOf(flag) + 1];
+        if (!args.includes(flag) || !/^\d{4}-\d{2}-\d{2}$/.test(value ?? '') || Number.isNaN(Date.parse(`${value}T00:00:00Z`))) {
+            throw new Error(`${flag} YYYY-MM-DD is required. Usage: pnpm run ledger:verify --from 2026-09-20 --to 2026-09-23 (both days included, UTC)`);
+        }
+        return new Date(`${value}T00:00:00Z`);
+    };
+    const from = day('--from');
+    const to = day('--to');
+    if (to < from)
+        throw new Error('--to is before --from.');
+    to.setUTCDate(to.getUTCDate() + 1);
+    return { from: from.toISOString(), to: to.toISOString() };
+}
+/**
+ * Score counts, by name, that the ledger's events produce with this build's formatting —
+ * what a sync of these events would send today.
+ */
+export function expectedScoreCounts(events) {
+    const counts = new Map();
+    for (const event of events) {
+        for (const score of formatEventForLangfuse(event).scores ?? []) {
+            counts.set(score.name, (counts.get(score.name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/** Every score name found on either side, with actual minus expected. Sorted by name. */
+export function scoreDeltas(params) {
+    const names = [...new Set([...params.expected.keys(), ...params.actual.keys()])].sort();
+    return names.map(name => {
+        const expected = params.expected.get(name) ?? 0;
+        const actual = params.actual.get(name) ?? 0;
+        const note = RETIRED_SCORE_NAMES.includes(name) ? 'retired name, safe to ignore'
+            : expected === 0 && actual > 0 ? 'not written by this build'
+                : '';
+        return { name, expected, actual, delta: actual - expected, note };
+    });
+}
+function readLedgerEvents(window) {
+    const db = new Database(CONFIG.LEDGER_PATH, { readonly: true, fileMustExist: true });
+    try {
+        return db.prepare('SELECT * FROM events WHERE ts >= ? AND ts < ? ORDER BY ts').all(window.from, window.to);
+    }
+    finally {
+        db.close();
+    }
+}
+/** One paced GET against Langfuse, retried on 429 and 5xx. Returns null (and says why) on any other failure. */
+async function langfuseGet(pathAndQuery) {
+    const baseUrl = CONFIG.LANGFUSE_HOST.replace(/\/$/, '');
+    const auth = `Basic ${Buffer.from(`${CONFIG.LANGFUSE_PUBLIC_KEY}:${CONFIG.LANGFUSE_SECRET_KEY}`).toString('base64')}`;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        await new Promise(resolve => setTimeout(resolve, REQUEST_SPACING_MS));
+        const res = await fetch(`${baseUrl}${pathAndQuery}`, { headers: { Authorization: auth } });
+        if (res.ok)
+            return res.json();
+        const transient = res.status === 429 || res.status >= 500;
+        if (!transient || attempt === MAX_RETRIES - 1) {
+            console.error(`[verify] GET ${pathAndQuery.split('?')[0]} failed (${res.status}): ${(await res.text().catch(() => '')).slice(0, 300)}`);
+            return null;
+        }
+        await waitWithBackoff(attempt, MAX_RETRIES, `Langfuse ${res.status}`, res.headers.get('retry-after'), 'verify');
+    }
+    return null;
+}
+/** Score counts by name for one score view, from the v2 metrics API. */
+async function langfuseScoreCounts(params) {
+    const query = {
+        view: params.view,
+        dimensions: [{ field: 'name' }],
+        metrics: [{ measure: 'count', aggregation: 'count' }],
+        filters: [],
+        fromTimestamp: params.window.from,
+        toTimestamp: params.window.to,
+    };
+    const body = await langfuseGet(`/api/public/v2/metrics?query=${encodeURIComponent(JSON.stringify(query))}`);
+    if (!body?.data)
+        return null;
+    return new Map(body.data.filter(row => row.name).map(row => [row.name, Number(row.count_count)]));
+}
+/**
+ * Trace count in the window, optionally only traces carrying `tag`.
+ *
+ * The v2 metrics API has no traces view, so this reads the total from the trace list
+ * (limit=1). Langfuse retires that endpoint on Cloud on 2026-11-16; from then this
+ * returns null and the report says the count is unavailable.
+ */
+async function langfuseTraceCount(params) {
+    const query = new URLSearchParams({ limit: '1', fromTimestamp: params.window.from, toTimestamp: params.window.to });
+    if (params.tag)
+        query.set('tags', params.tag);
+    const body = await langfuseGet(`/api/public/traces?${query}`);
+    return typeof body?.meta?.totalItems === 'number' ? body.meta.totalItems : null;
+}
+async function verify(window) {
+    requireKeys(['LANGFUSE_PUBLIC_KEY', 'LANGFUSE_SECRET_KEY', 'LANGFUSE_HOST']);
+    const events = readLedgerEvents(window);
+    const byEnvironment = new Map();
+    for (const e of events)
+        byEnvironment.set(e.environment ?? '(none)', (byEnvironment.get(e.environment ?? '(none)') ?? 0) + 1);
+    console.log('=== SLM Gate: ledger ↔ Langfuse reconciliation (read-only) ===\n');
+    console.log(`Window  : ${window.from} → ${window.to} (end excluded)`);
+    console.log(`Ledger  : ${CONFIG.LEDGER_PATH}`);
+    console.log(`Langfuse: ${CONFIG.LANGFUSE_HOST}\n`);
+    console.log('Querying Langfuse (paced for the 30 requests/minute limit)...\n');
+    const allTraces = await langfuseTraceCount({ window });
+    const gateTaggedTraces = await langfuseTraceCount({ window, tag: SLM_GATE_SOURCE_TAG });
+    const numeric = await langfuseScoreCounts({ view: 'scores-numeric', window });
+    const categorical = await langfuseScoreCounts({ view: 'scores-categorical', window });
+    const show = (n) => n === null ? 'unavailable' : String(n);
+    const diff = (n) => n === null ? '' : `${n - events.length >= 0 ? '+' : ''}${n - events.length}`;
+    // Every gate event writes exactly one 'verified' score and no other writer does, so this
+    // counts the gate's traces even when they predate the source tag.
+    const gateVerified = categorical ? (categorical.get('verified') ?? 0) : null;
+    console.table([
+        { Measure: 'Ledger events', Count: String(events.length), 'Δ vs ledger': '' },
+        ...[...byEnvironment].map(([env, n]) => ({ Measure: `  environment=${env}`, Count: String(n), 'Δ vs ledger': '' })),
+        { Measure: 'Langfuse traces, all writers', Count: show(allTraces), 'Δ vs ledger': diff(allTraces) },
+        { Measure: `Langfuse traces tagged ${SLM_GATE_SOURCE_TAG}`, Count: show(gateTaggedTraces), 'Δ vs ledger': diff(gateTaggedTraces) },
+        { Measure: "Langfuse gate traces (one 'verified' score each)", Count: show(gateVerified), 'Δ vs ledger': diff(gateVerified) },
+        {
+            Measure: 'Langfuse traces from other writers',
+            Count: allTraces === null || gateVerified === null ? 'unavailable' : String(allTraces - gateVerified),
+            'Δ vs ledger': '',
+        },
+    ]);
+    if (!numeric || !categorical) {
+        console.error('Score counts are unavailable; see the errors above.');
+        process.exitCode = 1;
+        return;
+    }
+    const actual = new Map([...numeric, ...categorical]);
+    const rows = scoreDeltas({ expected: expectedScoreCounts(events), actual });
+    console.log('\nScores by name. Expected = what this build produces for the ledger events above.');
+    console.table(rows.map(r => ({
+        'Score name': r.name,
+        Expected: r.expected,
+        Langfuse: r.actual,
+        Δ: r.delta === 0 ? '0' : `${r.delta > 0 ? '+' : ''}${r.delta}`,
+        Note: r.note,
+    })));
+    console.log('Langfuse list endpoints can lag live data by about 10 minutes.');
+}
+if (isEntryPoint(import.meta.url)) {
+    let window;
+    try {
+        window = parseWindow(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    verify(window).catch(err => {
+        console.error('ledger:verify failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}