akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/health/llm-usage.js

@@ -7,7 +7,7 @@
  */
 import { readEvents } from "../../core/events.js";
 import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
-import { toFiniteNumber } from "./improve-metrics.js";
+import { decodeLlmUsageRecord } from "../../llm/usage-telemetry.js";
 /** Stage key used for `llm_usage` events recorded outside any stage scope. */
 const UNATTRIBUTED_STAGE = "unattributed";
 function emptyLlmUsageStageAggregate() {
@@ -21,7 +21,7 @@ function emptyLlmUsageStageAggregate() {
     };
 }
 function emptyLlmUsageAggregate() {
-    return { ...emptyLlmUsageStageAggregate(), byStage: {} };
+    return { ...emptyLlmUsageStageAggregate(), byStage: {}, byProcess: {}, byEngine: {} };
 }
 /**
  * Aggregate `llm_usage` events (#576) into a window total plus a per-stage
@@ -32,25 +32,25 @@ function emptyLlmUsageAggregate() {
 export function summarizeLlmUsage(events) {
     const aggregate = emptyLlmUsageAggregate();
     for (const event of events) {
-        const meta = event.metadata ?? {};
-        const stageKey = typeof meta.stage === "string" && meta.stage ? meta.stage : UNATTRIBUTED_STAGE;
-        let stage = aggregate.byStage[stageKey];
-        if (!stage) {
-            stage = emptyLlmUsageStageAggregate();
-            aggregate.byStage[stageKey] = stage;
+        const record = decodeLlmUsageRecord(event.metadata);
+        if (!record)
+            continue;
+        const dimensions = [];
+        for (const [groups, key] of [
+            [aggregate.byStage, record.stage ?? UNATTRIBUTED_STAGE],
+            [aggregate.byProcess, record.process ?? UNATTRIBUTED_STAGE],
+            [aggregate.byEngine, record.engine ?? UNATTRIBUTED_STAGE],
+        ]) {
+            groups[key] ??= emptyLlmUsageStageAggregate();
+            dimensions.push(groups[key]);
         }
-        const durationMs = toFiniteNumber(meta.durationMs);
-        const promptTokens = toFiniteNumber(meta.promptTokens);
-        const completionTokens = toFiniteNumber(meta.completionTokens);
-        const totalTokens = toFiniteNumber(meta.totalTokens);
-        const reasoningTokens = toFiniteNumber(meta.reasoningTokens);
-        for (const target of [aggregate, stage]) {
+        for (const target of [aggregate, ...dimensions]) {
             target.calls += 1;
-            target.totalDurationMs += durationMs;
-            target.promptTokens += promptTokens;
-            target.completionTokens += completionTokens;
-            target.totalTokens += totalTokens;
-            target.reasoningTokens += reasoningTokens;
+            target.totalDurationMs += record.durationMs;
+            target.promptTokens += record.promptTokens ?? 0;
+            target.completionTokens += record.completionTokens ?? 0;
+            target.totalTokens += record.totalTokens ?? 0;
+            target.reasoningTokens += record.reasoningTokens ?? 0;
         }
     }
     return aggregate;

package/dist/commands/health/md-report.js

@@ -16,9 +16,7 @@ function renderTable(headers, rows) {
 }
 /**
  * Render `--detail per-run` rows as a TSV-ish aligned table. The column
- * shape was originally inherited from the retired
- * `scripts/improve-stats/runs-detail` bash helper; keep the same shape
- * so operator muscle memory carries over.
+ * shape is stable so repeated operator reports remain easy to compare.
  *
  * Columns: ts | ok | actions | refl_ok/fail/cd/skip |
  *   distill_q/llm-fail/qrej/cfg/skip | cons_proc/promo/merge/del |
@@ -28,14 +26,16 @@ export function renderRunsDetailMd(runs) {
     const headers = [
         "ts",
         "ok",
+        "strategy",
         "actions",
         "refl_ok/fail/cd/skip",
-        "distill_q/llm-fail/qrej/cfg/skip",
+        "distill_q/llm-fail/judge/validator/cfg/skip",
         "cons_proc/promo/merge/del",
         "mem_cons/written/skip",
         "graph_f/e/r",
         "orphans",
         "lint_f/fl",
+        "result_status",
     ];
     const rows = runs.map((r) => {
         const totalActions = r.actions.reflect.ok +
@@ -44,7 +44,8 @@ export function renderRunsDetailMd(runs) {
             r.actions.reflect.skipped +
             r.actions.distill.queued +
             r.actions.distill.llmFailed +
-            r.actions.distill.qualityRejected +
+            r.actions.distill.judgeRejected +
+            r.actions.distill.validatorRejected +
             r.actions.distill.configDisabled +
             r.actions.distill.skipped +
             r.actions.memoryPrune +
@@ -54,14 +55,16 @@ export function renderRunsDetailMd(runs) {
         return [
             r.startedAt,
             String(r.ok),
+            r.strategy ?? "",
             String(totalActions),
             `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}`,
-            `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.qualityRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
+            `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.judgeRejected}/${r.actions.distill.validatorRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
             `${r.consolidation.processed}/${r.consolidation.promoted}/${r.consolidation.merged}/${r.consolidation.deleted}`,
             `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.skippedNoFacts}`,
             `${r.graphExtraction.extractedFiles}/${r.graphExtraction.entities}/${r.graphExtraction.relations}`,
             String(r.orphansPurged),
             `${r.lintFixed}/${r.lintFlagged}`,
+            r.resultStatus ?? "valid",
         ];
     });
     return renderTable(headers, rows);
@@ -85,7 +88,13 @@ export function renderWindowCompareMd(windows, deltas) {
         "improve.memoryInference.skippedNoFacts",
     ]);
     const rows = [];
-    for (const path of INTERESTING_DELTA_PATHS) {
+    const paths = [
+        "runs",
+        "improve.resultRows.included",
+        "improve.resultRows.skipped.invalid",
+        ...INTERESTING_DELTA_PATHS,
+    ];
+    for (const path of paths) {
         const values = windows.map((w) => String(readNumericPath(w, path)));
         const delta = deltas?.[path];
         let deltaStr = "—";

package/dist/commands/health/metrics.js

@@ -3,38 +3,74 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * State.db-backed health metrics for `akm health`: the round-trip probe,
- * auto-accept calibration, denominator-fixed coverage, the enrichment-vs-
- * minting rollup, and the WS-5 per-run degradation metrics.
+ * denominator-fixed coverage, the enrichment-vs-minting rollup, and the WS-5
+ * per-run degradation metrics.
  */
