akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/health/surfaces.js

@@ -1,102 +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/.
-/**
- * The remaining `surfaces` advisory group for `akm health` (meta-review 08).
- * `stash-git-exposure` (08-F1) shipped first in ./stash-exposure.ts; this
- * module adds the other two read-only checks the adjudication approved:
- *
- *   - `binary-config-skew`  — config.json written by a NEWER akm than this binary (F3)
- *   - `egress-endpoints`    — the remote-destination list, for eyeball diff (surfaces 3/9)
- *
- * Every collector is a pure projection over injected paths/config (no
- * process.env reads) and is silent when there is nothing to report, matching
- * the stash-exposure pattern. `egress-endpoints` is the one informational
- * (pass-status) entry: it emits whenever any remote endpoint is configured.
- */
-import { readTextFile } from "../../core/common.js";
-import { CURRENT_CONFIG_VERSION } from "../../core/config/config-schema.js";
-import { compareConfigVersion } from "../../core/config/config-version.js";
-import { formatRegistryUrl } from "../../core/registry-url.js";
-/**
- * `binary-config-skew` (08-F3): warn when config.json carries a configVersion
- * NEWER than (or unorderable against) this binary's CURRENT_CONFIG_VERSION —
- * i.e. a newer/foreign akm wrote the shared config and this install is stale.
- * That is the proven multi-install incident class. Silent for current or older
- * versions and unreadable configs (config loading surfaces its own errors).
- */
-export function collectConfigSkewAdvisory(configPath) {
-    let raw;
-    try {
-        raw = JSON.parse(readTextFile(configPath, "Config file"));
-    }
-    catch {
-        return undefined;
-    }
-    const onDisk = raw.configVersion;
-    const order = compareConfigVersion(onDisk, CURRENT_CONFIG_VERSION);
-    const skewed = order === 1 || (onDisk !== undefined && order === undefined);
-    if (!skewed)
-        return undefined;
-    return {
-        name: "binary-config-skew",
-        kind: "deterministic",
-        status: "warn",
-        confidence: "high",
-        message: `config.json has configVersion ${JSON.stringify(onDisk)} but this binary knows ${CURRENT_CONFIG_VERSION} — ` +
-            "a newer akm wrote the shared config, so this install is stale. Upgrade this install; do not keep a stale " +
-            "binary against the shared config/DBs.",
-        evidence: { onDiskConfigVersion: onDisk, binaryConfigVersion: CURRENT_CONFIG_VERSION },
-    };
-}
-/**
- * `egress-endpoints` (08 surfaces 3/9): the full list of remote destinations
- * akm can talk to under the effective config — registries, remote sources,
- * LLM endpoints, embedding endpoint — as one pass-status informational entry
- * for eyeball diff against expectations. Silent only when nothing remote is
- * configured at all.
- */
-export function collectEgressAdvisory(config) {
-    if (!config)
-        return undefined;
-    const endpoints = [];
-    for (const reg of config.registries ?? []) {
-        if (reg.enabled === false || !reg.url)
-            continue;
-        endpoints.push(`registry ${reg.name ?? "(unnamed)"}: ${formatRegistryUrl(reg.url)}`);
-    }
-    for (const [key, bundle] of Object.entries(config.bundles ?? {})) {
-        if (!bundle)
-            continue;
-        const url = bundle.git ?? bundle.website?.url;
-        if (!url)
-            continue;
-        endpoints.push(`source ${key} (${bundle.git ? "git" : "website"}): ${url}`);
-    }
-    for (const [name, engine] of Object.entries(config.engines ?? {})) {
-        if (engine?.kind !== "llm" || !engine.endpoint)
-            continue;
-        endpoints.push(`llm ${name}: ${engine.endpoint}`);
-    }
-    if (config.embedding?.endpoint)
-        endpoints.push(`embedding: ${config.embedding.endpoint}`);
-    if (endpoints.length === 0)
-        return undefined;
-    return {
-        name: "egress-endpoints",
-        kind: "deterministic",
-        status: "pass",
-        confidence: "high",
-        message: `${endpoints.length} remote endpoint(s) in the effective config (registries/sources/LLM/embedding) — ` +
-            "review the evidence list for unexpected destinations.",
-        evidence: { endpoints },
-    };
-}
-/**
- * Aggregate the two collectors into the advisories array shape `akmHealth`
- * consumes. Order is fixed: skew → egress.
- */
-export function collectSurfacesAdvisories(input) {
-    const results = [collectConfigSkewAdvisory(input.configPath), collectEgressAdvisory(input.config)];
-    return results.filter((r) => r !== undefined);
-}

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

