akm-cli 0.9.16 → 0.9.17-alpha.1

package/dist/scripts/akm-migrate-node.js

@@ -12792,6 +12792,7 @@ var init_schema = __esm(() => {
     content_policy_reject: true,
     unsupported_type: true,
     no_change: true,
+    quality_rejected: true,
     aborted: true
   };
   PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
@@ -76098,6 +76099,7 @@ var IMPROVE_PROCESS_BASE_FIELDS = {
   timeoutMs: exports_external.union([positiveInt, exports_external.null()]).optional()
 };
 var allowedTypesField = exports_external.array(exports_external.string().min(1)).optional();
+var excludeRefPrefixesField = exports_external.array(exports_external.string().min(1)).optional();
 var processLimitField = positiveInt.optional();
 var qualityGateField = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional();
 var contradictionDetectionField = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional();
@@ -76138,6 +76140,7 @@ var antiCollapseField = exports_external.object({
 }).passthrough().optional();
 var REFLECT_PROCESS_FIELDS = {
   allowedTypes: allowedTypesField,
+  excludeRefPrefixes: excludeRefPrefixesField,
   limit: processLimitField,
   qualityGate: qualityGateField,
   lowValueFilter: lowValueFilterField
@@ -76169,7 +76172,8 @@ var GRAPH_EXTRACTION_PROCESS_FIELDS = {
   topN: positiveInt.optional(),
   includeTypes: exports_external.array(exports_external.string().min(1)).min(1).optional(),
   batchSize: positiveInt.optional(),
-  fullScan: exports_external.boolean().optional()
+  fullScan: exports_external.boolean().optional(),
+  maxChunksPerAsset: positiveInt.optional()
 };
 var EXTRACT_PROCESS_FIELDS = {
   defaultSince: exports_external.string().min(1).optional(),
@@ -76220,6 +76224,15 @@ function checkRetiredProcessKeys(value, ctx) {
     }
   }
 }
+function rejectExcludeRefPrefixesOutsideReflect(value, ctx) {
+  if ("excludeRefPrefixes" in value) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: ["excludeRefPrefixes"],
+      message: "excludeRefPrefixes is only valid on the reflect process"
+    });
+  }
+}
 var ImproveProcessConfigSchema = exports_external.object({
   ...IMPROVE_PROCESS_BASE_FIELDS,
   ...REFLECT_PROCESS_FIELDS,
@@ -76232,8 +76245,8 @@ var ImproveProcessConfigSchema = exports_external.object({
   ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS
 }).passthrough().superRefine(checkRetiredProcessKeys);
 var ReflectProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...REFLECT_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
-var DistillProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...DISTILL_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
-var ConsolidateProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...CONSOLIDATE_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
+var DistillProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...DISTILL_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys).superRefine(rejectExcludeRefPrefixesOutsideReflect);
+var ConsolidateProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...CONSOLIDATE_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys).superRefine(rejectExcludeRefPrefixesOutsideReflect);
 var MemoryInferenceProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...MEMORY_INFERENCE_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
 var GraphExtractionProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...GRAPH_EXTRACTION_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
 var ExtractProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...EXTRACT_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
