akm-cli 0.9.27 → 0.9.28-alpha.2

package/dist/commands/metrics/metrics-cli.js

@@ -0,0 +1,213 @@
+// 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 metrics` — one read-only report over what akm has already recorded:
+ * asset usage, feedback, utility, LLM usage, task runs, proposals and
+ * workflow spend. This module reads the stores and hands the rows to the pure
+ * aggregation in `collect.ts`; the shape is `AkmMetricsResult` (`types.ts`).
+ *
+ * Nothing is written, and nothing is migrated: `state.db` is opened read-only,
+ * and one with migrations pending is skipped with a note. A missing `state.db`
+ * gives an empty report and a missing `index.db` an empty utility section, each
+ * with a note, never an error.
+ */
+import fs from "node:fs";
+import { defineJsonCommand, output } from "../../cli/shared.js";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { readEvents } from "../../core/events.js";
+import { getDbPath } from "../../core/paths.js";
+import { getStateDbPath, listPendingStateMigrations } from "../../core/state-db.js";
+import { lookupBundleRefsReadonly } from "../../indexer/indexer.js";
+import { USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
+import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { getOutputMode } from "../../output/context.js";
+import { openDatabase } from "../../storage/database.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { listUtilityWithRefs } from "../../storage/repositories/index-utility-repository.js";
+import { countProposalsByStatus, listIndexCompletedEvents, listLowestOutcomeAssets, listSelectEvents, listUsageEventRows, summarizeWorkflowRuns, } from "../../storage/repositories/metrics-repository.js";
+import { queryTaskHistory } from "../../storage/repositories/task-history-repository.js";
+import { applyReadonlyPragmas } from "../../storage/sqlite-pragmas.js";
+import { parseHealthSince } from "../health.js";
+import { computeAcceptRateBySource } from "../health/accept-rate.js";
+import { emptyLlmUsageAggregate, summarizeLlmUsage } from "../health/llm-usage.js";
+import { buildMetricsResult, DEFAULT_EVENT_RETENTION_DAYS, indexRunsFromEvents, llmRowsFromEvents, retentionNotes, } from "./collect.js";
+const DEFAULT_SINCE = "30d";
+/** Cap on every ranked list. */
+const TOP = 20;
+/** Usage rows from people; improve, task and audit rows are akm's own reads. */
+const SOURCE = "user";
+/**
+ * Whether the report carries the raw window rows: the HTML dashboard
+ * re-aggregates from them client-side, so `--format html` always includes
+ * them, and `--detail full` includes them for any other format.
+ */
+export function metricsIncludeRows(mode) {
+    return mode.format === "html" || mode.detail === "full";
+}
+/**
+ * `select` events keyed on the durable ref. The events stream stores the ref
+ * as typed (`knowledge/x` for the default bundle), while `usage_events` stores
+ * `bundle//conceptId`; resolving here keeps one asset from showing as two rows.
+ * A ref that does not resolve (registry results, removed assets) is kept as is.
+ */
+async function durableSelects(selects) {
+    const unqualified = [];
+    for (const ref of new Set(selects.map((select) => select.ref))) {
+        try {
+            const parsed = parseBundleRef(ref);
+            if (!parsed.bundle)
+                unqualified.push({ ref, parsed });
+        }
+        catch {
+            // Not a local bundle ref: keep the ref as recorded.
+        }
+    }
+    const entries = await lookupBundleRefsReadonly(unqualified.map(({ parsed }) => parsed));
+    const resolved = new Map(unqualified.map(({ ref }, i) => [ref, entries[i]?.itemRef ?? ref]));
+    return selects.map((select) => ({ ts: select.ts, ref: resolved.get(select.ref) ?? select.ref }));
+}
+/** `index.db` utility rows, or a note saying why there are none. */
+function readUtility() {
+    let db;
+    try {
+        db = openReadonlyExistingDatabase(getDbPath());
+        if (!db)
+            return { note: "index.db was not found, so the utility section is empty. Run 'akm index' to build it." };
+        return { utility: listUtilityWithRefs(db) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { note: `index.db could not be read (${message}), so the utility section is empty.` };
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
+function readEventRetention() {
+    try {
+        const days = loadConfig().improve?.eventRetentionDays;
+        return { eventRetentionDays: typeof days === "number" ? days : DEFAULT_EVENT_RETENTION_DAYS };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            eventRetentionDays: DEFAULT_EVENT_RETENTION_DAYS,
+            note: `The config could not be loaded (${message}), so event retention assumes ${DEFAULT_EVENT_RETENTION_DAYS} days.`,
+        };
+    }
+}
+function readAcceptRate(stateDb, notes) {
+    try {
+        return computeAcceptRateBySource(undefined, { db: stateDb });
+    }
+    catch (error) {
+        notes.push(`Proposal accept rate is unavailable (${error instanceof Error ? error.message : String(error)}).`);
+        return [];
+    }
+}
+/** Read every store and build the report. */
+export async function akmMetrics(options = {}) {
+    const nowMs = (options.now ?? Date.now)();
+    const sinceIso = parseHealthSince(options.since ?? DEFAULT_SINCE);
+    const untilIso = new Date(nowMs).toISOString();
+    if (Date.parse(sinceIso) >= Date.parse(untilIso)) {
+        throw new UsageError(`--since (${sinceIso}) must be earlier than now (${untilIso}).`, "INVALID_FLAG_VALUE");
+    }
+    const notes = [];
+    const config = readEventRetention();
+    if (config.note)
+        notes.push(config.note);
+    notes.push(...retentionNotes({
+        sinceIso,
+        nowMs,
+        usageRetentionDays: USAGE_EVENT_RETENTION_DAYS,
+        eventRetentionDays: config.eventRetentionDays,
+    }));
+    const index = readUtility();
+    if (index.note)
+        notes.push(index.note);
+    const filter = { sinceIso, untilIso, source: SOURCE };
+    notes.push("Selects come from the events stream, which records no source, so they are counted for every source.");
+    const input = {
+        window: { since: sinceIso, until: untilIso },
+        source: SOURCE,
+        top: TOP,
+        includeRows: options.includeRows === true,
+        usage: [],
+        selects: [],
+        utility: index.utility,
+        outcomes: [],
+        llm: emptyLlmUsageAggregate(),
+        llmRows: [],
+        indexRuns: [],
+        tasks: [],
+        proposals: { byStatus: {}, acceptRateBySource: [] },
+        workflows: { runs: 0, byStatus: {}, tokens: 0, byModel: {} },
+        notes,
+    };
+    const stateDbPath = getStateDbPath();
+    if (!fs.existsSync(stateDbPath)) {
+        notes.push("state.db was not found, so every section except utility is empty.");
+        return buildMetricsResult(input);
+    }
+    let pending;
+    try {
+        pending = listPendingStateMigrations(stateDbPath);
+    }
+    catch (error) {
+        notes.push(`state.db could not be read (${error instanceof Error ? error.message : String(error)}), so every section except utility is empty.`);
+        return buildMetricsResult(input);
+    }
+    if (pending.length > 0) {
+        notes.push(`state.db has ${pending.length} pending migration${pending.length === 1 ? "" : "s"}; 'akm metrics' never migrates, so every section except utility is empty. Run 'akm migrate apply'.`);
+        return buildMetricsResult(input);
+    }
+    const stateDb = openDatabase(stateDbPath, { readonly: true, create: false });
+    let selects = [];
+    try {
+        applyReadonlyPragmas(stateDb);
+        input.usage = listUsageEventRows(stateDb, filter);
+        selects = listSelectEvents(stateDb, sinceIso, untilIso);
+        input.outcomes = listLowestOutcomeAssets(stateDb, TOP);
+        input.indexRuns = indexRunsFromEvents(listIndexCompletedEvents(stateDb, sinceIso, untilIso));
+        input.tasks = queryTaskHistory(stateDb, { since: sinceIso, until: untilIso });
+        input.proposals = {
+            byStatus: countProposalsByStatus(stateDb, sinceIso, untilIso),
+            acceptRateBySource: readAcceptRate(stateDb, notes),
+        };
+        input.workflows = summarizeWorkflowRuns(stateDb, sinceIso, untilIso);
+        const untilMs = Date.parse(untilIso);
+        const llmEvents = readEvents({ since: sinceIso, type: LLM_USAGE_EVENT }, { db: stateDb, readOnly: true }).events;
+        const inWindow = llmEvents.filter((event) => Date.parse(event.ts) < untilMs);
+        input.llm = summarizeLlmUsage(inWindow);
+        if (input.includeRows)
+            input.llmRows = llmRowsFromEvents(inWindow);
+    }
+    finally {
+        stateDb.close();
+    }
+    input.selects = await durableSelects(selects);
+    return buildMetricsResult(input);
+}
+export const metricsCommand = defineJsonCommand({
+    meta: {
+        name: "metrics",
+        description: "Experimental: report asset usage, feedback, utility, LLM usage, tasks, proposals and workflow spend from local records. Read-only. --format html writes a self-contained dashboard.",
+    },
+    args: {
+        since: {
+            type: "string",
+            description: `Window start: ISO, date, epoch ms, or 24h / 7d / 30d (default ${DEFAULT_SINCE})`,
+        },
+    },
+    async run({ args }) {
+        output("metrics", await akmMetrics({
+            since: args.since,
+            includeRows: metricsIncludeRows(getOutputMode()),
+        }));
+    },
+});

package/dist/commands/metrics/report-view.js

@@ -0,0 +1,243 @@
+// 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/.
+/** Lists are cut to this many rows at `--detail brief`; `normal`/`full` show what the top-20 cap kept. */
+export const BRIEF_LIST_LIMIT = 5;
+/** Narrow an unknown envelope to an `AkmMetricsResult`; renderers return `null` (generic fallback) otherwise. */
+export function isMetricsResult(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const r = value;
+    return r.schemaVersion === 1 && !!r.window && !!r.usage && !!r.feedback && !!r.llm;
+}
+const int = (n) => String(n);
+const dash = (v) => (v === undefined || v === "" ? "-" : v);
+/** A fraction as a percentage; `null` (zero denominator) is `n/a`, never `NaN`. */
+const pct = (n) => (n === null ? "n/a" : `${(n * 100).toFixed(1)}%`);
+const ms = (n) => (n === null ? "n/a" : `${Math.round(n)} ms`);
+const fixed = (n, digits) => (n === null ? "n/a" : n.toFixed(digits));
+function sourceFacts(counts) {
+    const entries = Object.entries(counts);
+    return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
+}
+function llmRows(group) {
+    return Object.entries(group).map(([name, a]) => [
+        name,
+        int(a.calls),
+        int(a.failures),
+        int(a.promptTokens),
+        int(a.completionTokens),
+        int(a.totalTokens),
+        ms(a.totalDurationMs),
+    ]);
+}
+const LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+export function buildMetricsView(r, detail) {
+    const brief = detail === "brief";
+    const cut = (items) => (brief ? items.slice(0, BRIEF_LIST_LIMIT) : items);
+    const { usage, feedback, utility, llm } = r;
+    const searches = usage.totals.searches;
+    const sections = [
+        {
+            title: "Usage",
+            facts: [
+                ["searches", int(searches)],
+                ["shows", int(usage.totals.shows)],
+                ["curates", int(usage.totals.curates)],
+                ["selects", int(usage.totals.selects)],
+                ["select rate", pct(usage.selectRate)],
+                [
+                    "zero-result searches",
+                    `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`,
+                ],
+                ["search median", ms(usage.searchMedianMs)],
+                ["distinct assets", int(usage.totals.distinctAssets)],
+                ["distinct queries", int(usage.totals.distinctQueries)],
+                ["by source", sourceFacts(usage.bySource)],
+            ],
+            tables: [
+                {
+                    title: "Top assets",
+                    headers: ["ref", "shows", "search hits", "selects", "+", "-", "last used"],
+                    rows: cut(usage.topAssets).map((a) => [
+                        a.ref,
+                        int(a.shows),
+                        int(a.searchHits),
+                        int(a.selects),
+                        int(a.positive),
+                        int(a.negative),
+                        dash(a.lastUsedAt),
+                    ]),
+                },
+                {
+                    title: "Top queries",
+                    headers: ["query", "count", "avg results", "last"],
+                    rows: cut(usage.topQueries).map((q) => [q.query, int(q.count), fixed(q.avgResults, 1), q.lastAt]),
+                },
+                {
+                    title: "Zero-result queries",
+                    headers: ["query", "count", "last"],
+                    rows: cut(usage.zeroResultQueries).map((q) => [q.query, int(q.count), q.lastAt]),
+                },
+                {
+                    title: "Daily",
+                    headers: ["day", "search", "show", "curate", "feedback"],
+                    rows: brief
+                        ? []
+                        : usage.daily.map((d) => [d.day, int(d.search), int(d.show), int(d.curate), int(d.feedback)]),
+                    hideWhenEmpty: true,
+                },
+            ],
+        },
+        {
+            title: "Feedback",
+            facts: [
+                ["positive", int(feedback.totals.positive)],
+                ["negative", int(feedback.totals.negative)],
+            ],
+            tables: [
+                {
+                    title: "By asset",
+                    headers: ["ref", "+", "-", "valence", "last"],
+                    rows: cut(feedback.byAsset).map((a) => [
+                        a.ref,
+                        int(a.positive),
+                        int(a.negative),
+                        fixed(a.valence, 2),
+                        a.lastAt,
+                    ]),
+                },
+                {
+                    title: "By tag",
+                    headers: ["tag", "+", "-"],
+                    rows: cut(Object.entries(feedback.byTag)).map(([tag, c]) => [tag, int(c.positive), int(c.negative)]),
+                    hideWhenEmpty: true,
+                },
+                {
+                    title: "Recent negative",
+                    headers: ["ref", "at", "reason", "tags"],
+                    rows: cut(feedback.recentNegative).map((n) => [n.ref, n.at, dash(n.reason), dash(n.tags?.join(", "))]),
+                },
+            ],
+        },
+        {
+            title: "Utility",
+            facts: [
+                ["scored assets", int(utility.count)],
+                ["never used", int(utility.neverUsed)],
+            ],
+            tables: [
+                {
+                    title: "Histogram",
+                    headers: ["bucket", "count"],
+                    rows: utility.histogram.map((h) => [h.bucket, int(h.count)]),
+                    hideWhenEmpty: true,
+                },
+                { title: "Lowest", headers: utilityHeaders(), rows: cut(utility.lowest).map(utilityRow) },
+                { title: "Highest", headers: utilityHeaders(), rows: cut(utility.highest).map(utilityRow) },
+                {
+                    title: "Lowest outcome",
+                    headers: ["ref", "outcome", "retrievals", "negative", "accepted changes"],
+                    rows: cut(r.outcomes.lowestOutcome).map((o) => [
+                        o.ref,
+                        fixed(o.outcomeScore, 2),
+                        int(o.retrievalCount),
+                        int(o.negativeFeedbackCount),
+                        int(o.acceptedChangeCount),
+                    ]),
+                    hideWhenEmpty: true,
+                },
+            ],
+        },
+        {
+            title: "LLM",
+            facts: [
+                ["calls", int(llm.calls)],
+                ["failed", int(llm.failures)],
+                ["prompt tokens", int(llm.promptTokens)],
+                ["completion tokens", int(llm.completionTokens)],
+                ["reasoning tokens", int(llm.reasoningTokens)],
+                ["total tokens", int(llm.totalTokens)],
+                ["time", ms(llm.totalDurationMs)],
+            ],
+            tables: [
+                { title: "By engine", headers: LLM_HEADERS, rows: cut(llmRows(llm.byEngine)), hideWhenEmpty: true },
+                { title: "By process", headers: LLM_HEADERS, rows: cut(llmRows(llm.byProcess)), hideWhenEmpty: true },
+                { title: "By stage", headers: LLM_HEADERS, rows: cut(llmRows(llm.byStage)), hideWhenEmpty: true },
+            ],
+        },
+        {
+            title: "Index",
+            facts: [
+                ["runs", int(r.index.runs)],
+                ["median time", ms(r.index.medianMs)],
+            ],
+            tables: [
+                {
+                    title: "Recent runs",
+                    headers: ["at", "mode", "time"],
+                    rows: brief ? [] : r.index.recent.map((i) => [i.at, i.mode, ms(i.totalMs)]),
+                    hideWhenEmpty: true,
+                },
+            ],
+        },
+        {
+            title: "Tasks",
+            facts: [
+                ["runs", int(r.tasks.runs)],
+                ["failed", int(r.tasks.failed)],
+                ["fail rate", pct(r.tasks.failRate)],
+            ],
+            tables: [
+                {
+                    title: "By task",
+                    headers: ["task", "runs", "failed", "median"],
+                    rows: cut(r.tasks.byTask).map((t) => [t.taskId, int(t.runs), int(t.failed), ms(t.medianMs)]),
+                    hideWhenEmpty: true,
+                },
+            ],
+        },
+        {
+            title: "Proposals",
+            facts: [["by status", sourceFacts(r.proposals.byStatus)]],
+            tables: [
+                {
+                    title: "Accept rate by source",
+                    headers: ["source", "total", "accepted", "rejected", "pending", "accept rate"],
+                    rows: r.proposals.acceptRateBySource.map((p) => [
+                        p.source,
+                        int(p.total),
+                        int(p.accepted),
+                        int(p.rejected),
+                        int(p.pending),
+                        pct(p.acceptRate),
+                    ]),
+                    hideWhenEmpty: true,
+                },
+            ],
+        },
+        {
+            title: "Workflows",
+            facts: [
+                ["runs", int(r.workflows.runs)],
+                ["by status", sourceFacts(r.workflows.byStatus)],
+                ["tokens", int(r.workflows.tokens)],
+                ["tokens by model", sourceFacts(r.workflows.byModel)],
+            ],
+            tables: [],
+        },
+    ];
+    const f = r.filters;
+    return {
+        window: `${r.window.since} to ${r.window.until}`,
+        filters: `source=${f.source}`,
+        sections,
+        notes: r.notes,
+    };
+}
+function utilityHeaders() {
+    return ["ref", "utility", "shows", "searches", "select rate", "last used"];
+}
+function utilityRow(u) {
+    return [u.ref, fixed(u.utility, 2), int(u.showCount), int(u.searchCount), pct(u.selectRate), dash(u.lastUsedAt)];
+}

package/dist/commands/metrics/types.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/commands/read/search.js

@@ -293,6 +293,11 @@ function logSearchEvent(rawQuery, response, mode = "keyword", eventSource = "use
                         registryHitCount,
                         resolvedCount: resolved.length,
                         mode,
+                        // Whole-search latency plus the rank/embed phases when the local
+                        // search reported them, so `akm metrics` can show timings later.
+                        totalMs: response.timing?.totalMs,
+                        rankMs: response.timing?.rankMs,
+                        embedMs: response.timing?.embedMs,
                     }),
                     source: eventSource,
                 });

