akm-cli 0.9.0-rc.9 → 0.9.0

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

@@ -2,16 +2,21 @@
 // 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/churn detector
+ * R5 — Longitudinal collapse detector
  * (docs/architecture/specs/improve-collapse-churn-detector-design.md).
  *
- * Detects the two measured failure modes of LLM-consolidated memory stores:
+ * 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.
  *
- *   COLLAPSE — repeated merges destroy information: canary retrieval recall
- *     downtrends, distinct-content entropy downtrends, or the store shrinks
- *     while generation counts rise.
- *   CHURN — real accepted-change volume with zero retrieval-visible or
- *     shape-visible movement (LLM budget burned rewriting to no effect).
+ * 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,
@@ -25,6 +30,7 @@
  * @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";
@@ -42,7 +48,6 @@ 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_CHURN_MIN_ACCEPTED = 25;
 export const DEFAULT_RETENTION_DAYS = 365;
 /** Deterministic bigram-diversity sample cap (cost bound at 10k assets). */
 const DIVERSITY_SAMPLE_CAP = 2000;
@@ -117,9 +122,10 @@ function newCanarySetId() {
  * 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
- * `akm improve canary --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.
+ * `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);
@@ -134,11 +140,11 @@ export function ensureCanarySet(stateDb, indexDb, cfg, preloadedEntries) {
     return { canarySetId, canaries: getCanariesBySetId(stateDb, canarySetId) };
 }
 /**
- * Explicit canary re-mint (the ONLY refresh path — `akm improve canary
- * --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.
+ * 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);
@@ -179,26 +185,35 @@ export function normHash(text) {
 }
 /**
  * Score one canary against the live index, merge-following via canonical
- * `xrefs`. Legacy `source_refs` remains readable for assets written before the
- * xref cutover. A hit is the anchor ref itself OR any returned entry whose
+ * `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];
-        // Chunk-8 WI-8.5c: match the stored anchor (SHORT conceptId) and the
-        // canonical `xrefs` provenance (also conceptIds post WI-8.5a) on the
-        // conceptId spelling.
+        // 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 === canary.anchor_ref)
+        if (ref === anchorConceptId)
             return i;
-        if (r.entry.xrefs?.includes(canary.anchor_ref) || r.entry.sourceRefs?.includes(canary.anchor_ref))
+        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.
@@ -272,7 +287,9 @@ export function computeCycleMetrics(stateDb, indexDb, args) {
         distinct_content_ratio: learningTotal === 0 ? 1 : contentHashes.size / learningTotal,
         mean_bigram_diversity: diversityCount === 0 ? 1 : diversitySum / diversityCount,
         over_generation_count: overGeneration,
-        accepted_actions: args.acceptedActions,
+        // 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: "[]",
     };
@@ -312,7 +329,6 @@ export function evaluateCollapseAlerts(history, current, cfg) {
     const windowStart = hist[0];
     const recallDrop = cfg.recallDropThreshold ?? DEFAULT_RECALL_DROP_THRESHOLD;
     const entropyDrop = cfg.entropyDropThreshold ?? DEFAULT_ENTROPY_DROP_THRESHOLD;
-    const churnMin = cfg.churnMinAcceptedActions ?? DEFAULT_CHURN_MIN_ACCEPTED;
     // 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));
@@ -351,20 +367,6 @@ export function evaluateCollapseAlerts(history, current, cfg) {
             },
         });
     }
-    // CHURN — real write volume, zero retrieval- or shape-visible movement.
-    // Flatness is measured against the window MEDIAN (consistent with the
-    // recall rule): endpoint-only comparison would call a window that swung
-    // wildly but happened to land near its start "flat".
-    const acceptedSum = hist.reduce((a, h) => a + h.accepted_actions, 0);
-    const scoreFlat = Math.abs(current.mean_ndcg - median(hist.map((h) => h.mean_ndcg))) < 0.02;
-    const entropyFlat = Math.abs(current.distinct_content_ratio - median(hist.map((h) => h.distinct_content_ratio))) < 0.02;
-    if (acceptedSum >= churnMin && scoreFlat && entropyFlat) {
-        alerts.push({
-            kind: "churn",
-            detail: `${acceptedSum} accepted actions over ${W} cycles with flat canary score and flat entropy — write volume with no retrieval-visible effect`,
-            metrics: { acceptedSum, ndcgDelta: current.mean_ndcg - windowStart.mean_ndcg },
-        });
-    }
     return alerts;
 }
 // ── Orchestrator ─────────────────────────────────────────────────────────────
@@ -392,7 +394,6 @@ export function runCollapseDetector(args) {
                 const row = computeCycleMetrics(stateDb, db, {
                     runId: args.runId,
                     pass: args.pass,
-                    acceptedActions: args.acceptedActions,
                     mergeFloorViolations: args.mergeFloorViolations,
                     cfg,
                     maxGeneration,

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

@@ -22,7 +22,7 @@ export function isConsolidationEligibleMemoryName(name) {
  * consolidate flow already guards against unparseable memories elsewhere).
  *
  * Defends against four observed defect classes (see
- * `memory:akm-improve-critical-review-2026-05-20`):
+ * `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"
@@ -40,25 +40,3 @@ export function isHotCapturedMemory(filePath) {
         return false;
     }
 }
-export function consolidateGuardStatus(filePath) {
-    if (!fs.existsSync(filePath))
-        return "missing";
-    let content;
-    try {
-        content = fs.readFileSync(filePath, "utf8");
-    }
-    catch {
-        return "unparseable";
-    }
-    let parsed;
-    try {
-        parsed = parseFrontmatter(content);
-    }
-    catch {
-        return "unparseable";
-    }
-    const data = parsed.data;
-    if (!data || Object.keys(data).length === 0)
-        return "unparseable";
-    return hasHotCaptureMode(data) ? "hot" : "safe";
-}

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

@@ -56,6 +56,10 @@ export function mergePlans(chunks, knownRefs) {
                         mergeOp = { ...op, secondaries: filteredSecondaries };
                     }
                 }
+                if (mergeOp.secondaries.length > 1) {
+                    warnings.push(`Merge: ${mergeOp.primary} proposed multiple secondaries; retaining one secondary for review.`);
+                    mergeOp = { ...mergeOp, secondaries: mergeOp.secondaries.slice(0, 1) };
+                }
                 // merge wins over delete
                 if (deleteOps.has(mergeOp.primary)) {
                     deleteOps.delete(mergeOp.primary);