@@ -97986,7 +97999,7 @@ var GATE_OUTCOMES = {
   "auto-rejected": true
 };
 function validatePresentMetadata(meta) {
-  const stringFields = ["sourceRun", "beforeHash", "backupContent"];
+  const stringFields = ["sourceRun", "beforeHash", "beforeHashNormalized", "backupContent"];
   for (const field of stringFields) {
     if (Object.hasOwn(meta, field) && typeof meta[field] !== "string")
       invalidPresentField(field);
@@ -98066,6 +98079,7 @@ function proposalRowToProposal(row) {
     changes,
     ...proposedTarget !== undefined ? { proposedTarget } : {},
     ...typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {},
+    ...typeof meta.beforeHashNormalized === "string" ? { beforeHashNormalized: meta.beforeHashNormalized } : {},
     ...meta.review !== undefined ? { review: meta.review } : {},
     ...typeof meta.confidence === "number" ? { confidence: meta.confidence } : {},
     ...meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {},
@@ -98092,6 +98106,8 @@ function proposalToRowValues(proposal, stashDir) {
     metaObj.proposedTarget = currentProposalTarget(proposal.proposedTarget);
   if (proposal.beforeHash !== undefined)
     metaObj.beforeHash = proposal.beforeHash;
+  if (proposal.beforeHashNormalized !== undefined)
+    metaObj.beforeHashNormalized = proposal.beforeHashNormalized;
   if (proposal.sourceRun !== undefined)
     metaObj.sourceRun = proposal.sourceRun;
   if (proposal.review !== undefined)

package/dist/scripts/akm-migrate.js

@@ -12791,6 +12791,7 @@ var init_schema = __esm(() => {
     content_policy_reject: true,
     unsupported_type: true,
     no_change: true,
+    quality_rejected: true,
     aborted: true
   };
   PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
@@ -75426,6 +75427,7 @@ var IMPROVE_PROCESS_BASE_FIELDS = {
   timeoutMs: exports_external.union([positiveInt, exports_external.null()]).optional()
 };
 var allowedTypesField = exports_external.array(exports_external.string().min(1)).optional();
+var excludeRefPrefixesField = exports_external.array(exports_external.string().min(1)).optional();
 var processLimitField = positiveInt.optional();
 var qualityGateField = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional();
 var contradictionDetectionField = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional();
@@ -75466,6 +75468,7 @@ var antiCollapseField = exports_external.object({
 }).passthrough().optional();
 var REFLECT_PROCESS_FIELDS = {
   allowedTypes: allowedTypesField,
+  excludeRefPrefixes: excludeRefPrefixesField,
   limit: processLimitField,
   qualityGate: qualityGateField,
   lowValueFilter: lowValueFilterField
@@ -75497,7 +75500,8 @@ var GRAPH_EXTRACTION_PROCESS_FIELDS = {
   topN: positiveInt.optional(),
   includeTypes: exports_external.array(exports_external.string().min(1)).min(1).optional(),
   batchSize: positiveInt.optional(),
-  fullScan: exports_external.boolean().optional()
+  fullScan: exports_external.boolean().optional(),
+  maxChunksPerAsset: positiveInt.optional()
 };
 var EXTRACT_PROCESS_FIELDS = {
   defaultSince: exports_external.string().min(1).optional(),
@@ -75548,6 +75552,15 @@ function checkRetiredProcessKeys(value, ctx) {
     }
   }
 }
+function rejectExcludeRefPrefixesOutsideReflect(value, ctx) {
+  if ("excludeRefPrefixes" in value) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: ["excludeRefPrefixes"],
+      message: "excludeRefPrefixes is only valid on the reflect process"
+    });
+  }
+}
 var ImproveProcessConfigSchema = exports_external.object({
   ...IMPROVE_PROCESS_BASE_FIELDS,
   ...REFLECT_PROCESS_FIELDS,
@@ -75560,8 +75573,8 @@ var ImproveProcessConfigSchema = exports_external.object({
   ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS
 }).passthrough().superRefine(checkRetiredProcessKeys);
 var ReflectProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...REFLECT_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
-var DistillProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...DISTILL_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
-var ConsolidateProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...CONSOLIDATE_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
+var DistillProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...DISTILL_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys).superRefine(rejectExcludeRefPrefixesOutsideReflect);
+var ConsolidateProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...CONSOLIDATE_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys).superRefine(rejectExcludeRefPrefixesOutsideReflect);
 var MemoryInferenceProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...MEMORY_INFERENCE_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
 var GraphExtractionProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...GRAPH_EXTRACTION_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
 var ExtractProcessConfigSchema = exports_external.object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...EXTRACT_PROCESS_FIELDS }).passthrough().superRefine(checkRetiredProcessKeys);