package/dist/indexer/indexer.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
 import { compareCodePoints, isHttpUrl } from "../core/common.js";
+import { appendEvent } from "../core/events.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
@@ -500,6 +501,32 @@ async function akmIndexReal(options) {
         vacuumIndexDb(db, onProgress);
         const totalEntries = getEntryCount(db);
         const tFinalizeEnd = Date.now();
+        const timing = {
+            totalMs: Date.now() - t0,
+            walkMs: tWalkEnd - tWalkStart,
+            llmMs: tLlmEnd - tWalkEnd,
+            embedMs: tEmbedEnd - tLlmEnd,
+            ftsMs: tFtsEnd - tEmbedEnd,
+            finalizeMs: tFinalizeEnd - tFinalizeStart,
+            cleanMs: clean ? cleanEnd - cleanStart : 0,
+            preflightMs: t0 - requestedAt,
+            sourceCacheMs: sourceCacheEnd - sourceCacheStart,
+            endToEndMs: Date.now() - requestedAt,
+        };
+        // Persist the phase timings so `akm metrics` can report index latency
+        // after the command output is gone. Best-effort, like every appendEvent.
+        appendEvent({
+            eventType: "index_completed",
+            metadata: {
+                mode,
+                totalMs: timing.totalMs,
+                walkMs: timing.walkMs,
+                llmMs: timing.llmMs,
+                embedMs: timing.embedMs,
+                ftsMs: timing.ftsMs,
+                finalizeMs: timing.finalizeMs,
+            },
+        });
         return {
             stashDir,
             totalEntries,
@@ -512,18 +539,7 @@ async function akmIndexReal(options) {
             ...(warnings.length > 0 ? { warnings } : {}),
             ...(Object.keys(persistedAdapters).length > 0 ? { configUpdated: { detectedAdapters: persistedAdapters } } : {}),
             verification,
-            timing: {
-                totalMs: Date.now() - t0,
-                walkMs: tWalkEnd - tWalkStart,
-                llmMs: tLlmEnd - tWalkEnd,
-                embedMs: tEmbedEnd - tLlmEnd,
-                ftsMs: tFtsEnd - tEmbedEnd,
-                finalizeMs: tFinalizeEnd - tFinalizeStart,
-                cleanMs: clean ? cleanEnd - cleanStart : 0,
-                preflightMs: t0 - requestedAt,
-                sourceCacheMs: sourceCacheEnd - sourceCacheStart,
-                endToEndMs: Date.now() - requestedAt,
-            },
+            timing,
             ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
         };
     }
@@ -1110,7 +1126,9 @@ async function resolveLookupSources() {
     const { resolveSourceEntries } = await import("./search/search-source.js");
     return resolveSourceEntries(undefined, loadConfig());
 }
-async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
+async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase, 
+/** The opener hands out a handle the caller owns and closes. */
+borrowed = false) {
     const sources = await resolveLookupSources();
     if (sources.length === 0)
         return { entry: null };
@@ -1171,7 +1189,7 @@ async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
         return resolved(null);
     }
     finally {
-        if (db)
+        if (db && !borrowed)
             closeDatabase(db);
     }
 }
