akm-cli 0.9.16 → 0.9.17-alpha.2

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);
@@ -76986,6 +76999,31 @@ function upgradeConfigVersion(raw, sourcePath) {
 
 // src/core/config/config.ts
 init_legacy_source_shape_shim();
+
+// src/core/config/retired-experimental-keys-shim.ts
+init_common();
+init_warn();
+var RETIRED_EXPERIMENTAL_KEYS = ["workflowEngine"];
+function retiredExperimentalKeysIn(raw) {
+  const experimental = raw.experimental;
+  if (!isRecord(experimental))
+    return [];
+  return RETIRED_EXPERIMENTAL_KEYS.filter((key) => (key in experimental));
+}
+function stripRetiredExperimentalKeys(raw, sourcePath) {
+  const present = retiredExperimentalKeysIn(raw);
+  if (present.length === 0)
+    return raw;
+  const original = raw.experimental;
+  const experimental = { ...original };
+  for (const key of present)
+    delete experimental[key];
+  const where = sourcePath ? ` at ${sourcePath}` : "";
+  warnOnce(`config:retired-experimental-key${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired experimental key(s) ${present.join(", ")} \u2014 ignored in memory. Run \`akm migrate apply\` to remove ${present.length === 1 ? "it" : "them"} from the config file and silence this warning.`);
+  return { ...raw, experimental };
+}
+
+// src/core/config/config.ts
 init_paths();
 init_warn();
 var DEFAULT_CONFIG = {
@@ -77045,7 +77083,8 @@ function loadUserConfig() {
 function runConfigFilePipeline(text, sourcePath) {
   const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
   const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
-  return liftExtraParamsOrThrow(parsedRaw, sourcePath);
+  const liftedRaw = liftExtraParamsOrThrow(parsedRaw, sourcePath);
+  return stripRetiredExperimentalKeys(liftedRaw, sourcePath);
 }
 function liftExtraParamsOrThrow(parsedRaw, sourcePath) {
   const where = sourcePath ? ` at ${sourcePath}` : "";
@@ -85704,8 +85743,11 @@ function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
     return;
   throw new UsageError(`Bundle "${source.name}" uses adapter "${source.adapterId}", which does not support AKM asset writes.`, "INVALID_FLAG_VALUE");
 }
+function isWriteCapableSourceKind(kind) {
+  return kind === "filesystem" || kind === "git";
+}
 function adaptConfiguredSource(runtime) {
-  if (runtime.type !== "filesystem" && runtime.type !== "git") {
+  if (!isWriteCapableSourceKind(runtime.type)) {
     throw new ConfigError(`write-source: source "${runtime.name}" has unsupported kind "${runtime.type}" for writes. ` + "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
   }
   const kind = runtime.type;
@@ -93169,32 +93211,7 @@ var GLOBAL_OUTPUT_ARGS = {
 init_errors();
 
 // scripts/akm-migrate/help.txt
-var help_default = `Usage: akm-migrate <command> [options]
-
-The one migration tool for an akm installation. Every historical shape akm
-has ever written lives here; the CLI proper reads only current schemas.
-\`status\` and \`apply\` run every step, in order, and print one combined JSON
-plan (exit 1 when any step is blocked):
-
-  1. legacy config \`extraParams\` keys lifted onto first-class engine fields
-  2. scheduler grants bound to the configured source installation that was
-     approved (stale grants whose bundle no longer exists are removed)
-  3. pending state.db migrations, historical-destructive ones included,
-     with a verified sibling safety copy (the only path that admits them)
-  4. task-v2 files to task v3, then task-v3 files to task source v4
-  5. superseded pre-0.9.0 \`.akm\` residue and stale filesystem transactions
-  6. live \`.akm\` writers relocated to \`$STATE\`/\`$CACHE\`, for every local
-     bundle (distill-rejected, eval-cases, measurement verdicts, and stale
-     improve-pipeline locks \u2014 a lock a live run still holds is left alone)
-
-\`akm migrate status|apply\` wraps this executable; \`akm upgrade\` runs
-\`apply\` after its install step, so an image that ships akm can put either
-in its entrypoint (a current installation is a no-op).
-
-Commands:
-  status              Inspect every pending migration without changing anything.
-  apply [--dry-run]   Back up and apply every pending migration.
-`;
+var help_default = "Usage: akm-migrate <command> [options]\n\nThe one migration tool for an akm installation. Every historical shape akm\nhas ever written lives here; the CLI proper reads only current schemas.\n`status` and `apply` run every step, in order, and print one combined JSON\nplan (exit 1 when any step is blocked):\n\n  1. legacy config `extraParams` keys lifted onto first-class engine fields\n  2. retired `experimental.*` config keys removed (today `workflowEngine`)\n  3. scheduler grants bound to the configured source installation that was\n     approved (stale grants whose bundle no longer exists are removed)\n  4. pending state.db migrations, historical-destructive ones included,\n     with a verified sibling safety copy (the only path that admits them)\n  5. source-owned schedule enablement converted to host-local scheduler\n     grants\n  6. task-v2 files to task v3, then task-v3 files to task source v4\n  7. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions\n  8. live `.akm` writers relocated to `$STATE`/`$CACHE`, for every local\n     bundle (distill-rejected, eval-cases, measurement verdicts, and stale\n     improve-pipeline locks \u2014 a lock a live run still holds is left alone)\n\n`akm migrate status|apply` wraps this executable; `akm upgrade` runs\n`apply` after its install step, so an image that ships akm can put either\nin its entrypoint (a current installation is a no-op).\n\nCommands:\n  status              Inspect every pending migration without changing anything.\n  apply [--dry-run]   Back up and apply every pending migration.\n";
 
 // scripts/akm-migrate/run-migrate.ts
 init_common();
@@ -94730,10 +94747,44 @@ function applyConfigExtraParamsLift(configPath) {
   return { applied: true, lifted, conflicts: [] };
 }
 
+// scripts/akm-migrate/migrate/config-retired-experimental-keys.ts
+function readRawConfig2(configPath) {
+  const text = readConfigText(configPath);
+  if (text === undefined)
+    return;
+  return parseConfigText(text, configPath);
+}
+function findConfigRetiredExperimentalKeys(configPath) {
+  const raw = readRawConfig2(configPath);
+  if (!raw)
+    return { removed: [] };
+  return { removed: retiredExperimentalKeysIn(raw).map((key) => `experimental.${key}`) };
+}
+function applyConfigRetiredExperimentalKeys(configPath) {
+  const raw = readRawConfig2(configPath);
+  if (!raw)
+    return { applied: false, removed: [] };
+  const retired = retiredExperimentalKeysIn(raw);
+  if (retired.length === 0)
+    return { applied: false, removed: [] };
+  const experimental = { ...raw.experimental };
+  for (const key of retired)
+    delete experimental[key];
+  const config = { ...raw, experimental };
+  const release = acquireConfigLock();
+  try {
+    backupExistingConfig(configPath);
+    writeConfigAtomic(configPath, config);
+  } finally {
+    release();
+  }
+  return { applied: true, removed: retired.map((key) => `experimental.${key}`) };
+}
+
 // scripts/akm-migrate/migrate/config-scheduler-source-ids.ts
 init_asset_ref();
 init_bundle_id();
-function readRawConfig2(configPath) {
+function readRawConfig3(configPath) {
   const text = readConfigText(configPath);
   return text === undefined ? undefined : parseConfigText(text, configPath);
 }
@@ -94788,13 +94839,13 @@ function implicitBundleSourceId(raw, bundleId) {
   return implicitId === bundleId ? filesystemBundleSourceId(root2) : undefined;
 }
 function findConfigSchedulerSourceIdMigration(configPath) {
-  const raw = readRawConfig2(configPath);
+  const raw = readRawConfig3(configPath);
   return Object.freeze({ changes: Object.freeze(raw ? migrationChanges(raw) : []) });
 }
 function applyConfigSchedulerSourceIdMigration(configPath) {
   const release = acquireConfigLock();
   try {
-    const raw = readRawConfig2(configPath);
+    const raw = readRawConfig3(configPath);
     if (!raw)
       return Object.freeze({ applied: false, changes: Object.freeze([]) });
     const changes = migrationChanges(raw);
@@ -97942,7 +97993,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 +98073,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 +98100,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)
@@ -104011,12 +104065,16 @@ async function runMigration(options) {
   if (apply && configExtraParams.applied)
     resetConfigCache();
   const pendingLift = apply ? undefined : configExtraParams.pending;
+  const configRetiredExperimentalKeys = apply ? applyConfigRetiredExperimentalKeys(configPath) : { pending: findConfigRetiredExperimentalKeys(configPath) };
+  if (apply && configRetiredExperimentalKeys.applied)
+    resetConfigCache();
   if (pendingLift && pendingLift.lifted.length > 0) {
     return {
       schemaVersion: 1,
       status: "blocked",
       blockers: pendingLift.lifted,
       configExtraParams,
+      configRetiredExperimentalKeys,
       stateMigrations: { pending: listPendingStateMigrations() }
     };
   }
@@ -104031,6 +104089,7 @@ async function runMigration(options) {
       blockers: pendingSchedulerBindings.changes.map((change) => `${change.kind === "bind" ? "bind" : "drop"} scheduler activation ${change.ref}` + (change.reason ? `: ${change.reason}` : "")),
       configExtraParams,
       configSchedulerSourceIds,
+      configRetiredExperimentalKeys,
       stateMigrations: { pending: listPendingStateMigrations() }
     };
   }
@@ -104050,12 +104109,14 @@ async function runMigration(options) {
   }
   const stateStatus = "pending" in stateMigrations && stateMigrations.pending.length > 0 ? "ready" : "current";
   const schedulerStatus = "pending" in schedulerActivation && schedulerActivation.pending.length > 0 ? "ready" : "current";
+  const retiredKeysStatus = "pending" in configRetiredExperimentalKeys && configRetiredExperimentalKeys.pending.removed.length > 0 ? "ready" : "current";
   return {
     schemaVersion: 1,
-    status: worstStatus(worstStatus(worstStatus(taskV3.status, taskV4.status), stateStatus), schedulerStatus),
+    status: worstStatus(worstStatus(worstStatus(worstStatus(taskV3.status, taskV4.status), stateStatus), schedulerStatus), retiredKeysStatus),
     blockers: [...taskV3.blockers, ...taskV4.blockers],
     configExtraParams,
     configSchedulerSourceIds,
+    configRetiredExperimentalKeys,
     stateMigrations,
     schedulerActivation,
     taskV3Migration: taskV3.taskV3Migration,

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 |
@@ -1673,16 +1673,25 @@ in order:
 
 1. legacy config `extraParams` keys lifted onto first-class engine fields
    (`configExtraParams`);
-2. pending `state.db` migrations, historical-destructive ones included, with
+2. retired `experimental.*` config keys removed, today `workflowEngine`
+   (`configRetiredExperimentalKeys`) — config loading already ignores them
+   with a one-time warning, so this only cleans the file;
+3. scheduler grants bound to the configured source installation that was
+   approved, with stale grants for removed bundles dropped
+   (`configSchedulerSourceIds`);
+4. pending `state.db` migrations, historical-destructive ones included, with
    a verified sibling safety copy (`stateMigrations`) — the only path besides
    `akm upgrade` that admits released migration 018, which an ordinary
    command refuses;
-3. task-v2 files to task v3, then task-v3 files to task source v4
+5. source-owned schedule enablement converted to host-local scheduler grants
+   (`schedulerActivation`);
+6. task-v2 files to task v3, then task-v3 files to task source v4
    (`taskV3Migration`, `taskV4Migration`), each keeping its own lock, backup,
    prevalidation, and rollback, so a file blocked in the first generation does
    not stop the second from converting files already at `version: 3`;
-4. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions
-   (`deadResidue`, `staleTxns`).
+7. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions
+   (`deadResidue`, `staleTxns`), then live `.akm` writers relocated to
+   `$STATE`/`$CACHE` (`writerRelocation`).
 
 ```sh
 akm migrate status
@@ -2459,8 +2468,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.2",
   "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