@@ -97942,7 +97955,7 @@ var GATE_OUTCOMES = {
   "auto-rejected": true
 };
 function validatePresentMetadata(meta) {
-  const stringFields = ["sourceRun", "beforeHash", "backupContent"];
+  const stringFields = ["sourceRun", "beforeHash", "beforeHashNormalized", "backupContent"];
   for (const field of stringFields) {
     if (Object.hasOwn(meta, field) && typeof meta[field] !== "string")
       invalidPresentField(field);
@@ -98022,6 +98035,7 @@ function proposalRowToProposal(row) {
     changes,
     ...proposedTarget !== undefined ? { proposedTarget } : {},
     ...typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {},
+    ...typeof meta.beforeHashNormalized === "string" ? { beforeHashNormalized: meta.beforeHashNormalized } : {},
     ...meta.review !== undefined ? { review: meta.review } : {},
     ...typeof meta.confidence === "number" ? { confidence: meta.confidence } : {},
     ...meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {},
@@ -98048,6 +98062,8 @@ function proposalToRowValues(proposal, stashDir) {
     metaObj.proposedTarget = currentProposalTarget(proposal.proposedTarget);
   if (proposal.beforeHash !== undefined)
     metaObj.beforeHash = proposal.beforeHash;
+  if (proposal.beforeHashNormalized !== undefined)
+    metaObj.beforeHashNormalized = proposal.beforeHashNormalized;
   if (proposal.sourceRun !== undefined)
     metaObj.sourceRun = proposal.sourceRun;
   if (proposal.review !== undefined)

package/dist/storage/repositories/index-entries-repository.js

@@ -684,6 +684,22 @@ export function getIndexedFilePaths(db) {
         .all();
     return new Set(rows.map((r) => r.file_path));
 }
+/**
+ * `entries.file_path -> content_hash` for every currently-indexed file that
+ * carries a stored hash. Used by per-file staleness detection
+ * (`hasNewerIndexableFiles`, R6) to tell "edited after the last build" apart
+ * from "already re-indexed with this exact content after the last build" —
+ * `indexWrittenAssets` upserts a fresh row (and its `content_hash`) without
+ * bumping `builtAt`, so mtime alone cannot distinguish the two cases.
+ */
+export function getIndexedFileHashes(db) {
+    const rows = db
+        .prepare(`SELECT file_path, content_hash FROM entries
+        WHERE file_path IS NOT NULL AND file_path <> ''
+          AND content_hash IS NOT NULL`)
+        .all();
+    return new Map(rows.map((r) => [r.file_path, r.content_hash]));
+}
 /**
  * Resolve a single `entries.file_path` by primary key, or `undefined` if no
  * row matches.
@@ -732,6 +748,33 @@ export function getEntryByRef(db, ref) {
     const id = findEntryIdByRef(db, ref);
     return id === undefined ? null : { id };
 }
+/** Build a {@link LiveRefSnapshot} from the current `entries` table. */
+export function getLiveRefSnapshot(db) {
+    const rows = db.prepare("SELECT item_ref FROM entries").all();
+    const itemRefs = new Set();
+    const conceptIds = new Set();
+    for (const { item_ref } of rows) {
+        itemRefs.add(item_ref);
+        const boundary = item_ref.indexOf("//");
+        if (boundary >= 0)
+            conceptIds.add(item_ref.slice(boundary + 2));
+    }
+    return { itemRefs, conceptIds };
+}
+/**
+ * `getEntryByRef`'s liveness check (bundle-qualified exact match, or bare
+ * `//conceptId` suffix match across bundles, each tried with the `.md`
+ * toggle {@link withMdVariants} applies) against a prebuilt
+ * {@link LiveRefSnapshot} instead of the database — no query per call.
+ */
+export function isRefLiveInSnapshot(snapshot, ref) {
+    const parsed = parseBundleRef(ref);
+    const conceptVariants = withMdVariants(parsed.conceptId);
+    if (parsed.bundle !== undefined) {
+        return conceptVariants.some((conceptId) => snapshot.itemRefs.has(`${parsed.bundle}//${conceptId}`));
+    }
+    return conceptVariants.some((conceptId) => snapshot.conceptIds.has(conceptId));
+}
 /**
  * The fully-qualified `item_ref` (`<bundle>//<conceptId>`, the durable stored
  * spelling — spec §11.1 D-R3) for an entry `id`, or `null` when the row is gone

package/dist/storage/repositories/proposals-repository.js

@@ -107,7 +107,7 @@ const GATE_OUTCOMES = {
     "auto-rejected": true,
 };
 function validatePresentMetadata(meta) {
-    const stringFields = ["sourceRun", "beforeHash", "backupContent"];
+    const stringFields = ["sourceRun", "beforeHash", "beforeHashNormalized", "backupContent"];
     for (const field of stringFields) {
         if (Object.hasOwn(meta, field) && typeof meta[field] !== "string")
             invalidPresentField(field);
@@ -224,6 +224,7 @@ export function proposalRowToProposal(row) {
         changes,
         ...(proposedTarget !== undefined ? { proposedTarget } : {}),
         ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
+        ...(typeof meta.beforeHashNormalized === "string" ? { beforeHashNormalized: meta.beforeHashNormalized } : {}),
         ...(meta.review !== undefined ? { review: meta.review } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
@@ -274,6 +275,8 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.proposedTarget = currentProposalTarget(proposal.proposedTarget);
     if (proposal.beforeHash !== undefined)
         metaObj.beforeHash = proposal.beforeHash;
+    if (proposal.beforeHashNormalized !== undefined)
+        metaObj.beforeHashNormalized = proposal.beforeHashNormalized;
     if (proposal.sourceRun !== undefined)
         metaObj.sourceRun = proposal.sourceRun;
     if (proposal.review !== undefined)

package/dist/storage/state-db-integrity.js

@@ -0,0 +1,123 @@
+// 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/.
+/**
+ * state.db integrity + reclaimable-space probes (R0, tier0-0917).
+ *
+ * `akm health`'s `state-db-integrity` check (src/commands/health/checks.ts)
+ * is a pure projection like every other check, so the actual IO lives here:
+ * a read-only `PRAGMA quick_check` and a read-only freelist/page-count read.
+ * Both open their own short-lived connection via the plain {@link openDatabase}
+ * opener — deliberately bypassing `openStateDatabase`'s managed-open/migration
+ * machinery (src/core/state-db.ts), since a corrupt database must not need a
+ * clean migration-ledger read just to report itself as corrupt.
+ *
+ * {@link vacuumStateDbIfReclaimable} is the post-purge VACUUM step: given an
+ * already-open read-write connection (VACUUM cannot run inside a transaction,
+ * and a read-only handle cannot run it at all) and a freelist reading, it
+ * VACUUMs only when the freelist ratio crosses {@link STATE_DB_FREELIST_WARN_RATIO}
+ * and never throws — a locked/busy database is reported, not raised.
+ *
+ * @module storage/state-db-integrity
+ */
+import { appendEvent } from "../core/events.js";
+import { openDatabase } from "./database.js";
+import { SQLITE_BUSY_TIMEOUT_MS } from "./sqlite-pragmas.js";
+/** How many corruption errors `PRAGMA quick_check` collects before it stops scanning and returns. */
+const QUICK_CHECK_ERROR_LIMIT = 10;
+/** Above this fraction of free pages, `state-db-integrity` warns and a post-purge pass VACUUMs. */
+export const STATE_DB_FREELIST_WARN_RATIO = 0.5;
+/** Event appended by {@link vacuumStateDbIfReclaimable} after a successful VACUUM. */
+export const STATE_DB_VACUUMED_EVENT = "state_db_vacuumed";
+function firstColumn(row) {
+    return row === undefined ? undefined : Object.values(row)[0];
+}
+function openReadonlyStateDb(dbPath) {
+    const db = openDatabase(dbPath, { readonly: true, create: false });
+    // Read-only handles cannot run journal_mode/foreign_keys (write operations),
+    // but busy_timeout is legal — see openReadonlyExistingDatabase's identical
+    // rationale in src/storage/repositories/index-connection.ts.
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+    return db;
+}
+/**
+ * Run `PRAGMA quick_check(N)` against `dbPath` read-only. Sub-second on a
+ * healthy multi-hundred-MB file; on a corrupt one, `N` bounds how many errors
+ * SQLite collects before it stops scanning, which keeps the check's runtime
+ * bounded even against a badly corrupt file.
+ */
+export function runStateDbQuickCheck(dbPath) {
+    let db;
+    try {
+        db = openReadonlyStateDb(dbPath);
+        const rows = db.prepare(`PRAGMA quick_check(${QUICK_CHECK_ERROR_LIMIT})`).all();
+        const lines = rows.map((row) => String(firstColumn(row)));
+        const ok = lines.length === 1 && lines[0] === "ok";
+        return { ok, lines };
+    }
+    catch (err) {
+        return { ok: false, lines: [], error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * Read `PRAGMA freelist_count` / `PRAGMA page_count` off an already-open
+ * connection. Shared by {@link getStateDbFreelistInfo} (which opens its own
+ * read-only handle) and the post-purge VACUUM call site, which must read the
+ * freelist off the same read-write connection the purge just used rather
+ * than open a second one.
+ */
+export function readFreelistInfo(db) {
+    const freelistCount = Number(firstColumn(db.prepare("PRAGMA freelist_count").get()) ?? 0);
+    const pageCount = Number(firstColumn(db.prepare("PRAGMA page_count").get()) ?? 0);
+    return { freelistCount, pageCount, ratio: pageCount > 0 ? freelistCount / pageCount : 0 };
+}
+/** Read `PRAGMA freelist_count` / `PRAGMA page_count` — how much of state.db is reclaimable by VACUUM. */
+export function getStateDbFreelistInfo(dbPath) {
+    let db;
+    try {
+        db = openReadonlyStateDb(dbPath);
+        return readFreelistInfo(db);
+    }
+    catch (err) {
+        return { freelistCount: 0, pageCount: 0, ratio: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * VACUUM `db` when `freelist.ratio` exceeds {@link STATE_DB_FREELIST_WARN_RATIO},
+ * appending a {@link STATE_DB_VACUUMED_EVENT} recording pages before/after.
+ * Intended to run immediately after the retention purge, on the same
+ * read-write connection the purge just used. Never throws: a locked/busy
+ * database (another writer holds the file right now) is reported via
+ * `reason: "busy"` rather than raised, since this is opportunistic
+ * maintenance and must not fail the purge pass it follows.
+ *
+ * The event is appended via `appendEvent` (not a direct `insertEvent` on
+ * `db`) so it honors the caller's `EventsContext` — `readOnly` suppresses
+ * the write and an injected `now` is used for `ts` — the same as every
+ * other event `runRetentionPurgePass` appends in this callback.
+ */
+export function vacuumStateDbIfReclaimable(db, freelist, eventsCtx) {
+    if (freelist.ratio <= STATE_DB_FREELIST_WARN_RATIO) {
+        return { ran: false, reason: "below-threshold", pagesBefore: freelist.pageCount };
+    }
+    try {
+        db.exec("VACUUM");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const busy = /busy|locked/i.test(message);
+        return { ran: false, reason: busy ? "busy" : "error", pagesBefore: freelist.pageCount, error: message };
+    }
+    const pagesAfter = Number(firstColumn(db.prepare("PRAGMA page_count").get()) ?? 0);
+    appendEvent({
+        eventType: STATE_DB_VACUUMED_EVENT,
+        metadata: { pagesBefore: freelist.pageCount, pagesAfter, freelistRatioBefore: freelist.ratio },
+    }, eventsCtx);
+    return { ran: true, pagesBefore: freelist.pageCount, pagesAfter };
+}

package/dist/workflows/program/schema.js

@@ -25,6 +25,7 @@ const RETRY_REASON_SET = {
     content_policy_reject: true,
     unsupported_type: true,
     no_change: true,
+    quality_rejected: true,
     aborted: true,
 };
 export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);

package/docs/reference/cli.md

@@ -387,7 +387,7 @@ Primary result fields:
 | Field | Description |
 | --- | --- |
 | `status` | Overall health verdict: `pass`, `warn`, or `fail` |
-| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-migrations`, `task-log-backing`, `active-runs`, `default-engine`, `model-map-files`, `default-llm-engine`, `configured-engines`, and `active-improve-strategy` |
+| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-integrity`, `state-db-migrations`, `task-log-backing`, `active-runs`, `default-engine`, `model-map-files`, `default-llm-engine`, `configured-engines`, and `active-improve-strategy` |
 | `advisories` | Non-fatal warnings including `semantic-search-runtime`, `session-extraction` (akmExtract pipeline health), `cli-version` (installed vs latest release), `thinking-control` (an `enableThinking: false` engine whose recorded usage still shows reasoning tokens), and `engine-last-used` (an engine bound to an enabled improve process with no recorded use in 30 days) |
 | `metrics` | Aggregate task/runtime metrics: `taskFailRate`, `agentFailureRate`, `stuckActiveRuns`, `logBackingRate`, `probeRoundTripMs` |
 | `improve` | Recent improve-loop counts derived from `improve_invoked`, `improve_skipped`, and `improve_completed` events |
@@ -2459,8 +2459,9 @@ configures a judgment engine. Each row carries `enabled`, the resolved
 `engine`/`model` (llm-backed processes only) and `engineKind`, this process's
 own lowering `notices`, and — for reflect/distill/consolidate only —
 `eligibleRefs`, the count of this run's `effectiveRefs` the process would act
-on (`shouldSkipRef`'s allowedTypes/process-disabled check; a count, not a
-per-ref matrix, to keep the envelope bounded). A row that could not resolve an
+on (`shouldSkipRef`'s allowedTypes/excludeRefPrefixes (reflect only)/
+process-disabled check; a count, not a per-ref matrix, to keep the envelope
+bounded). A row that could not resolve an
 engine or credential carries `unavailable: {configKey, reason}` — the same
 data behind `skippedProcesses` above, reshaped per process. When the process
 resolved a real engine whose credential just isn't reachable here, the row

package/docs/reference/data-and-telemetry.md

@@ -208,6 +208,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `events_purged` | Old events deleted by improve maintenance (90-day default retention) | `purgedCount`, `retentionDays` |
 | `improve_runs_purged` | Old `improve_runs` rows deleted by improve maintenance (same retention window as events) | `purgedCount`, `retentionDays` |
 | `improve_cycle_metrics_purged` | Old `improve_cycle_metrics` rows (365-day retention) deleted by improve maintenance | `purgedCount`, `retentionDays` |
+| `state_db_vacuumed` | state.db was VACUUMed after the retention purge because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `task_logs_purged` | Old scheduled-task log files purged by improve maintenance | |
 
 *Workflows*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.16",
+  "version": "0.9.17-alpha.1",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -796,6 +796,13 @@
                           "minLength": 1
                         }
                       },
+                      "excludeRefPrefixes": {
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      },
                       "limit": {
                         "type": "integer",
                         "exclusiveMinimum": 0
@@ -1207,6 +1214,10 @@
                       },
                       "fullScan": {
                         "type": "boolean"
+                      },
+                      "maxChunksPerAsset": {
+                        "type": "integer",
+                        "exclusiveMinimum": 0
                       }
                     },
                     "additionalProperties": true
@@ -2578,6 +2589,13 @@
                               "minLength": 1
                             }
                           },
+                          "excludeRefPrefixes": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          },
                           "limit": {
                             "type": "integer",
                             "exclusiveMinimum": 0
@@ -2989,6 +3007,10 @@
                           },
                           "fullScan": {
                             "type": "boolean"
+                          },
+                          "maxChunksPerAsset": {
+                            "type": "integer",
+                            "exclusiveMinimum": 0
                           }
                         },
                         "additionalProperties": true
@@ -3755,6 +3777,13 @@
             "minLength": 1
           }
         },