@@ -1,83 +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/.
-/**
- * WS-3b Step 8 — Anti-collapse merge guards.
- *
- *   (a) Generation counter: merged.generation = max(sources)+1; merges cite
- *       sources. `over_generation_count` (collapse-detector.ts) tracks assets
- *       above the generation threshold as an advisory metric only — there is
- *       no merge-refusal path wired in.
- *   (b) Lexical-diversity check: low n-gram diversity ⇒ raise merge threshold.
- *   (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;
-}
-/**
- * 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/collapse-detector.js

@@ -1,432 +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/.
-/**
- * R5 — Longitudinal collapse detector
- * (docs/architecture/specs/improve-collapse-churn-detector-design.md).
- *
- * Detects the measured collapse failure mode of LLM-consolidated memory
- * stores: repeated merges destroy information — canary retrieval recall
- * downtrends, distinct-content entropy downtrends, or the store shrinks
- * while generation counts rise.
- *
- * The CHURN alert class described in the design doc was removed: production
- * never threaded a real accepted-change-volume signal in (the value was a
- * hardcoded 0 from the 0.9.0 confidence-gate deletion onward), so the alert
- * could never fire. See the design doc's status note for the removal
- * rationale. `improve_cycle_metrics.accepted_actions` stays in the schema and
- * is written as 0 because deployed `state.db` files already contain it and
- * removing it would be a destructive schema change.
- *
- * Hard invariants: deterministic only (FTS BM25 + hashing — never an LLM,
- * never an embedding model); bounded storage (< 2 KB per qualifying cycle,
- * 365-day retention); fail-open (an error warns and skips, never breaks an
- * improve run); runs only on cycles where consolidate did work.
- *
- * Observe-only in v1: alerts land in `improve_cycle_metrics.alerts_json`, the
- * events log (`collapse_detector_alert`), and the `akm health` advisory —
- * nothing is ever blocked.
- *
- * @module collapse-detector
- */
-import { randomBytes } from "node:crypto";
-import { parseBundleRef } from "../../core/asset/asset-ref.js";
-import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
-import { getImproveProcessConfig } from "../../core/config/config.js";
-import { appendEvent } from "../../core/events.js";
-import { withStateDb } from "../../core/state-db.js";
-import { warn } from "../../core/warn.js";
-import { deactivateCanarySet, getActiveCanaries, getCanariesBySetId, insertCanaries, insertCycleMetrics, listActiveCanarySetIds, queryRecentCycleMetrics, } from "../../storage/repositories/canaries-repository.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
-import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
-import { searchFts } from "../../storage/repositories/index-fts-repository.js";
-import { computeBigramDiversity, DEFAULT_MAX_GENERATION } from "./anti-collapse.js";
-import { getAllRankScores } from "./salience.js";
-// ── Defaults (mirrored in config-schema.ts ImproveCollapseDetectorSchema) ────
-export const DEFAULT_CANARY_COUNT = 40; // owner-approved 30–50 range
-export const DEFAULT_CANARY_K = 10;
-export const DEFAULT_WINDOW_CYCLES = 5;
-export const DEFAULT_RECALL_DROP_THRESHOLD = 0.15;
-export const DEFAULT_ENTROPY_DROP_THRESHOLD = 0.05;
-export const DEFAULT_RETENTION_DAYS = 365;
-/** Deterministic bigram-diversity sample cap (cost bound at 10k assets). */
-const DIVERSITY_SAMPLE_CAP = 2000;
-/**
- * Minimum merge-floor violations in one cycle before the advisory alert fires.
- * The specificity floor is deliberately strict (Phase-1 tuning pending), so a
- * couple of borderline merges per cycle must not flip `akm health` to warn —
- * that alert fatigue would drown the real collapse signals.
- */
-const MERGE_FLOOR_ALERT_MIN = 3;
-/** The learning-store types the detector measures. */
-const LEARNING_TYPES = new Set(["memory", "lesson", "knowledge"]);
-// ── Canary set ────────────────────────────────────────────────────────────────
-/** Deterministic query string for one anchor entry: name tokens + top tags + description head. */
-function buildCanaryQuery(entry) {
-    const nameTokens = entry.entry.name.split(/[-_/.]+/).filter((t) => t.length > 1);
-    const tags = (entry.entry.tags ?? []).slice(0, 3);
-    const descriptionHead = (entry.entry.description ?? "").split(/\s+/).slice(0, 6);
-    const parts = [...nameTokens, ...tags, ...descriptionHead].filter((t) => t.length > 0);
-    return [...new Set(parts)].join(" ");
-}
-/** Build the mint candidate list (deterministic given index + salience tables). */
-function buildMintList(stateDb, entries, cfg) {
-    const canaryCount = cfg.canaryCount ?? DEFAULT_CANARY_COUNT;
-    const rankScores = getAllRankScores(stateDb);
-    // Chunk-8 WI-8.5c: the canary anchor + salience correlation both key on the
-    // SHORT conceptId (`<stash-subdir>/<name>`, D-R2) — the same spelling the
-    // improve candidate refs and content xrefs now carry (post WI-8.5a).
-    const candidates = entries
-        .filter((e) => LEARNING_TYPES.has(e.entry.type))
-        .map((e) => {
-        const ref = conceptIdFromTypeName(e.entry.type, e.entry.name);
-        return { e, ref, score: rankScores.get(ref) ?? 0 };
-    })
-        .sort((a, b) => b.score - a.score || (a.ref < b.ref ? -1 : 1));
-    // Type-stratified top slice: ⅓ per learning type, backfill from global order.
-    const perType = Math.ceil(canaryCount / 3);
-    const picked = new Map();
-    for (const type of LEARNING_TYPES) {
-        let taken = 0;
-        for (const c of candidates) {
-            if (taken >= perType || picked.size >= canaryCount)
-                break;
-            if (c.e.entry.type === type && !picked.has(c.ref)) {
-                picked.set(c.ref, c);
-                taken++;
-            }
-        }
-    }
-    for (const c of candidates) {
-        if (picked.size >= canaryCount)
-            break;
-        if (!picked.has(c.ref))
-            picked.set(c.ref, c);
-    }
-    return [...picked.values()]
-        .map((c) => ({ anchorRef: c.ref, query: buildCanaryQuery(c.e) }))
-        .filter((c) => c.query.length > 0);
-}
-/** Collision-safe mint token (same-millisecond mints happen in tests + concurrent runs). */
-function newCanarySetId() {
-    return `canary-${Date.now().toString(36)}-${randomBytes(2).toString("hex")}`;
-}
-/**
- * Mint (or return) the active canary set. Deterministic given the index +
- * salience tables: rank the three learning types by `asset_salience.rank_score`
- * (fallback 0, tie-broken by ref), take a type-stratified top slice
- * (⅓ per type, backfilled from the global ranking when a type is short).
- *
- * Returns `null` when the index has no mintable learning entries — a cycle
- * with no canary set is NOT recorded (a fresh unused set id every cycle would
- * mean the trend window never fills and recall reads as a fake 0).
- *
- * NEVER auto-refreshes: once minted the set is frozen until an explicit
- * `bun scripts/refresh-canary-set.ts --refresh` — silent re-baselining is how
- * a slow collapse hides. Rows are read back BY OUR OWN set id (never "newest
- * active") so a concurrent mint in another process cannot relabel this run's
- * metrics.
- */
-export function ensureCanarySet(stateDb, indexDb, cfg, preloadedEntries) {
-    const existing = getActiveCanaries(stateDb);
-    if (existing.length > 0) {
-        return { canarySetId: existing[0].canary_set_id, canaries: existing };
-    }
-    const minted = buildMintList(stateDb, preloadedEntries ?? getAllEntries(indexDb), cfg);
-    if (minted.length === 0)
-        return null;
-    const canarySetId = newCanarySetId();
-    insertCanaries(stateDb, canarySetId, minted);
-    return { canarySetId, canaries: getCanariesBySetId(stateDb, canarySetId) };
-}
-/**
- * Explicit canary re-mint (the ONLY refresh path —
- * `bun scripts/refresh-canary-set.ts --refresh`). Mint-first, deactivate-after:
- * when the index is empty or unreadable the current baseline is left untouched
- * instead of destroyed. Deactivates ALL other active sets (not just the
- * newest) so stragglers from an interrupted refresh can never resurrect.
- */
-export function refreshCanarySet(stateDb, indexDb, cfg) {
-    const minted = buildMintList(stateDb, getAllEntries(indexDb), cfg);
-    if (minted.length === 0)
-        return null; // nothing mintable — keep the old baseline
-    const canarySetId = newCanarySetId();
-    insertCanaries(stateDb, canarySetId, minted);
-    for (const oldSetId of listActiveCanarySetIds(stateDb)) {
-        if (oldSetId !== canarySetId)
-            deactivateCanarySet(stateDb, oldSetId);
-    }
-    return { canarySetId, canaries: getCanariesBySetId(stateDb, canarySetId) };
-}
-// ── Cycle metrics ─────────────────────────────────────────────────────────────
-/**
- * Name-free content fingerprint text for entropy metrics. The indexed
- * search_text EMBEDS the (unique) entry name, which would pin the
- * distinct-content ratio at 1.0 forever; convergence shows up in the
- * description/tags/heading fields, so those are what get hashed. Bounded body
- * content is searchable but deliberately excluded from this fingerprint: the
- * detector measures the structured surface generic merged assets converge on.
- */
-function contentFingerprint(entry) {
-    const parts = [entry.description ?? "", (entry.tags ?? []).join(" "), (entry.toc ?? []).map((h) => h.text).join(" ")];
-    return parts.filter((t) => t.length > 0).join(" ");
-}
-/** FNV-1a 64-bit over lowercased whitespace-collapsed text (distinct-content hashing). */
-export function normHash(text) {
-    const normalized = text.toLowerCase().replace(/\s+/g, " ").trim();
-    let hash = 0xcbf29ce484222325n;
-    const prime = 0x100000001b3n;
-    for (let i = 0; i < normalized.length; i++) {
-        hash ^= BigInt(normalized.charCodeAt(i));
-        hash = (hash * prime) & 0xffffffffffffffffn;
-    }
-    return hash.toString(16);
-}
-/**
- * Score one canary against the live index, merge-following via canonical
- * `xrefs`. A hit is the anchor ref itself or any returned entry whose
- * provenance contains the anchor.
- * Returns the 0-based rank of the first hit, or -1.
- */
-function scoreCanary(indexDb, canary, k) {
-    const results = searchFts(indexDb, canary.query, k);
-    const anchorConceptId = canaryConceptId(canary.anchor_ref);
-    for (let i = 0; i < Math.min(results.length, k); i++) {
-        const r = results[i];
-        // Persisted canaries may be fully qualified after a state migration while
-        // index refs and xrefs remain short conceptIds. Compare identity, not display
-        // spelling, so migration alone cannot collapse recall to zero.
-        const ref = conceptIdFromTypeName(r.entry.type, r.entry.name);
-        if (ref === anchorConceptId)
-            return i;
-        const provenance = r.entry.xrefs ?? [];
-        if (provenance.some((sourceRef) => canaryConceptId(sourceRef) === anchorConceptId))
-            return i;
-    }
-    return -1;
-}
-function canaryConceptId(ref) {
-    try {
-        return parseBundleRef(ref).conceptId;
-    }
-    catch {
-        return ref;
-    }
-}
-/**
- * Compute one qualifying cycle's store-health snapshot. One `entries` scan +
- * `canaryCount` FTS queries; no LLM, no embedding model, no filesystem reads.
- * Returns `null` when no canary set exists AND none is mintable (empty index)
- * — such a cycle is not measurable and must not be recorded.
- */
-export function computeCycleMetrics(stateDb, indexDb, args) {
-    const k = args.cfg.k ?? DEFAULT_CANARY_K;
-    const maxGeneration = args.maxGeneration ?? DEFAULT_MAX_GENERATION;
-    // Single entries scan — shared by the canary mint (if one is needed) and
-    // the store-shape metrics below.
-    const all = getAllEntries(indexDb);
-    const canarySet = ensureCanarySet(stateDb, indexDb, args.cfg, all);
-    if (canarySet === null)
-        return null;
-    const { canarySetId, canaries } = canarySet;
-    // ── Canary retrieval metrics ───────────────────────────────────────────────
-    const ranks = [];
-    let recallSum = 0;
-    let ndcgSum = 0;
-    let mrrSum = 0;
-    for (const canary of canaries) {
-        const rank = scoreCanary(indexDb, canary, k);
-        ranks.push([canary.id, rank]);
-        if (rank >= 0) {
-            recallSum += 1;
-            mrrSum += 1 / (rank + 1);
-            // Single-relevant nDCG@k closed form: ideal DCG is 1, so the score is
-            // just the discount at the hit rank.
-            ndcgSum += 1 / Math.log2(rank + 2);
-        }
-    }
-    const n = Math.max(1, canaries.length);
-    // ── Store-shape metrics (same single entries scan) ────────────────────────
-    const byType = new Map();
-    const contentHashes = new Set();
-    let learningTotal = 0;
-    let overGeneration = 0;
-    const learningTexts = [];
-    for (const e of all) {
-        byType.set(e.entry.type, (byType.get(e.entry.type) ?? 0) + 1);
-        if (!LEARNING_TYPES.has(e.entry.type))
-            continue;
-        learningTotal++;
-        const fingerprint = contentFingerprint(e.entry);
-        contentHashes.add(normHash(fingerprint));
-        if ((e.entry.generation ?? 0) > maxGeneration)
-            overGeneration++;
-        learningTexts.push({ key: e.itemRef, text: fingerprint });
-    }
-    // Deterministic diversity sample: sort by item ref, take every ⌈N/cap⌉-th row.
-    learningTexts.sort((a, b) => (a.key < b.key ? -1 : 1));
-    const step = Math.max(1, Math.ceil(learningTexts.length / DIVERSITY_SAMPLE_CAP));
-    let diversitySum = 0;
-    let diversityCount = 0;
-    for (let i = 0; i < learningTexts.length; i += step) {
-        diversitySum += computeBigramDiversity(learningTexts[i].text);
-        diversityCount++;
-    }
-    return {
-        run_id: args.runId,
-        ts: (args.now ?? new Date()).toISOString(),
-        pass: args.pass,
-        canary_set_id: canarySetId,
-        mean_recall: recallSum / n,
-        mean_ndcg: ndcgSum / n,
-        mean_mrr: mrrSum / n,
-        canary_ranks_json: JSON.stringify(ranks),
-        store_total: learningTotal,
-        store_by_type_json: JSON.stringify(Object.fromEntries([...byType.entries()].sort())),
-        distinct_content_ratio: learningTotal === 0 ? 1 : contentHashes.size / learningTotal,
-        mean_bigram_diversity: diversityCount === 0 ? 1 : diversitySum / diversityCount,
-        over_generation_count: overGeneration,
-        // Always 0 — the CHURN alert this fed was removed. The column is NOT NULL
-        // in a released migration body, so it is written rather than dropped.
-        accepted_actions: 0,
-        merge_floor_violations: args.mergeFloorViolations,
-        alerts_json: "[]",
-    };
-}
-// ── Alert evaluation (pure) ───────────────────────────────────────────────────
-function median(values) {
-    if (values.length === 0)
-        return Number.NaN;
-    const sorted = [...values].sort((a, b) => a - b);
-    const mid = Math.floor(sorted.length / 2);
-    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
-}
-/**
- * Evaluate the §1 alert definitions. PURE — history rows (oldest-first, NOT
- * including `current`) plus the current row in, alerts out. A window shorter
- * than `windowCycles` never fires (no baseline yet); the merge-floor advisory
- * is per-cycle and fires regardless of window depth.
- */
-export function evaluateCollapseAlerts(history, current, cfg) {
-    const alerts = [];
-    // MERGE-FLOOR advisory: per-cycle, window-independent. Gated on a minimum
-    // count — the specificity floor is deliberately strict pre-tuning, and one
-    // or two borderline merges per cycle must not generate alert fatigue.
-    if (current.merge_floor_violations >= MERGE_FLOOR_ALERT_MIN) {
-        alerts.push({
-            kind: "merge-floor",
-            detail: `${current.merge_floor_violations} merge(s) failed the information floor this cycle (provenance shrank or specificity below threshold)`,
-            metrics: { mergeFloorViolations: current.merge_floor_violations },
-        });
-    }
-    const W = cfg.windowCycles ?? DEFAULT_WINDOW_CYCLES;
-    const hist = history.slice(-W);
-    if (hist.length < W)
-        return alerts; // no baseline yet
-    // Window is non-empty here: `windowCycles` is schema-bounded to ≥2 (default 5),
-    // so `hist.length >= W >= 2`. `windowStart` is the oldest row in the window.
-    const windowStart = hist[0];
-    const recallDrop = cfg.recallDropThreshold ?? DEFAULT_RECALL_DROP_THRESHOLD;
-    const entropyDrop = cfg.entropyDropThreshold ?? DEFAULT_ENTROPY_DROP_THRESHOLD;
-    // COLLAPSE 1 — canary recall drop vs window median (median, not previous
-    // cycle, so one noisy cycle can neither fire nor mask the alert).
-    const medianRecall = median(hist.map((h) => h.mean_recall));
-    if (current.mean_recall <= medianRecall - recallDrop) {
-        alerts.push({
-            kind: "collapse-recall",
-            detail: `mean canary recall ${current.mean_recall.toFixed(3)} dropped ≥${recallDrop} below the ${W}-cycle median ${medianRecall.toFixed(3)}`,
-            metrics: { currentRecall: current.mean_recall, medianRecall, threshold: recallDrop },
-        });
-    }
-    // COLLAPSE 2 — monotonic distinct-content-ratio decline over the window.
-    const series = [...hist.map((h) => h.distinct_content_ratio), current.distinct_content_ratio];
-    const monotonicNonIncreasing = series.every((v, i) => i === 0 || v <= series[i - 1]);
-    const totalDecline = windowStart.distinct_content_ratio - current.distinct_content_ratio;
-    if (monotonicNonIncreasing && totalDecline >= entropyDrop) {
-        alerts.push({
-            kind: "collapse-entropy",
-            detail: `distinct-content ratio declined monotonically by ${totalDecline.toFixed(3)} (≥${entropyDrop}) over ${W} cycles — store content is converging`,
-            metrics: {
-                windowStart: windowStart.distinct_content_ratio,
-                current: current.distinct_content_ratio,
-                decline: totalDecline,
-            },
-        });
-    }
-    // COLLAPSE 3 — store shrinking BECAUSE of re-merging (not deletion hygiene).
-    const maxStore = Math.max(...hist.map((h) => h.store_total));
-    if (current.store_total < 0.8 * maxStore && current.over_generation_count > windowStart.over_generation_count) {
-        alerts.push({
-            kind: "collapse-shrink",
-            detail: `store shrank >20% (${current.store_total} vs window max ${maxStore}) while over-generation count rose (${windowStart.over_generation_count} → ${current.over_generation_count})`,
-            metrics: {
-                storeTotal: current.store_total,
-                windowMax: maxStore,
-                overGeneration: current.over_generation_count,
-            },
-        });
-    }
-    return alerts;
-}
-// ── Orchestrator ─────────────────────────────────────────────────────────────
-/**
- * Run the detector for one qualifying cycle: ensure canaries → compute →
- * evaluate against stored history → persist the row → append one
- * `collapse_detector_alert` event per fired alert. FAIL-OPEN: any error warns
- * and returns undefined — an improve run is never broken by its own
- * instrumentation.
- */
-export function runCollapseDetector(args) {
-    const cfg = args.config.improve?.collapseDetector ?? {};
-    if (cfg.enabled === false)
-        return undefined;
-    try {
-        let indexDb;
-        try {
-            indexDb = openExistingDatabase(args.indexDbPath);
-            const db = indexDb;
-            // Over-generation threshold mirrors the guard actually in effect —
-            // reading the same config key keeps the two aligned when tuned.
-            const antiCollapse = getImproveProcessConfig("consolidate", args.improveProfile)?.antiCollapse;
-            const maxGeneration = antiCollapse?.maxGeneration ?? DEFAULT_MAX_GENERATION;
-            return withStateDb((stateDb) => {
-                const row = computeCycleMetrics(stateDb, db, {
-                    runId: args.runId,
-                    pass: args.pass,
-                    mergeFloorViolations: args.mergeFloorViolations,
-                    cfg,
-                    maxGeneration,
-                });
-                if (row === null)
-                    return undefined; // empty index — nothing to measure
-                const windowCycles = cfg.windowCycles ?? DEFAULT_WINDOW_CYCLES;
-                const history = queryRecentCycleMetrics(stateDb, row.canary_set_id, windowCycles);
-                const alerts = evaluateCollapseAlerts(history, row, cfg);
-                row.alerts_json = JSON.stringify(alerts.map((a) => a.kind));
-                insertCycleMetrics(stateDb, row);
-                for (const alert of alerts) {
-                    appendEvent({
-                        eventType: "collapse_detector_alert",
-                        ref: undefined,
-                        metadata: {
-                            kind: alert.kind,
-                            detail: alert.detail,
-                            metrics: alert.metrics,
-                            canarySetId: row.canary_set_id,
-                            runId: args.runId,
-                        },
-                    }, args.eventsCtx);
-                }
-                return row;
-            }, { path: args.eventsCtx?.dbPath, borrowed: args.eventsCtx?.db });
-        }
-        finally {
-            if (indexDb)
-                closeDatabase(indexDb);
-        }
-    }
-    catch (err) {
-        warn(`[collapse-detector] skipped (fail-open): ${err instanceof Error ? err.message : String(err)}`);
-        return undefined;
-    }
-}

