akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/improve/anti-collapse.js

@@ -0,0 +1,170 @@
+// 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/.
+/**
+ * WS-3b Step 8 — Anti-collapse merge guards.
+ *
+ *   (a) Generation counter: merged.generation = max(sources)+1; refuse merge
+ *       of two assets both above generation N (default 2); merges cite sources.
+ *   (b) Lexical-diversity check: low n-gram diversity ⇒ raise merge threshold.
+ *   (c) Merge-information floor (R5 §4.2): provenance union must not shrink and
+ *       the merged body must retain a minimum fraction of the source tokens.
+ *   (d) Occasional random non-similar cluster in the pool.
+ *
+ * @module anti-collapse
+ */
+/** Default max generation depth before merge is refused. */
+export const DEFAULT_MAX_GENERATION = 2;
+/** Default fraction of pool to fill with random (non-similar) clusters. */
+export const DEFAULT_RANDOM_CLUSTER_FRACTION = 0.05;
+/**
+ * Read the `generation` field from an asset's frontmatter.
+ * Returns 0 when absent (no generation metadata = original asset).
+ */
+export function readAssetGeneration(frontmatterData) {
+    const gen = frontmatterData.generation;
+    if (typeof gen === "number" && Number.isFinite(gen) && gen >= 0) {
+        return Math.floor(gen);
+    }
+    return 0;
+}
+/**
+ * Compute the new generation for a merged asset.
+ * Rule: `merged.generation = max(source generations) + 1`.
+ */
+export function computeMergedGeneration(sourceGenerations) {
+    if (sourceGenerations.length === 0)
+        return 1;
+    return Math.max(...sourceGenerations) + 1;
+}
+/**
+ * Check whether a merge of the given assets should be refused due to the
+ * anti-collapse generation guard.
+ *
+ * Returns `{ refused: true, reason }` when BOTH assets have generation > maxGeneration.
+ * Returns `{ refused: false }` when the merge is allowed.
+ *
+ * @param sourceGenerations - Generation values for all merge participants.
+ * @param config - Anti-collapse config.
+ */
+export function checkGenerationGuard(sourceGenerations, config) {
+    // R5: default ON — only an explicit opt-out disables the guard.
+    if (config.enabled === false)
+        return { refused: false };
+    const maxGen = config.maxGeneration ?? DEFAULT_MAX_GENERATION;
+    const highGenCount = sourceGenerations.filter((g) => g > maxGen).length;
+    if (highGenCount >= 2) {
+        return {
+            refused: true,
+            reason: `Anti-collapse: ${highGenCount} merge participants have generation > ${maxGen} (${sourceGenerations.join(", ")}); refusing to merge over-consolidated assets.`,
+        };
+    }
+    return { refused: false };
+}
+/** Distinct-token retention floor default (R5 §4.2). */
+export const DEFAULT_MIN_SPECIFICITY_RETENTION = 0.6;
+function distinctTokens(text) {
+    // Same lowercase whitespace tokenization computeBigramDiversity uses.
+    return new Set(text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 0));
+}
+/**
+ * A merge must strictly increase information (R5 §4.2):
+ *  1. Provenance: the merged asset's `source_refs` must be a superset of the
+ *     union of all participants' `source_refs` plus the participant refs
+ *     themselves — provenance never shrinks through a merge.
+ *  2. Specificity: distinctTokens(mergedBody) ≥ minSpecificityRetention ×
+ *     |union(distinctTokens(participant bodies))| — a merge that only
+ *     shortens/genericizes fails.
+ *
+ * Pure and deterministic; ADVISORY in v1 (the caller counts violations, it
+ * does not refuse the merge). Returns `passed: true` immediately when the
+ * anti-collapse suite or the floor itself is opted out.
+ */
+export function checkMergeInformationFloor(mergedBody, mergedSourceRefs, participants, config) {
+    if (config.enabled === false || config.mergeInformationFloor === false || participants.length === 0) {
+        return { passed: true, provenanceBefore: 0, provenanceAfter: 0, specificityRetention: 1 };
+    }
+    // 1. Provenance union: participants + everything they already cited.
+    const required = new Set();
+    for (const p of participants) {
+        required.add(p.ref);
+        for (const sr of p.sourceRefs)
+            required.add(sr);
+    }
+    const after = new Set(mergedSourceRefs);
+    const missing = [...required].filter((r) => !after.has(r));
+    // 2. Specificity retention over the union of source tokens.
+    const sourceTokens = new Set();
+    for (const p of participants) {
+        for (const t of distinctTokens(p.body))
+            sourceTokens.add(t);
+    }
+    const mergedTokens = distinctTokens(mergedBody);
+    // Clamped at computation so the pass/fail decision, the reason string, and
+    // the reported field all describe the same value.
+    const specificityRetention = Math.min(1, sourceTokens.size === 0 ? 1 : mergedTokens.size / sourceTokens.size);
+    const minRetention = config.minSpecificityRetention ?? DEFAULT_MIN_SPECIFICITY_RETENTION;
+    const provenanceOk = missing.length === 0;
+    const specificityOk = specificityRetention >= minRetention;
+    const reasons = [];
+    if (!provenanceOk) {
+        reasons.push(`provenance shrank: merged source_refs missing ${missing.length} ref(s) (e.g. ${missing[0]})`);
+    }
+    if (!specificityOk) {
+        reasons.push(`specificity retention ${specificityRetention.toFixed(2)} < ${minRetention} (merge genericized/shortened)`);
+    }
+    return {
+        passed: provenanceOk && specificityOk,
+        provenanceBefore: required.size,
+        provenanceAfter: after.size,
+        specificityRetention,
+        ...(reasons.length > 0 ? { reason: reasons.join("; ") } : {}),
+    };
+}
+/**
+ * Compute the bigram n-gram diversity of a text string.
+ * Returns a value in [0, 1] where 0 = all identical bigrams, 1 = all unique.
+ * Used by the lexical-diversity check to detect correlated-extraction artifacts.
+ */
+export function computeBigramDiversity(text) {
+    const words = text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    if (words.length < 2)
+        return 1; // too short to have bigrams; treat as diverse
+    const total = words.length - 1;
+    const unique = new Set();
+    for (let i = 0; i < total; i++) {
+        unique.add(`${words[i]}\t${words[i + 1]}`);
+    }
+    return unique.size / total;
+}
+/**
+ * Check whether a cluster of memories exhibits suspiciously low lexical diversity.
+ * When true, the cluster is likely a correlated-extraction artifact; the merge
+ * threshold should be raised.
+ *
+ * @param bodies - The stripped body texts of the cluster members.
+ * @param config - Anti-collapse config.
+ * @returns `{ lowDiversity: true, diversity }` when the cluster diversity is
+ *   below the 0.3 threshold; `{ lowDiversity: false }` otherwise.
+ */
+export function checkLexicalDiversity(bodies, config) {
+    // R5: default ON — only an explicit opt-out disables the check.
+    if (config.enabled === false || config.lexicalDiversityCheck === false) {
+        return { lowDiversity: false };
+    }
+    if (bodies.length === 0)
+        return { lowDiversity: false };
+    // Average bigram diversity across all bodies in the cluster.
+    const avg = bodies.reduce((sum, b) => sum + computeBigramDiversity(b), 0) / bodies.length;
+    const DIVERSITY_FLOOR = 0.3;
+    if (avg < DIVERSITY_FLOOR) {
+        return { lowDiversity: true, diversity: avg };
+    }
+    return { lowDiversity: false };
+}

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",
+    };
+}