akm-cli 0.9.0-beta.52 → 0.9.0-beta.54

package/dist/commands/health.js

@@ -2,17 +2,29 @@
 // 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 { loadConfig } from "../core/config/config.js";
 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, listProposalGateDecisions, listStateProposals, openStateDatabase, queryCompletedTaskIntervals, queryImproveRuns, queryTaskHistory, } from "../core/state-db.js";
+import { getLatestCycleMetrics, 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";
+/**
+ * Lanes ratified as ENRICHMENT-ONLY: they may propose edits to existing
+ * assets (metadata, relations, content refresh) but must not mint new ones.
+ * New-asset generation belongs to the signal-gated minting lanes
+ * (extract/distill/memory-inference/recombine).
+ */
+export const ENRICHMENT_LANES = ["proactive", "high-salience", "high-retrieval", "signal-delta"];
+/** Minted share of enrichment-lane accepts that triggers a WARN advisory. */
+export const ENRICHMENT_MINTED_WARN_SHARE = 0.05;
+/** Minted share of enrichment-lane accepts that triggers a FAIL advisory. */
+export const ENRICHMENT_MINTED_FAIL_SHARE = 0.15;
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
 const IMPROVE_COMPLETED_EVENT = "improve_completed";
 const HEALTH_PROBE_EVENT = "health_probe";
@@ -172,6 +184,8 @@ function createUnknownImproveMetrics() {
             rate: Number.NaN,
             eligibleFraction: Number.NaN,
             acceptedProposals: 0,
+            distinctRefs: 0,
+            churnRatio: Number.NaN,
             totalAssets: 0,
         },
     };