-import { appendEvent, readEvents } from "../../core/events.js";
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { decodeImproveResult } from "../../core/improve-result.js";
+import { withStateDb } from "../../core/state-db.js";
+import { insertEvent } from "../../storage/repositories/events-repository.js";
 import { queryImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
-import { listProposalGateDecisions, listStateProposals } from "../../storage/repositories/proposals-repository.js";
-import { gateDecisionsToSamples, summarizeCalibration } from "../improve/calibration.js";
+import { listStateProposals } from "../../storage/repositories/proposals-repository.js";
+import { getTopRetrievalSalience } from "../../storage/repositories/salience-repository.js";
 import { roundRate, toFiniteNumber } from "./improve-metrics.js";
 import { ENRICHMENT_LANES, } from "./types.js";
 /** Event type appended + read back by the state.db round-trip probe. */
 const HEALTH_PROBE_EVENT = "health_probe";
+/** Synthetic sentinel ref (ref-grammar decision D-R3): a colon-free
+ * `<subsystem>/_<marker>` label. `health` has no asset stash-subdir, so
+ * `health/_probe` names the subsystem. */
+const HEALTH_PROBE_REF = "health/_probe";
+/**
+ * Verify state.db can accept a write and read it back — WITHOUT leaving any
+ * permanent trace (R-030). Earlier versions appended a `health_probe` event
+ * on every `akm health` invocation and never removed it: a read-only health
+ * check ran on a cron would grow state.db without bound (the only purge is
+ * `improve`'s retention pass, which a health-only user never runs). The probe
+ * row inserted here is deleted again inside the SAME connection once the
+ * round trip is confirmed, so the net effect on the `events` table is always
+ * zero rows — the round trip still genuinely exercises append + read against
+ * the real table, it just doesn't accumulate.
+ */
 export function probeStateDbRoundTrip(stateDbPath) {
-    const before = readEvents({}, { dbPath: stateDbPath }).nextOffset;
     const started = Date.now();
-    appendEvent({ eventType: HEALTH_PROBE_EVENT, ref: "health:probe", metadata: { source: "akm health" } }, { dbPath: stateDbPath });
-    const after = readEvents({ sinceOffset: before, type: HEALTH_PROBE_EVENT, ref: "health:probe" }, { dbPath: stateDbPath });
-    const durationMs = Date.now() - started;
-    if (after.events.length === 0 || after.nextOffset <= before) {
-        return { ok: false, durationMs, error: "probe event was not readable after append" };
+    try {
+        return withStateDb((db) => {
+            const ts = new Date().toISOString();
+            const insertedId = insertEvent(db, {
+                eventType: HEALTH_PROBE_EVENT,
+                ts,
+                ref: HEALTH_PROBE_REF,
+                metadata: { source: "akm health" },
+            });
+            const durationMs = Date.now() - started;
+            if (insertedId === undefined) {
+                return { ok: false, durationMs, error: "probe event insert did not return a row id" };
+            }
+            // The round-trip matches on the exact (id, eventType, ref) triple
+            // written above, then removes the row regardless of outcome — a
+            // failed round trip must not leak a row any more than a successful
+            // one should.
+            let roundTripOk = false;
+            try {
+                const row = db
+                    .prepare("SELECT 1 AS present FROM events WHERE id = ? AND event_type = ? AND ref = ?")
+                    .get(insertedId, HEALTH_PROBE_EVENT, HEALTH_PROBE_REF);
+                roundTripOk = row !== undefined;
+            }
+            finally {
+                db.prepare("DELETE FROM events WHERE id = ?").run(insertedId);
+            }
+            if (!roundTripOk) {
+                return { ok: false, durationMs, error: "probe event was not readable after append" };
+            }
+            return { ok: true, durationMs };
+        }, { path: stateDbPath });
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return { ok: false, durationMs: Date.now() - started, error: err instanceof Error ? err.message : String(err) };
     }
-    return { ok: true, durationMs };
-}
-/**
- * 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.
- */
-export function readCalibration(db, since, until) {
-    const decisions = listProposalGateDecisions(db);
-    const samples = gateDecisionsToSamples(decisions, { since, ...(until !== undefined ? { until } : {}) });
-    return summarizeCalibration(samples);
 }
 // ── WS-5 Observability helpers ───────────────────────────────────────────────
 /**
@@ -177,10 +213,10 @@ export function computeDegradationMetrics(db, since, until) {
     let entrenchmentFlagged;
     let salienceUniformityFlagged;
     try {
-        const rows = db
-            .prepare(`SELECT retrieval_salience FROM asset_salience
-         ORDER BY rank_score DESC LIMIT 100`)
-            .all();
+        // Fail-open: the asset_salience table may not exist yet (pre-WS-1 install).
+        // getTopRetrievalSalience (storage/repositories/salience-repository.ts,
+        // #672 part 2) owns the raw SQL; this call site's try/catch is unchanged.
+        const rows = getTopRetrievalSalience(db, 100);
         if (rows.length >= 5) {
             const vals = rows.map((r) => r.retrieval_salience).sort((a, b) => a - b);
             const n = vals.length;
@@ -188,12 +224,11 @@ export function computeDegradationMetrics(db, since, until) {
                 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;
+            // `sumAbsDiff` contains each unordered pair once, so the standard Gini
+            // denominator is n² × mean (the equivalent ordered-pair formula has 2n²).
+            const gini = mean > 0 ? sumAbsDiff / (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).
             // 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
@@ -221,7 +256,7 @@ export function computeDegradationMetrics(db, since, until) {
         let totalProcessed = 0;
         for (const row of runs) {
             try {
-                const result = JSON.parse(row.result_json);
+                const result = decodeImproveResult(row.result_json).envelope;
                 const cons = result.consolidation;
                 if (cons) {
                     totalContradicted += toFiniteNumber(cons.contradicted);

package/dist/commands/health/renderers.js

@@ -0,0 +1,47 @@
+// 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/.
+/**
+ * `akm health` document renderers, registered rather than intercepted (D7).
+ *
+ * Both handlers are **pure functions of the shaped result**. Everything the
+ * rich report needs — per-run rows, window-compare deltas, the pending
+ * proposal queue, and the window labels — travels in the result itself
+ * (`runs`/`deltas`/`report`, populated by `akm health --report`). There is no
+ * out-of-band context: an earlier revision bound the proposal queue through
+ * module state set by the command right before `output()`, which coupled the
+ * renderer to call order and made the command branch on the output format to
+ * know when to bind it. Putting the data in the envelope removed both.
+ *
+ * Returning `null` falls through to the generic renderer, so a result without
+ * the report dataset still renders — generically — instead of erroring or
+ * emitting an empty table.
+ */
+import { renderHtml, resolveTemplatePath } from "../../output/html-render.js";
+import { registerHtmlRenderer, registerMdRenderer } from "../../output/render-registry.js";
+import { buildHealthHtmlReplacements } from "./html-report.js";
+import { renderRunsDetailMd, renderWindowCompareMd } from "./md-report.js";
+function isHealthResult(value) {
+    return value !== null && typeof value === "object" && "status" in value;
+}
+registerMdRenderer("health", (result) => {
+    if (!isHealthResult(result))
+        return null;
+    if (result.windows && result.windows.length > 0) {
+        return renderWindowCompareMd(result.windows, result.deltas);
+    }
+    if (result.runs)
+        return renderRunsDetailMd(result.runs);
+    return null;
+});
+registerHtmlRenderer("health", (result) => {
+    if (!isHealthResult(result) || !result.report)
+        return null;
+    return renderHtml(resolveTemplatePath("health"), buildHealthHtmlReplacements(result, {
+        window: result.report.window,
+        compare: result.report.compare,
+        comparisonMode: result.report.comparisonMode,
+        proposals: result.report.pendingProposals,
+        deltas: result.deltas,
+    }));
+});