akm-cli 0.9.0-beta.11 → 0.9.0-beta.26

package/dist/commands/health.js

@@ -6,12 +6,13 @@ import { ConfigError, UsageError } from "../core/errors.js";
 import { appendEvent, readEvents } from "../core/events.js";
 import { buildTaskRunId, getLoggedRunIds, openLogsDatabase } from "../core/logs-db.js";
 import { getStateDbPathInDataDir } from "../core/paths.js";
-import { listExistingTableNames, openStateDatabase, queryCompletedTaskIntervals, queryImproveRuns, queryTaskHistory, } from "../core/state-db.js";
+import { listExistingTableNames, listProposalGateDecisions, listStateProposals, openStateDatabase, queryCompletedTaskIntervals, queryImproveRuns, queryTaskHistory, } from "../core/state-db.js";
 import { parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
 import { getExecutionLogCandidates } from "../integrations/session-logs/index.js";
 import { LLM_USAGE_EVENT } from "../llm/usage-persist.js";
 import { HEALTH_CHECKS } from "./health/checks.js";
+import { gateDecisionsToSamples, summarizeCalibration } from "./improve/calibration.js";
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
 const IMPROVE_COMPLETED_EVENT = "improve_completed";
 const HEALTH_PROBE_EVENT = "health_probe";
@@ -72,6 +73,7 @@ function createUnknownImproveMetrics() {
             error: 0,
         },
         autoAccept: { promoted: 0, validationFailed: 0 },
+        calibration: summarizeCalibration([]),
         reflectsWithErrorContext: 0,
         coverageGapCount: 0,
         evalCasesWritten: 0,
@@ -155,6 +157,22 @@ function createUnknownImproveMetrics() {
                 graphExtraction: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
             },
         },
+        perfTelemetry: {
+            dedupPoolSize: 0,
+            llmPoolSize: 0,
+            judgedCacheSkipped: 0,
+            embedMs: 0,
+            embedCacheHits: 0,
+            embedCacheMisses: 0,
+            overBudgetRuns: 0,
+            runsWithTelemetry: 0,
+        },
+        coverage: {
+            rate: Number.NaN,
+            eligibleFraction: Number.NaN,
+            acceptedProposals: 0,
+            totalAssets: 0,
+        },
     };
 }
 function toFiniteNumber(value) {
@@ -363,6 +381,21 @@ function projectRunMetrics(result) {
                 }
             }
         }
+        // WS-5: extract perf telemetry from the consolidation envelope.
+        // Pre-WS-5 envelopes lack `perfTelemetry`; be defensive.
+        const perf = consolidation.perfTelemetry;
+        if (perf) {
+            metrics.perfTelemetry.runsWithTelemetry += 1;
+            metrics.perfTelemetry.dedupPoolSize += toFiniteNumber(perf.dedupPoolSize);
+            metrics.perfTelemetry.llmPoolSize += toFiniteNumber(perf.llmPoolSize);
+            metrics.perfTelemetry.judgedCacheSkipped += toFiniteNumber(perf.judgedCacheSkipped);
+            metrics.perfTelemetry.embedMs += toFiniteNumber(perf.embedMs);
+            metrics.perfTelemetry.embedCacheHits += toFiniteNumber(perf.embedCacheHits);
+            metrics.perfTelemetry.embedCacheMisses += toFiniteNumber(perf.embedCacheMisses);
+            const budgetFrac = toFiniteNumber(perf.estimatedBudgetFractionUsed);
+            if (budgetFrac > 1.0)
+                metrics.perfTelemetry.overBudgetRuns += 1;
+        }
     }
     const memoryInference = result.memoryInference;
     if (memoryInference) {
@@ -561,6 +594,18 @@ function mergeImproveMetrics(dst, src) {
     dst.sessionExtraction.proposalsCreated += src.sessionExtraction.proposalsCreated;
     dst.sessionExtraction.warnings += src.sessionExtraction.warnings;
     dst.sessionExtraction.durationMs += src.sessionExtraction.durationMs;
+    // WS-5: merge perf telemetry (additive sums).
+    dst.perfTelemetry.dedupPoolSize += src.perfTelemetry.dedupPoolSize;
+    dst.perfTelemetry.llmPoolSize += src.perfTelemetry.llmPoolSize;
+    dst.perfTelemetry.judgedCacheSkipped += src.perfTelemetry.judgedCacheSkipped;
+    dst.perfTelemetry.embedMs += src.perfTelemetry.embedMs;
+    dst.perfTelemetry.embedCacheHits += src.perfTelemetry.embedCacheHits;
+    dst.perfTelemetry.embedCacheMisses += src.perfTelemetry.embedCacheMisses;
+    dst.perfTelemetry.overBudgetRuns += src.perfTelemetry.overBudgetRuns;
+    dst.perfTelemetry.runsWithTelemetry += src.perfTelemetry.runsWithTelemetry;
+    // coverage: acceptedProposals is additive; totalAssets is a snapshot (like memorySummary).
+    // totalAssets is intentionally NOT merged here — set from the most recent run in summarizeImproveRuns.
+    dst.coverage.acceptedProposals += src.coverage.acceptedProposals;
 }
 function summarizeImproveRuns(db, since, until) {
     const accum = createUnknownImproveMetrics();
@@ -1051,6 +1096,197 @@ function readLlmUsageAggregate(stateDbPath, since, until) {
     });
     return summarizeLlmUsage(events);
 }