@@ -1133,6 +1147,7 @@ function readCalibration(db, since, until) {
  */
 function computeDenominatorFixedCoverage(db, totalAssets, eligibleAssets, since, until, stashDir) {
     let acceptedProposals = 0;
+    let distinctRefs = 0;
     try {
         const proposals = listStateProposals(db, {
             status: "accepted",
@@ -1146,25 +1161,91 @@ function computeDenominatorFixedCoverage(db, totalAssets, eligibleAssets, since,
             return true;
         });
         acceptedProposals = proposals.length;
+        // Coverage counts DISTINCT refs: N accepted rewrites of one asset are
+        // churn, not coverage. The raw proposal count is kept alongside so the
+        // churn ratio (proposals ÷ distinct refs) stays visible.
+        distinctRefs = new Set(proposals.map((p) => p.ref)).size;
     }
     catch {
         // Fail open: table may not exist on older installs.
     }
+    const churnRatio = distinctRefs > 0 ? roundRate(acceptedProposals / distinctRefs) : Number.NaN;
     if (totalAssets === 0) {
         return {
             rate: Number.NaN,
             eligibleFraction: Number.NaN,
             acceptedProposals,
+            distinctRefs,
+            churnRatio,
             totalAssets: 0,
         };
     }
     return {
-        rate: roundRate(acceptedProposals / totalAssets),
+        rate: roundRate(distinctRefs / totalAssets),
         eligibleFraction: roundRate(eligibleAssets / totalAssets),
         acceptedProposals,
+        distinctRefs,
+        churnRatio,
         totalAssets,
     };
 }
+/**
+ * Compute the enrichment-vs-minting rollup over the window's accepted,
+ * lane-attributed proposals (reporting-only; see {@link EnrichmentMintingRollup}).
+ *
+ * SQL-side `json_extract` keeps the (potentially large) `backupContent` blobs
+ * out of process memory. Pre-Phase-6C rows without an `eligibilitySource`
+ * cannot be lane-classified and are excluded. Fails open (undefined) when the
+ * proposals table is absent.
+ */
+export function computeEnrichmentMintingRollup(db, since, until) {
+    try {
+        const rows = db
+            .prepare(`SELECT
+           json_extract(metadata_json, '$.eligibilitySource') AS lane,
+           CASE WHEN json_extract(metadata_json, '$.backupContent') IS NULL THEN 1 ELSE 0 END AS is_minted,
+           COUNT(*) AS cnt
+         FROM proposals
+         WHERE status = 'accepted'
+           AND updated_at >= ?
+           AND (? IS NULL OR updated_at < ?)
+           AND json_extract(metadata_json, '$.eligibilitySource') IS NOT NULL
+           AND json_extract(metadata_json, '$.eligibilitySource') != ''
+         GROUP BY lane, is_minted`)
+            .all(since, until ?? null, until ?? null);
+        if (rows.length === 0)
+            return undefined;
+        const byLane = {};
+        for (const row of rows) {
+            byLane[row.lane] ??= { minted: 0, updated: 0 };
+            const entry = byLane[row.lane];
+            if (row.is_minted === 1)
+                entry.minted += row.cnt;
+            else
+                entry.updated += row.cnt;
+        }
+        let minted = 0;
+        let updated = 0;
+        for (const lane of ENRICHMENT_LANES) {
+            const entry = byLane[lane];
+            if (!entry)
+                continue;
+            minted += entry.minted;
+            updated += entry.updated;
+        }
+        const decided = minted + updated;
+        return {
+            minted,
+            updated,
+            share: decided > 0 ? roundRate(minted / decided) : Number.NaN,
+            byLane,
+        };
+    }
+    catch {
+        // Fail open: proposals table may not exist on older installs.
+        return undefined;
+    }
+}
 /**
  * Compute WS-5 per-run degradation metrics (Part V §4).
  *
@@ -1175,7 +1256,7 @@ function computeDenominatorFixedCoverage(db, totalAssets, eligibleAssets, since,
  * @param since - Window start (ISO-8601).
  * @param until - Window end (ISO-8601).
  */
-function computeDegradationMetrics(db, since, until) {
+export 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
@@ -1183,6 +1264,7 @@ function computeDegradationMetrics(db, since, until) {
     // consecutive-run centroid distance requires cross-run history not yet stored.
     let corpusCentroidDistance = Number.NaN;
     let entrenchmentFlagged;
+    let salienceUniformityFlagged;
     try {
         const rows = db
             .prepare(`SELECT retrieval_salience FROM asset_salience
@@ -1201,9 +1283,13 @@ function computeDegradationMetrics(db, since, until) {
             // 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).
+            // Two-tailed: >0.35 flags entrenchment (robustly above the ~0.1 uniform
+            // baseline); <0.08 flags uniformity collapse — the distribution no longer
+            // discriminates between assets (live 2026-07 value 0.040 sat unflagged
+            // in this tail under the old one-tailed check).
             corpusCentroidDistance = roundRate(gini);
             entrenchmentFlagged = gini > 0.35;
+            salienceUniformityFlagged = gini < 0.08;
         }
     }
     catch {
@@ -1242,23 +1328,11 @@ function computeDegradationMetrics(db, since, until) {
     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.
-    }
+    // (c) highGenerationFraction was DELETED (meta-review 05 DRIFT-3): it
+    // approximated "LLM-merge generations" from consecutive_no_ops — which counts
+    // the opposite condition (cycles where nothing was changed) — and its own
+    // in-code TODO admitted the proxy. Display-only, never actionable; removed
+    // rather than instrumented.
     // (d) Oracle spot-check — up to 5 recently accepted proposals in the window.
     const oracleSpotCheck = [];
     try {
@@ -1286,8 +1360,8 @@ function computeDegradationMetrics(db, since, until) {
     return {
         corpusCentroidDistance,
         entrenchmentFlagged,
+        salienceUniformityFlagged,
         mergeFidelityContradictionRate,
-        highGenerationFraction,
         oracleSpotCheck,
     };
 }
@@ -1411,6 +1485,18 @@ export function akmHealth(options = {}) {
         const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
         const agentFailureRate = promptRows.length === 0 ? 0 : promptFailures.length / promptRows.length;
         const semanticStatus = readSemanticStatus();
+        // For the embedding-endpoint advisory. Best-effort: an unloadable config
+        // leaves both undefined and the check falls back to its generic message.
+        let semanticSearchMode;
+        let embeddingEndpoint;
+        try {
+            const config = loadConfig();
+            semanticSearchMode = config.semanticSearchMode;
+            embeddingEndpoint = config.embedding?.endpoint;
+        }
+        catch {
+            // fall through with undefined
+        }
         const improveInvoked = readEvents({ since, type: "improve_invoked" }, { dbPath: stateDbPath }).events.length;
         const improveCompletedEvents = readEvents({ since, type: IMPROVE_COMPLETED_EVENT }, { dbPath: stateDbPath }).events;
         const improveSkippedEvents = readEvents({ since, type: "improve_skipped" }, { dbPath: stateDbPath }).events;
@@ -1434,6 +1520,7 @@ export function akmHealth(options = {}) {
         if (degradationMain) {
             improveSummary.degradation = degradationMain;
         }
+        improveSummary.enrichmentMinting = computeEnrichmentMintingRollup(db, since, until);
         // 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.
@@ -1453,6 +1540,117 @@ export function akmHealth(options = {}) {
                     "The 0.10+ rich in-session outcome signal is no longer deferrable. See plan §WS-2.",
             });
         }
+        // Two-tailed companion: a proxy that decays to noise (|corr| < 0.1 at scale)
+        // is as much a failure as an inverted one — it just fails silently.
+        const proxyDeadEvents = readEvents({ since, type: "outcome_proxy_dead" }, { dbPath: stateDbPath, db }).events;
+        if (proxyDeadEvents.length > 0) {
+            const lastEvent = proxyDeadEvents[proxyDeadEvents.length - 1];
+            const correlation = typeof lastEvent.metadata?.correlation === "number" ? lastEvent.metadata.correlation.toFixed(3) : "unknown";
+            advisories.push({
+                name: "outcome-proxy-dead",
+                status: "warn",
+                kind: "deterministic",
+                confidence: "high",
+                message: `WS-2 outcome proxy is DEAD (${proxyDeadEvents.length} event(s) in window). ` +
+                    `|corr(outcome_score, accepted_change_rate)| = ${correlation} < 0.1 at n ≥ 500. ` +
+                    "outcome_score is statistically unrelated to improvement outcomes — " +
+                    "treat outcome-derived rank contributions as noise until a real usage/outcome signal lands.",
+            });
+        }
+        // Salience-distribution collapse: Gini below the uniform baseline means
+        // ranking no longer discriminates between assets.
+        if (improveSummary.degradation?.salienceUniformityFlagged) {
+            advisories.push({
+                name: "salience-uniformity-collapse",
+                status: "warn",
+                kind: "deterministic",
+                confidence: "high",
+                message: `Salience distribution collapsed toward uniform: top-100 retrieval_salience Gini = ` +
+                    `${improveSummary.degradation.corpusCentroidDistance} < 0.08 (uniform baseline ≈ 0.1). ` +
+                    "Ranking currently carries little to no discrimination between assets.",
+            });
+        }
+        // Enrichment-vs-minting policy: enrichment lanes edit existing assets;
+        // a rising minted share means a lane is generating new content instead.
+        const minting = improveSummary.enrichmentMinting;
+        if (minting && Number.isFinite(minting.share) && minting.share > ENRICHMENT_MINTED_WARN_SHARE) {
+            advisories.push({
+                name: "enrichment-lane-minting",
+                status: minting.share > ENRICHMENT_MINTED_FAIL_SHARE ? "fail" : "warn",
+                kind: "deterministic",
+                confidence: "high",
+                message: `Enrichment lanes minted ${minting.minted} NEW asset(s) vs ${minting.updated} update(s) ` +
+                    `(${Math.round(minting.share * 100)}% minted, threshold ${Math.round(ENRICHMENT_MINTED_WARN_SHARE * 100)}%). ` +
+                    "Enrichment-classed lanes (proactive/high-salience/high-retrieval/signal-delta) are ratified to edit " +
+                    "existing assets only — new-asset generation belongs to the signal-gated minting lanes.",
+            });
+        }
+        // Churn: accepted proposals far exceeding distinct touched refs means the
+        // loop is repeatedly rewriting the same assets, not covering the corpus.
+        if (Number.isFinite(improveSummary.coverage.churnRatio) && improveSummary.coverage.churnRatio > 1.5) {
+            advisories.push({
+                name: "improve-churn-ratio",
+                status: "warn",
+                kind: "deterministic",
+                confidence: "high",
+                message: `Improve churn ratio ${improveSummary.coverage.churnRatio} > 1.5: ` +
+                    `${improveSummary.coverage.acceptedProposals} accepted proposals touched only ` +
+                    `${improveSummary.coverage.distinctRefs} distinct assets in the window — ` +
+                    "repeated rewrites of the same refs count as churn, not coverage.",
+            });
+        }
+        // R5 collapse/churn detector: surface any collapse_detector_alert events
+        // in the health window, plus the latest cycle row's headline numbers so
+        // the operator can act without opening the DB. `unknown` when the detector
+        // has never produced a cycle row (no consolidate/recombine work yet).
+        try {
+            // Reuse the already-open state.db handle (readEvents supports a
+            // borrowed connection) — no extra open/migrate/close per health call.
+            const collapseAlertEvents = readEvents({ since, type: "collapse_detector_alert" }, { dbPath: stateDbPath, db }).events;
+            const latestCycle = getLatestCycleMetrics(db);
+            const cycleSummary = latestCycle
+                ? `Latest cycle (${latestCycle.ts}, ${latestCycle.pass}): mean canary recall ${latestCycle.mean_recall.toFixed(3)}, ` +
+                    `distinct-content ratio ${latestCycle.distinct_content_ratio.toFixed(3)}, ` +
+                    `${latestCycle.accepted_actions} accepted action(s).`
+                : "";
+            if (collapseAlertEvents.length > 0) {
+                const kinds = [...new Set(collapseAlertEvents.map((e) => String(e.metadata?.kind ?? "unknown")))];
+                const collapseKinds = kinds.filter((k) => k.startsWith("collapse"));
+                advisories.push({
+                    name: "collapse-churn-detector",
+                    status: "warn",
+                    kind: "deterministic",
+                    // Collapse kinds are measured, not inferred; churn/merge-floor
+                    // volume thresholds are still being tuned (design doc §7).
+                    confidence: collapseKinds.length > 0 ? "high" : "medium",
+                    message: `R5 detector fired ${collapseAlertEvents.length} alert(s) in window (kinds: ${kinds.join(", ")}). ` +
+                        `${cycleSummary} See docs/design/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,
+                });
+            }
+            else if (latestCycle) {
+                advisories.push({
+                    name: "collapse-churn-detector",
+                    status: "pass",
+                    kind: "deterministic",
+                    confidence: "high",
+                    message: `No collapse/churn alerts in window. ${cycleSummary}`,
+                });
+            }
+            else {
+                advisories.push({
+                    name: "collapse-churn-detector",
+                    status: "unknown",
+                    kind: "deterministic",
+                    confidence: "high",
+                    message: "No detector cycle rows yet — the collapse/churn detector runs only on improve cycles " +
+                        "where consolidate/recombine did work (synthesis lanes may be idle).",
+                });
+            }
+        }
+        catch {
+            // Table may predate migration 016 in odd mixed-version setups — advisory
+            // is best-effort and must never fail the health command.
+        }
         let sessionLogEntries = [];
         try {
             const sinceDays = Math.max(0, Math.ceil((now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));
@@ -1482,6 +1680,8 @@ export function akmHealth(options = {}) {
             logBackingRate,
             stuckActiveRuns,
             semanticStatus,
+            semanticSearchMode,
+            embeddingEndpoint,
             sessionLogEntries,
             sessionExtraction: improveSummary.sessionExtraction,
             autoAccept: improveSummary.autoAccept,