akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/graph/graph.js

@@ -1,487 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import fs from "node:fs";
-import path from "node:path";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { loadConfig } from "../../core/config/config.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
-import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openExistingDatabase, openIndexDatabase, } from "../../indexer/db/db.js";
-import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
-import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
-import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
-import { withIndexWriterLease } from "../../indexer/index-writer-lock.js";
-import { lookup } from "../../indexer/indexer.js";
-import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
-function resolveGraphStashPath(source) {
-    const sources = resolveSourceEntries(undefined, loadConfig());
-    if (sources.length === 0) {
-        throw new NotFoundError("No stash sources are configured.", "STASH_NOT_FOUND");
-    }
-    if (!source || source === "primary")
-        return sources[0].path;
-    const matched = sources.find((entry) => entry.registryId === source || entry.path === source);
-    if (!matched) {
-        throw new NotFoundError(`Source not found: ${source}`, "SOURCE_NOT_FOUND", "Run `akm list` to see source names.");
-    }
-    return matched.path;
-}
-function loadGraph(source) {
-    const stashPath = resolveGraphStashPath(source);
-    let db;
-    try {
-        db = openExistingDatabase();
-        const snapshot = loadStoredGraphSnapshot(stashPath, db);
-        if (!snapshot) {
-            throw new NotFoundError(`Graph data not found for source ${stashPath}.`, "FILE_NOT_FOUND", "Run the improvement flow that refreshes graph extraction data.");
-        }
-        return {
-            graph: {
-                schemaVersion: snapshot.schemaVersion,
-                generatedAt: snapshot.generatedAt,
-                stashRoot: snapshot.stashPath,
-                files: snapshot.files,
-                entities: snapshot.entities,
-                relations: snapshot.relations,
-                ...(snapshot.quality ? { quality: snapshot.quality } : {}),
-                ...(snapshot.telemetry ? { telemetry: snapshot.telemetry } : {}),
-            },
-            stashPath,
-            graphPath: snapshot.graphPath,
-        };
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
-}
-function countEntitiesByFile(nodes) {
-    const counts = new Map();
-    for (const node of nodes) {
-        const seen = new Set();
-        for (const entity of node.entities) {
-            if (seen.has(entity))
-                continue;
-            seen.add(entity);
-            counts.set(entity, (counts.get(entity) ?? 0) + 1);
-        }
-    }
-    return counts;
-}
-function aggregateEntityStats(nodes) {
-    const stats = new Map();
-    for (const node of nodes) {
-        const seen = new Set();
-        for (const entity of node.entities) {
-            if (seen.has(entity))
-                continue;
-            seen.add(entity);
-            const existing = stats.get(entity);
-            const nodeConf = typeof node.confidence === "number" && Number.isFinite(node.confidence) ? node.confidence : undefined;
-            if (existing) {
-                existing.fileCount += 1;
-                if (nodeConf !== undefined && (existing.confidence === undefined || nodeConf > existing.confidence)) {
-                    existing.confidence = nodeConf;
-                }
-            }
-            else {
-                stats.set(entity, { fileCount: 1, ...(nodeConf !== undefined ? { confidence: nodeConf } : {}) });
-            }
-        }
-    }
-    return stats;
-}
-export function akmGraphSummary(options) {
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    return {
-        schemaVersion: 1,
-        shape: "graph-summary",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        fileCount: graph.files.length,
-        entityCount: Array.isArray(graph.entities) ? graph.entities.length : countEntitiesByFile(graph.files).size,
-        relationCount: Array.isArray(graph.relations)
-            ? graph.relations.length
-            : graph.files.reduce((sum, node) => sum + node.relations.length, 0),
-        ...(graph.quality ? { quality: graph.quality } : {}),
-        ...(graph.telemetry ? { telemetry: graph.telemetry } : {}),
-    };
-}
-export function akmGraphEntities(options) {
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    const limit = options?.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const stats = aggregateEntityStats(graph.files);
-    const entities = [...stats.entries()]
-        .map(([name, info]) => ({
-        name,
-        fileCount: info.fileCount,
-        ...(info.confidence !== undefined ? { confidence: info.confidence } : {}),
-    }))
-        .sort((a, b) => b.fileCount - a.fileCount || a.name.localeCompare(b.name));
-    const sliced = typeof limit === "number" ? entities.slice(0, limit) : entities;
-    return {
-        schemaVersion: 1,
-        shape: "graph-entities",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        total: entities.length,
-        entities: sliced,
-    };
-}
-export function akmGraphRelations(options) {
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    const limit = options?.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const counts = new Map();
-    for (const node of graph.files) {
-        for (const rel of node.relations) {
-            const key = `${rel.from}\u0000${rel.to}\u0000${rel.type ?? ""}`;
-            const relConf = typeof rel.confidence === "number" && Number.isFinite(rel.confidence) ? rel.confidence : undefined;
-            const existing = counts.get(key);
-            if (existing) {
-                existing.count += 1;
-                if (relConf !== undefined && (existing.confidence === undefined || relConf > existing.confidence)) {
-                    existing.confidence = relConf;
-                }
-            }
-            else {
-                counts.set(key, {
-                    from: rel.from,
-                    to: rel.to,
-                    ...(rel.type ? { type: rel.type } : {}),
-                    count: 1,
-                    ...(relConf !== undefined ? { confidence: relConf } : {}),
-                });
-            }
-        }
-    }
-    const relations = [...counts.values()].sort((a, b) => b.count - a.count || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
-    const sliced = typeof limit === "number" ? relations.slice(0, limit) : relations;
-    return {
-        schemaVersion: 1,
-        shape: "graph-relations",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        total: relations.length,
-        relations: sliced,
-    };
-}
-export function akmGraphExport(options) {
-    if (!options.out?.trim()) {
-        throw new UsageError("`akm graph export` requires --out <path>.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const format = options.format ?? "json";
-    if (format !== "json" && format !== "jsonl") {
-        throw new UsageError("--format must be one of: json, jsonl.", "INVALID_FLAG_VALUE");
-    }
-    const { graph, stashPath, graphPath } = loadGraph(options.source);
-    const outPath = path.resolve(options.out);
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    const payload = format === "json"
-        ? `${JSON.stringify(graph, null, 2)}\n`
-        : `${[
-            ...graph.files.flatMap((file) => file.entities.map((entity) => JSON.stringify({ kind: "entity", entity, file: file.path }))),
-            ...graph.files.flatMap((file) => file.relations.map((relation) => JSON.stringify({ kind: "relation", ...relation, file: file.path }))),
-        ].join("\n")}\n`;
-    fs.writeFileSync(outPath, payload, "utf8");
-    return {
-        schemaVersion: 1,
-        shape: "graph-export",
-        stashPath,
-        graphPath,
-        outPath,
-        format,
-        bytes: Buffer.byteLength(payload, "utf8"),
-    };
-}
-export async function akmGraphRelated(options) {
-    const ref = options.ref.trim();
-    if (!ref) {
-        throw new UsageError("`akm graph related` requires <ref>.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const limit = options.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const target = await resolveGraphTarget(ref, options.source);
-    const { graph, stashPath, graphPath } = loadGraph(target.stashPath);
-    let db;
-    const related = (() => {
-        try {
-            db = openExistingDatabase();
-            return listRelatedPathsForFile(stashPath, target.filePath, limit ?? 5, db);
-        }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-    })();
-    return {
-        schemaVersion: 1,
-        shape: "graph-related",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        ref: target.ref,
-        path: target.filePath,
-        total: related.length,
-        related,
-        ...(related.length === 0 ? { tip: "No related graph neighbors were found for this asset." } : {}),
-    };
-}
-function normalizeGraphName(value) {
-    return value.trim().toLowerCase();
-}
-function buildRefByPath(stashRoot, db) {
-    const rows = getEntryRefRowsForStashRoot(db, stashRoot);
-    const map = new Map();
-    for (const row of rows) {
-        if (map.has(row.file_path))
-            continue;
-        try {
-            const entry = JSON.parse(row.entry_json);
-            if (typeof entry.type === "string" && typeof entry.name === "string") {
-                map.set(row.file_path, { ref: `${entry.type}:${entry.name}`, type: entry.type });
-            }
-        }
-        catch {
-            // ignore corrupt entry_json
-        }
-    }
-    return map;
-}
-export function akmGraphEntity(options) {
-    const name = options.name?.trim();
-    if (!name) {
-        throw new UsageError("`akm graph entity` requires <name>.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const limit = options.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const { graph, stashPath, graphPath } = loadGraph(options.source);
-    const target = normalizeGraphName(name);
-    let db;
-    let refByPath;
-    try {
-        db = openExistingDatabase();
-        refByPath = buildRefByPath(stashPath, db);
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
-    const matches = [];
-    for (const node of graph.files) {
-        const found = node.entities.some((entity) => normalizeGraphName(entity) === target);
-        if (!found)
-            continue;
-        const lookup = refByPath.get(node.path);
-        const conf = typeof node.confidence === "number" && Number.isFinite(node.confidence) ? node.confidence : undefined;
-        matches.push({
-            ...(lookup?.ref ? { ref: lookup.ref } : {}),
-            path: node.path,
-            type: node.type,
-            ...(conf !== undefined ? { confidence: conf } : {}),
-        });
-    }
-    matches.sort((a, b) => {
-        const ca = a.confidence ?? 0;
-        const cb = b.confidence ?? 0;
-        if (cb !== ca)
-            return cb - ca;
-        return a.path.localeCompare(b.path);
-    });
-    const sliced = typeof limit === "number" ? matches.slice(0, limit) : matches;
-    return {
-        schemaVersion: 1,
-        shape: "graph-entity",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        entity: name,
-        total: matches.length,
-        matches: sliced,
-    };
-}
-export function akmGraphOrphans(options) {
-    const limit = options?.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    let db;
-    let refByPath;
-    try {
-        db = openExistingDatabase();
-        refByPath = buildRefByPath(stashPath, db);
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
-    const orphans = [];
-    for (const node of graph.files) {
-        if ((node.status ?? (node.entities.length > 0 ? "extracted" : "empty")) === "extracted")
-            continue;
-        const lookup = refByPath.get(node.path);
-        orphans.push({
-            ...(lookup?.ref ? { ref: lookup.ref } : {}),
-            path: node.path,
-            type: node.type,
-            ...(node.status ? { status: node.status } : {}),
-            ...(node.reason ? { reason: node.reason } : {}),
-        });
-    }
-    orphans.sort((a, b) => a.type.localeCompare(b.type) || a.path.localeCompare(b.path));
-    const sliced = typeof limit === "number" ? orphans.slice(0, limit) : orphans;
-    return {
-        schemaVersion: 1,
-        shape: "graph-orphans",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        totalConsidered: graph.files.length,
-        total: orphans.length,
-        orphans: sliced,
-    };
-}
-/**
- * Re-run graph extraction, optionally scoped to specific asset refs.
- *
- * When `refs` is provided, only those files are re-extracted (incremental).
- * When no refs are given, the full eligible set is re-extracted.
- */
-export async function akmGraphUpdate(options) {
-    const config = options.config ?? loadConfig();
-    const sources = resolveSourceEntries(options.stashDir, config);
-    if (sources.length === 0) {
-        throw new NotFoundError("No stash sources are configured.", "STASH_NOT_FOUND");
-    }
-    if (options.source && options.source !== "primary") {
-        const matched = sources.find((s) => s.registryId === options.source || s.path === options.source);
-        if (!matched) {
-            throw new NotFoundError(`Source not found: ${options.source}`, "SOURCE_NOT_FOUND", "Run `akm list` to see source names.");
-        }
-    }
-    const scoped = Array.isArray(options.refs) && options.refs.length > 0;
-    return withIndexWriterLease({ purpose: "graph-update" }, async () => {
-        let candidatePaths;
-        if (scoped && options.refs) {
-            // Resolve each ref to an absolute file path while the writer lease is held
-            // so the scoped graph write sees the same index snapshot it resolved from.
-            const dbPath = getDbPath();
-            let db;
-            const resolvedPaths = new Set();
-            try {
-                db = openIndexDatabase(dbPath);
-                for (const ref of options.refs) {
-                    const trimmed = ref.trim();
-                    if (!trimmed)
-                        continue;
-                    const entryId = findEntryIdByRef(db, trimmed);
-                    if (entryId === undefined) {
-                        warn(`[graph] ref not found in index, skipping: ${trimmed}`);
-                        continue;
-                    }
-                    const row = getEntryById(db, entryId);
-                    if (!row?.filePath) {
-                        warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
-                        continue;
-                    }
-                    resolvedPaths.add(row.filePath);
-                }
-            }
-            finally {
-                if (db)
-                    closeDatabase(db);
-            }
-            if (resolvedPaths.size === 0) {
-                warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
-                return {
-                    shape: "graph-update",
-                    ok: true,
-                    filesExtracted: 0,
-                    entitiesUpserted: 0,
-                    relationsUpserted: 0,
-                    durationMs: 0,
-                    scoped: true,
-                };
-            }
-            candidatePaths = resolvedPaths;
-        }
-        const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
-        const passOptions = candidatePaths ? { candidatePaths } : {};
-        let db;
-        const startMs = Date.now();
-        try {
-            db = openIndexDatabase(getDbPath());
-            const onProgress = (event) => {
-                if (!event.currentPath)
-                    return;
-                const file = path.basename(event.currentPath);
-                warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
-            };
-            const result = await extractionFn({
-                config,
-                sources,
-                signal: undefined,
-                db,
-                reEnrich: false,
-                onProgress,
-                options: passOptions,
-            });
-            const durationMs = Date.now() - startMs;
-            return {
-                shape: "graph-update",
-                ok: true,
-                filesExtracted: result.quality.extractedFiles,
-                entitiesUpserted: result.quality.entityCount,
-                relationsUpserted: result.quality.relationCount,
-                durationMs,
-                scoped,
-            };
-        }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-    });
-}
-async function resolveGraphTarget(ref, source) {
-    const parsedRef = parseAssetRef(ref);
-    const filePath = (await resolveAssetPath(parsedRef, {
-        mode: "index-first",
-        honorOrigin: true,
-    })) ?? (await lookup(parsedRef))?.filePath;
-    if (!filePath) {
-        throw new NotFoundError(`Asset not found for ref: ${ref}`);
-    }
-    const allSources = resolveSourceEntries(undefined, loadConfig());
-    const matchedSource = findSourceForPath(filePath, allSources);
-    const inferredStashPath = matchedSource?.path;
-    const stashPath = source ? resolveGraphStashPath(source) : inferredStashPath;
-    if (!stashPath) {
-        throw new NotFoundError(`Could not determine stash source for ref: ${ref}`, "SOURCE_NOT_FOUND");
-    }
-    if (!filePath.startsWith(path.resolve(stashPath) + path.sep) && path.resolve(filePath) !== path.resolve(stashPath)) {
-        throw new UsageError(`Resolved asset ${ref} is not inside source ${source ?? stashPath}.`, "INVALID_SOURCE_VALUE", "Pass --source for the asset's source, or omit it to infer from the resolved asset path.");
-    }
-    return {
-        ref,
-        parsedRef,
-        filePath,
-        stashPath,
-    };
-}

package/dist/commands/improve/calibration.js

@@ -1,161 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-// ---------------------------------------------------------------------------
-// Reliability computation
-// ---------------------------------------------------------------------------
-/** Number of fixed-width reliability buckets over [0, 1]. */
-export const CALIBRATION_BUCKET_COUNT = 10;
-function roundRate(value) {
-    return Number(value.toFixed(4));
-}
-/**
- * Assign a confidence in [0, 1] to one of {@link CALIBRATION_BUCKET_COUNT}
- * fixed-width buckets. The final bucket is closed on the right so confidence
- * === 1 lands in the top bucket rather than overflowing.
- */
-function bucketIndex(confidence) {
-    const clamped = Math.min(1, Math.max(0, confidence));
-    const idx = Math.floor(clamped * CALIBRATION_BUCKET_COUNT);
-    return Math.min(CALIBRATION_BUCKET_COUNT - 1, idx);
-}
-/**
- * Compute a deterministic calibration summary from a list of acted-on gate
- * decisions. Pure: identical input always yields identical output, with no
- * dependency on wall-clock time or randomness.
- */
-export function summarizeCalibration(samples) {
-    const buckets = [];
-    const bucketCounts = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
-    const bucketAccepted = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
-    const bucketConfSum = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
-    let accepted = 0;
-    let confSum = 0;
-    for (const sample of samples) {
-        const idx = bucketIndex(sample.confidence);
-        bucketCounts[idx] = (bucketCounts[idx] ?? 0) + 1;
-        bucketConfSum[idx] = (bucketConfSum[idx] ?? 0) + sample.confidence;
-        confSum += sample.confidence;
-        if (sample.outcome === "auto-accepted") {
-            accepted += 1;
-            bucketAccepted[idx] = (bucketAccepted[idx] ?? 0) + 1;
-        }
-    }
-    const total = samples.length;
-    const width = 1 / CALIBRATION_BUCKET_COUNT;
-    for (let i = 0; i < CALIBRATION_BUCKET_COUNT; i += 1) {
-        const count = bucketCounts[i] ?? 0;
-        const acc = bucketAccepted[i] ?? 0;
-        buckets.push({
-            lower: roundRate(i * width),
-            upper: roundRate((i + 1) * width),
-            count,
-            accepted: acc,
-            acceptRate: count > 0 ? roundRate(acc / count) : 0,
-            meanConfidence: count > 0 ? roundRate((bucketConfSum[i] ?? 0) / count) : 0,
-        });
-    }
-    const overallAcceptRate = total > 0 ? roundRate(accepted / total) : 0;
-    const meanConfidence = total > 0 ? roundRate(confSum / total) : 0;
-    return {
-        samples: total,
-        accepted,
-        rejected: total - accepted,
-        overallAcceptRate,
-        meanConfidence,
-        calibrationGap: total > 0 ? roundRate(meanConfidence - overallAcceptRate) : 0,
-        buckets,
-    };
-}
-/**
- * Project a list of `gateDecision` records (read from the proposal store) into
- * the acted-on calibration samples within an optional `[since, until)` window.
- *
- * Only `auto-accepted` / `auto-rejected` decisions with a finite confidence in
- * [0, 1] contribute. `deferred` decisions and decisions missing a confidence
- * are excluded (no realized accept/reject signal). The window filter uses each
- * decision's `decidedAt` timestamp; decisions with an unparseable timestamp are
- * kept only when no window is supplied.
- *
- * Exploration-budget promotions (`reason === "exploration-budget"`) are EXCLUDED:
- * they are accepted regardless of confidence, so they carry no reliability signal
- * about the gate threshold. Counting them would inflate the apparent accept-rate
- * and bias the auto-tuner downward — they are exempt from auto-tune by design
- * (WS-4 exploration budget).
- */
-export function gateDecisionsToSamples(decisions, window) {
-    const sinceMs = window?.since ? new Date(window.since).getTime() : undefined;
-    const untilMs = window?.until ? new Date(window.until).getTime() : undefined;
-    const samples = [];
-    for (const decision of decisions) {
-        if (!decision)
-            continue;
-        if (decision.outcome !== "auto-accepted" && decision.outcome !== "auto-rejected")
-            continue;
-        if (decision.reason === "exploration-budget")
-            continue;
-        const confidence = decision.confidence;
-        if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1)
-            continue;
-        if (sinceMs !== undefined || untilMs !== undefined) {
-            const ts = new Date(decision.decidedAt).getTime();
-            if (!Number.isFinite(ts))
-                continue;
-            if (sinceMs !== undefined && ts < sinceMs)
-                continue;
-            if (untilMs !== undefined && ts >= untilMs)
-                continue;
-        }
-        samples.push({ confidence, outcome: decision.outcome });
-    }
-    return samples;
-}
-/**
- * Compute a bounded, opt-in threshold adjustment from a calibration summary.
- * PURE and deterministic — does not mutate config or read the clock. The
- * caller is responsible for persisting `newThreshold` and logging the result.
- *
- * Algorithm (deliberately simple and bounded):
- *   - When `autoTune` is false → no-op (`disabled`).
- *   - When samples < `minSamples` → no-op (`insufficient-samples`).
- *   - Otherwise nudge by at most `maxStep` toward `targetAcceptRate`, then
- *     clamp into `[minThreshold, maxThreshold]`. The step size scales with the
- *     gap from target but is capped, so a single run can never make a large
- *     swing.
- */
-export function computeThresholdAutoTune(currentThreshold, summary, config) {
-    const previousThreshold = Math.round(currentThreshold);
-    const noop = (reason) => ({
-        adjusted: false,
-        previousThreshold,
-        newThreshold: previousThreshold,
-        delta: 0,
-        reason,
-    });
-    if (!config.autoTune)
-        return noop("disabled");
-    if (summary.samples < config.minSamples)
-        return noop("insufficient-samples");
-    const gap = config.targetAcceptRate - summary.overallAcceptRate;
-    // A small dead-band so tiny noise doesn't churn the threshold every run.
-    const DEAD_BAND = 0.01;
-    if (Math.abs(gap) <= DEAD_BAND)
-        return noop("within-target");
-    // gap > 0 ⇒ realized below target ⇒ raise threshold (be stricter).
-    // gap < 0 ⇒ realized above target ⇒ lower threshold (be more permissive).
-    const direction = gap > 0 ? 1 : -1;
-    // Scale the step with the gap magnitude (in points) but cap at maxStep.
-    const desiredMagnitude = Math.min(config.maxStep, Math.max(1, Math.round(Math.abs(gap) * 100)));
-    const proposed = previousThreshold + direction * desiredMagnitude;
-    const clamped = Math.min(config.maxThreshold, Math.max(config.minThreshold, proposed));
-    const delta = clamped - previousThreshold;
-    if (delta === 0)
-        return noop("clamped-at-bound");
-    return {
-        adjusted: true,
-        previousThreshold,
-        newThreshold: clamped,
-        delta,
-        reason: direction > 0 ? "below-target-raise" : "above-target-lower",
-    };
-}