+/**
+ * Read the auto-accept gate calibration summary (#612) over `[since, until)`.
+ * Reads every proposal's `gateDecision` from the open state.db, projects the
+ * acted-on (auto-accepted / auto-rejected) decisions into calibration samples
+ * within the window, and aggregates them deterministically.
+ */
+function readCalibration(db, since, until) {
+    const decisions = listProposalGateDecisions(db);
+    const samples = gateDecisionsToSamples(decisions, { since, ...(until !== undefined ? { until } : {}) });
+    return summarizeCalibration(samples);
+}
+// ── WS-5 Observability helpers ───────────────────────────────────────────────
+/**
+ * Compute WS-5 denominator-fixed coverage metrics.
+ *
+ * `coverage = accepted_proposals / total_assets` (Part V §3).
+ * The denominator is the TOTAL stash size (not the moving eligible set) so
+ * more-inclusive WS-1 ranking cannot spuriously inflate coverage.
+ * `eligibleFraction = eligible_assets / total_assets` is reported separately.
+ *
+ * Proposals are counted only when their `updatedAt` falls within `[since, until)`
+ * so the rate is genuinely window-scoped (matching the JSDoc on the type).
+ *
+ * @param db - Open state.db connection.
+ * @param totalAssets - Total stash asset count (eligible + derived) from the
+ *   most recent run's memorySummary. 0 = denominator unknown, returns NaN rates.
+ * @param eligibleAssets - Eligible (non-derived) asset count from the most recent run.
+ * @param since - Window start (ISO-8601). Proposals accepted before this are excluded.
+ * @param until - Window end (ISO-8601, exclusive). Absent = open-ended (up to now).
+ * @param stashDir - Optional: scope accepted proposals to one stash. Absent = all stashes.
+ */
+function computeDenominatorFixedCoverage(db, totalAssets, eligibleAssets, since, until, stashDir) {
+    let acceptedProposals = 0;
+    try {
+        const proposals = listStateProposals(db, {
+            status: "accepted",
+            ...(stashDir ? { stashDir } : {}),
+        }).filter((p) => {
+            const updatedAt = p.updatedAt ?? "";
+            if (updatedAt < since)
+                return false;
+            if (until !== undefined && updatedAt >= until)
+                return false;
+            return true;
+        });
+        acceptedProposals = proposals.length;
+    }
+    catch {
+        // Fail open: table may not exist on older installs.
+    }
+    if (totalAssets === 0) {
+        return {
+            rate: Number.NaN,
+            eligibleFraction: Number.NaN,
+            acceptedProposals,
+            totalAssets: 0,
+        };
+    }
+    return {
+        rate: roundRate(acceptedProposals / totalAssets),
+        eligibleFraction: roundRate(eligibleAssets / totalAssets),
+        acceptedProposals,
+        totalAssets,
+    };
+}
+/**
+ * Compute WS-5 per-run degradation metrics (Part V §4).
+ *
+ * Health VIEWS only — reads from state.db tables populated by prior improve
+ * runs. Gracefully returns partial data when tables are absent (pre-WS-1/2).
+ *
+ * @param db - Open state.db connection.
+ * @param since - Window start (ISO-8601).
+ * @param until - Window end (ISO-8601).
+ */
+function computeDegradationMetrics(db, since, until) {
+    // (a) Corpus diversity — salience rank distribution of the top-100 assets.
+    // We use the Gini coefficient of retrieval_salience scores as an intra-corpus
+    // diversity proxy. A Gini close to 1 = highly concentrated (entrenched top
+    // assets), Gini near 0 = flat/diverse. This is a single-snapshot metric;
+    // consecutive-run centroid distance requires cross-run history not yet stored.
+    let corpusCentroidDistance = Number.NaN;
+    let entrenchmentFlagged;
+    try {
+        const rows = db
+            .prepare(`SELECT retrieval_salience FROM asset_salience
+         ORDER BY rank_score DESC LIMIT 100`)
+            .all();
+        if (rows.length >= 5) {
+            const vals = rows.map((r) => r.retrieval_salience).sort((a, b) => a - b);
+            const n = vals.length;
+            const sumAbsDiff = vals.reduce((acc, xi, i) => {
+                return acc + vals.slice(i + 1).reduce((a, xj) => a + Math.abs(xi - xj), 0);
+            }, 0);
+            const mean = vals.reduce((a, b) => a + b, 0) / n;
+            // Gini = (sum |xi - xj|) / (2 n^2 mean); 0 = perfect equality, 1 = perfect inequality.
+            const gini = mean > 0 ? sumAbsDiff / (2 * n * n * mean) : 0;
+            // Re-express as a diversity proxy in [0,1]: high gini = low diversity.
+            // corpusCentroidDistance approximation: gini is "distance from uniform".
+            // Note: retrieval_salience values are in [0,1], so the max achievable Gini
+            // with this formula is ~0.5 (when one asset dominates and others are near 0).
+            // Threshold: >0.35 flags entrenchment (robustly above the ~0.1 uniform baseline).
+            corpusCentroidDistance = roundRate(gini);
+            entrenchmentFlagged = gini > 0.35;
+        }
+    }
+    catch {
+        // Table not present (pre-WS-1 install) — leave NaN.
+    }
+    // (b) Merge fidelity — fraction of consolidate accepted proposals in the window
+    // whose ref also has a consolidate skip-reason of "contradict_target_missing"
+    // or an event indicating contradiction. Uses the improve_runs result_json
+    // consolidation.contradicted count as a proxy.
+    // Simple implementation: contradictionRate = total_contradicted / max(1, total_processed)
+    // sourced from the window's consolidation envelope.
+    // (The full "merge proposal → later contradiction" correlation requires cross-run
+    // history; this is the available proxy.)
+    let mergeFidelityContradictionRate = 0;
+    try {
+        const runs = queryImproveRuns(db, since, until);
+        let totalContradicted = 0;
+        let totalProcessed = 0;
+        for (const row of runs) {
+            try {
+                const result = JSON.parse(row.result_json);
+                const cons = result.consolidation;
+                if (cons) {
+                    totalContradicted += toFiniteNumber(cons.contradicted);
+                    totalProcessed += toFiniteNumber(cons.processed);
+                }
+            }
+            catch {
+                // Skip malformed rows.
+            }
+        }
+        if (totalProcessed > 0) {
+            mergeFidelityContradictionRate = roundRate(totalContradicted / totalProcessed);
+        }
+    }
+    catch {
+        // Fail open.
+    }
+    // (c) Generation distribution — fraction of asset_salience rows with
+    // generation >= 2. Generation is NOT currently stored in asset_salience
+    // (it's in frontmatter). We approximate using consecutive_no_ops as a
+    // maturity proxy: assets that have never been no-op'd are "fresh".
+    // TODO(0.10+): store generation in asset_salience for proper tracking.
+    let highGenerationFraction = Number.NaN;
+    try {
+        const genRows = db.prepare("SELECT consecutive_no_ops FROM asset_salience").all();
+        if (genRows.length > 0) {
+            // Use consecutive_no_ops >= 2 as a proxy for "has been through merge cycles".
+            const highGen = genRows.filter((r) => r.consecutive_no_ops >= 2).length;
+            highGenerationFraction = roundRate(highGen / genRows.length);
+        }
+    }
+    catch {
+        // Table not present.
+    }
+    // (d) Oracle spot-check — up to 5 recently accepted proposals in the window.
+    const oracleSpotCheck = [];
+    try {
+        const accepted = listStateProposals(db, { status: "accepted" }).filter((p) => {
+            const updatedAt = p.updatedAt ?? "";
+            return updatedAt >= since && updatedAt < until;
+        });
+        // Sample up to 5: pick evenly spaced (not just the first 5).
+        const step = Math.max(1, Math.floor(accepted.length / 5));
+        for (let i = 0; i < accepted.length && oracleSpotCheck.length < 5; i += step) {
+            const p = accepted[i];
+            if (p) {
+                oracleSpotCheck.push({
+                    proposalId: p.id,
+                    ref: p.ref,
+                    source: p.source ?? "unknown",
+                    acceptedAt: p.updatedAt ?? p.createdAt ?? "",
+                });
+            }
+        }
+    }
+    catch {
+        // Fail open.
+    }
+    return {
+        corpusCentroidDistance,
+        entrenchmentFlagged,
+        mergeFidelityContradictionRate,
+        highGenerationFraction,
+        oracleSpotCheck,
+    };
+}
 function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now(), logsDb) {
     const taskRows = queryTaskHistory(db, { since }).filter((row) => {
         const startMs = new Date(row.started_at).getTime();
@@ -1085,6 +1321,17 @@ function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now(
     const perRunSummaries = buildPerRunSummaries(db, since, until);
     const wallTimes = perRunSummaries.map((run) => run.wallTimeMs).filter((ms) => Number.isFinite(ms) && ms > 0);
     improveSummary.wallTime = computeWallTimeStats(wallTimes, improveSummary.wallTime.byPhase);
+    improveSummary.calibration = readCalibration(db, since, until);
+    // WS-5: Compute denominator-fixed coverage from the most recent run's
+    // memorySummary (totalAssets = eligible + derived — the fixed denominator).
+    const totalAssets = improveSummary.memorySummary.eligible + improveSummary.memorySummary.derived;
+    improveSummary.coverage = computeDenominatorFixedCoverage(db, totalAssets, improveSummary.memorySummary.eligible, since, until);
+    // WS-5: Compute per-run degradation metrics (corpus diversity, merge fidelity,
+    // generation distribution, oracle spot-check). Health VIEWS only.
+    const degradation = computeDegradationMetrics(db, since, until);
+    if (degradation) {
+        improveSummary.degradation = degradation;
+    }
     const metrics = {
         taskFailRate: roundRate(taskFailRate),
         agentFailureRate: roundRate(agentFailureRate),
@@ -1173,6 +1420,35 @@ export function akmHealth(options = {}) {
         const perRunSummaries = buildPerRunSummaries(db, since);
         const wallTimes = perRunSummaries.map((run) => run.wallTimeMs).filter((ms) => Number.isFinite(ms) && ms > 0);
         improveSummary.wallTime = computeWallTimeStats(wallTimes, improveSummary.wallTime.byPhase);
+        improveSummary.calibration = readCalibration(db, since);
+        // WS-5: Compute denominator-fixed coverage and per-run degradation metrics
+        // for the main health path (not just window-compare mode).
+        const until = new Date(now()).toISOString();
+        const totalAssetsMain = improveSummary.memorySummary.eligible + improveSummary.memorySummary.derived;
+        improveSummary.coverage = computeDenominatorFixedCoverage(db, totalAssetsMain, improveSummary.memorySummary.eligible, since, until);
+        const degradationMain = computeDegradationMetrics(db, since, until);
+        if (degradationMain) {
+            improveSummary.degradation = degradationMain;
+        }
+        // WS-2 proxy-adequacy tripwire: surface any outcome_proxy_inverted events
+        // in the health window as an advisory so operators know when the 0.10+
+        // rich in-session signal is no longer deferrable.
+        const proxyInvertedEvents = readEvents({ since, type: "outcome_proxy_inverted" }, { dbPath: stateDbPath }).events;
+        if (proxyInvertedEvents.length > 0) {
+            const lastEvent = proxyInvertedEvents[proxyInvertedEvents.length - 1];
+            const correlation = typeof lastEvent.metadata?.correlation === "number" ? lastEvent.metadata.correlation.toFixed(3) : "unknown";
+            advisories.push({
+                name: "outcome-proxy-adequacy",
+                status: "warn",
+                kind: "deterministic",
+                confidence: "high",
+                message: `WS-2 outcome proxy inverted (${proxyInvertedEvents.length} event(s) in window). ` +
+                    `corr(outcome_score, accepted_change_rate) = ${correlation} < −0.3. ` +
+                    "Popular assets are also the most-needing-improvement assets — " +
+                    "the retrieval-based proxy is inverted. " +
+                    "The 0.10+ rich in-session outcome signal is no longer deferrable. See plan §WS-2.",
+            });
+        }
         let sessionLogEntries = [];
         try {
             const sinceDays = Math.max(0, Math.ceil((now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));

package/dist/commands/improve/calibration.js

@@ -0,0 +1,161 @@
+// 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",
+    };
+}