+        "excludeRefPrefixes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
         "limit": {
           "type": "integer",
           "exclusiveMinimum": 0
@@ -3883,6 +3912,10 @@
         "fullScan": {
           "type": "boolean"
         },
+        "maxChunksPerAsset": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
         "defaultSince": {
           "type": "string",
           "minLength": 1
@@ -4148,6 +4181,13 @@
                     "minLength": 1
                   }
                 },
+                "excludeRefPrefixes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
                 "limit": {
                   "type": "integer",
                   "exclusiveMinimum": 0
@@ -4559,6 +4599,10 @@
                 },
                 "fullScan": {
                   "type": "boolean"
+                },
+                "maxChunksPerAsset": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0
                 }
               },
               "additionalProperties": true

package/schemas/akm-workflow.json

@@ -154,6 +154,7 @@
         "content_policy_reject",
         "unsupported_type",
         "no_change",
+        "quality_rejected",
         "aborted"
       ]
     },

package/dist/commands/improve/eval-cases.js

@@ -1,52 +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/.
-import fs from "node:fs";
-import path from "node:path";
-import { writeFileAtomic } from "../../core/common.js";
-import { getEvalCasesDir } from "../../core/paths.js";
-import { recordWrittenPath } from "../../core/write-provenance.js";
-export function writeEvalCase(stashDir, evalCase) {
-    const evalDir = getEvalCasesDir(stashDir);
-    fs.mkdirSync(evalDir, { recursive: true });
-    const fileName = `${evalCase.slug}.md`;
-    const filePath = path.join(evalDir, fileName);
-    const content = `---
-ref: ${evalCase.ref}
-failureReason: ${evalCase.failureReason}
-assetType: ${evalCase.assetType}
-rejectedAt: ${evalCase.rejectedAt}
-source: ${evalCase.source}
----
-
-# Eval Case: ${evalCase.ref}
-
-**Failure reason:** ${evalCase.failureReason}
-**Source:** ${evalCase.source}
-**Asset type:** ${evalCase.assetType}
-
-This case was automatically captured when a distillation or proposal was rejected.
-Use it as a regression test: future improve runs on this ref should not produce
-output that would be rejected for the same reason.
-`;
-    writeFileAtomic(filePath, content);
-    // itlackey/akm#890: journal it even though it now lands under `$STATE`,
-    // outside the stash's git repo — `result.writtenPaths` still reports it
-    // (as an absolute path; see describeRunWrittenPaths in improve.ts), and
-    // the auto-sync commit's own containment check already excludes anything
-    // outside the stash from what gets staged, so recording it here cannot
-    // cause it to be committed.
-    recordWrittenPath(filePath);
-    return filePath;
-}
-export function countEvalCases(stashDir) {
-    const evalDir = getEvalCasesDir(stashDir);
-    if (!fs.existsSync(evalDir))
-        return 0;
-    try {
-        return fs.readdirSync(evalDir).filter((f) => f.endsWith(".md")).length;
-    }
-    catch {
-        return 0;
-    }
-}