package/dist/commands/improve/consolidate/eligibility.js

@@ -1,48 +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/.
-// Eligibility / safety predicates for consolidate: "may we touch this memory?"
-// One reason to change — the policy for what consolidate is allowed to act on.
-import fs from "node:fs";
-import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
-import { hasHotCaptureMode } from "../../proposal/validators/proposal-quality-validators.js";
-export function isConsolidationEligibleMemoryName(name) {
-    return !name.endsWith(".derived");
-}
-/**
- * Returns true when the memory file has `captureMode: hot` in its frontmatter.
- *
- * Hot memories are USER-EXPLICIT (written via `akm remember` on the hot path).
- * The consolidate LLM is forbidden from deleting or auto-merging them — the
- * user wrote them on purpose and only the user can decide to retire them.
- *
- * Reads the file once per check; consolidate runs against ~10 memories per
- * chunk so the IO cost is trivial. Returns false on any read/parse error
- * (fail-safe: an unreadable or unparseable file is treated as HOT — protected
- * — because a deletion shield must not fail open; a missing file is not-hot).
- *
- * Defends against four observed defect classes (see
- * `memories/akm-improve-critical-review-2026-05-20`):
- *   - LLM marks a memory contradicted then deletes (dangling contradictedBy)
- *   - LLM merges two unrelated memories sharing a topic keyword
- *   - LLM judges a recent durable design memo as "redundant"
- *   - Cascade deletes (LLM uses ref:X as `contradictedBy` for ref:Y then deletes both)
- */
-export function isHotCapturedMemory(filePath) {
-    if (!fs.existsSync(filePath))
-        return false;
-    try {
-        const content = fs.readFileSync(filePath, "utf8");
-        const parsed = parseFrontmatter(content);
-        return hasHotCaptureMode(parsed.data);
-    }
-    catch {
-        // Fail CLOSED. This predicate is a deletion shield: "hot" memories are
-        // protected from consolidate's merge/delete. Returning false on a read or
-        // parse failure marked exactly the memories we could not inspect as fair
-        // game — the one direction a protection check must never fail. A missing
-        // file stays false (nothing to protect); an unreadable one is protected
-        // until someone can actually read it.
-        return true;
-    }
-}