@@ -1200,6 +1218,38 @@ export async function lookupBundleRefReadonly(ref) {
         throw resolution.indexError;
     return resolution.entry;
 }
+/**
+ * {@link lookupBundleRefReadonly} for many refs through one snapshot of the
+ * index, which is copied once rather than once per ref. A ref that does not
+ * resolve, or an index that cannot be read, gives `null` for that ref.
+ */
+export async function lookupBundleRefsReadonly(refs) {
+    if (refs.length === 0)
+        return [];
+    let db;
+    try {
+        db = openReadonlyExistingDatabase(getDbPath(), { isolatedSnapshot: true });
+    }
+    catch {
+        // Unreadable index: every ref stays unresolved.
+    }
+    try {
+        const entries = [];
+        for (const ref of refs) {
+            try {
+                entries.push((await lookupBundleRefWithResolutionUsing(ref, () => db, true)).entry);
+            }
+            catch {
+                entries.push(null);
+            }
+        }
+        return entries;
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
 function readLookupEntry(db, id, fallbackConceptId, sourceRoot) {
     const row = db
         .prepare("SELECT file_path AS filePath, type, document_json AS documentJson, " +

package/dist/indexer/usage/usage-events.js

@@ -134,7 +134,9 @@ export function purgeOldUsageEvents(db, retentionDays) {
         return;
     try {
         const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-        db.prepare("DELETE FROM usage_events WHERE created_at < ?").run(cutoff);
+        // `created_at` is `YYYY-MM-DD HH:MM:SS`, not ISO: normalize both sides so the
+        // space-vs-`T` ordering doesn't delete the whole cutoff date early.
+        db.prepare("DELETE FROM usage_events WHERE datetime(created_at) < datetime(?)").run(cutoff);
     }
     catch {
         /* Table may not exist yet */

package/dist/integrations/session-logs/pre-filter.js

@@ -31,6 +31,7 @@ export const DEFAULT_AKM_READONLY_OPS = new Set([
     "events",
     "config",
     "health",
+    "metrics",
 ]);
 /**
  * Regex patterns that identify post-compact / activity-log noise. Conservative