akm-cli 0.9.3 → 0.9.4

package/dist/tasks/source/task-to-v4.js

@@ -0,0 +1,467 @@
+// 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/.
+/**
+ * Pure, byte-producing task-v3 to task-source-v4 migration planner (spec
+ * docs/plans/specs/p2b-input-bindings.md §1.3, §1.7 C-N1, §5). Mirrors
+ * `task-to-v3.ts`'s fail-closed ladder exactly: the INPUT side is read as a
+ * raw record by a vendored bounded-YAML reader (never the typed
+ * `parseTaskV3Yaml`, which would normalize away exactly the value bytes this
+ * migrator must preserve — a duration string like "5m", or a bare numeric
+ * `timeout`, would be converted to milliseconds by the real parser). The
+ * OUTPUT side is validated through the REAL `parseTaskSourceV4` before a
+ * "changed" outcome is ever handed back (C-N1, B-71).
+ *
+ * `inputs:` is never invented — the migrator translates structure, not
+ * intent (spec §5.3).
+ */
+import crypto from "node:crypto";
+import path from "node:path";
+import { LineCounter, parseDocument, stringify as stringifyYaml } from "yaml";
+import { assertBoundedTaskYamlDocument, TASK_V3_MAX_SOURCE_BYTES } from "./bounded-document.js";
+import { classifyTaskV3Uses } from "./task-source-v3-frozen.js";
+import { parseTaskSourceV4 } from "./task-source-v4.js";
+/** The closed v3 top-level key set (`src/tasks/source-v3.ts`'s own, vendored — not exported there). */
+const V3_TOP_LEVEL_KEYS = new Set([
+    "version",
+    "name",
+    "uses",
+    "run",
+    "with",
+    "env",
+    "shell",
+    "working-directory",
+    "akm",
+    "on",
+]);
+/** The closed v3 `akm.*` key set, vendored from `src/tasks/source-v3.ts`. */
+const V3_AKM_KEYS = new Set([
+    "schedule",
+    "enabled",
+    "description",
+    "when_to_use",
+    "tags",
+    "agent",
+    "engine",
+    "model",
+    "inference",
+    "outputSchema",
+    "tools",
+    "timeout",
+    "redact",
+    "maxSteps",
+    "maxRetries",
+]);
+/** The closed v3 `on.*` key set, vendored from `src/tasks/source-v3.ts`. */
+const V3_ON_KEYS = new Set(["schedule", "workflow_dispatch"]);
+/** `akm.*` keys hoisted verbatim to the identical top-level v4 key (schedule/enabled handled separately). */
+const AKM_HOIST_KEYS = [
+    "description",
+    "when_to_use",
+    "tags",
+    "agent",
+    "engine",
+    "model",
+    "inference",
+    "tools",
+    "timeout",
+    "redact",
+    "maxSteps",
+    "maxRetries",
+];
+function hash(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+function causeMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function base(input) {
+    const inspectionIdentity = input.inspectionIdentity
+        ? Object.freeze({
+            file: Object.freeze({ ...input.inspectionIdentity.file }),
+            root: Object.freeze({ ...input.inspectionIdentity.root }),
+            ...(input.inspectionIdentity.bundleRoot
+                ? { bundleRoot: Object.freeze({ ...input.inspectionIdentity.bundleRoot }) }
+                : {}),
+        })
+        : undefined;
+    return {
+        filePath: input.filePath,
+        before: Buffer.from(input.bytes),
+        beforeHash: hash(input.bytes),
+        mode: input.mode,
+        writable: input.writable,
+        ...(input.onDiskWritable !== undefined ? { onDiskWritable: input.onDiskWritable } : {}),
+        ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
+        ...(inspectionIdentity ? { inspectionIdentity } : {}),
+    };
+}
+function blocked(input, reason, detail) {
+    return Object.freeze({ status: "blocked", ...base(input), reason, ...(detail ? { detail } : {}) });
+}
+function plainRecord(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a mapping`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(`${label} must use a plain or null prototype`);
+    }
+    return value;
+}
+function exactString(value, label, nonempty = false) {
+    if (typeof value !== "string" || (nonempty && value.trim().length === 0)) {
+        throw new Error(`${label} must be ${nonempty ? "a non-empty " : "a "}string`);
+    }
+    return value;
+}
+/**
+ * Vendored raw-record reader (mirrors `task-to-v3.ts`'s `parseLegacyTaskYaml`
+ * exactly). Reading the RAW decoded record — rather than the typed
+ * `parseTaskV3Yaml` — keeps every field's original value bytes (a duration
+ * string, a bare millisecond integer, an env value's exact type) intact for
+ * verbatim re-emission; a typed v3 parse would normalize several of these
+ * away (C-N1).
+ */
+function parseV3RawYaml(input) {
+    if (input.bytes.byteLength > TASK_V3_MAX_SOURCE_BYTES) {
+        throw new Error(`task YAML exceeds the 1 MiB (${TASK_V3_MAX_SOURCE_BYTES}-byte) source resource limit`);
+    }
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input.bytes);
+    }
+    catch {
+        throw new Error("task YAML contains invalid UTF-8 bytes");
+    }
+    const lineCounter = new LineCounter();
+    let document;
+    try {
+        document = parseDocument(source, { lineCounter, uniqueKeys: true });
+    }
+    catch (cause) {
+        throw new Error(`invalid YAML: ${causeMessage(cause)}`);
+    }
+    const [parseError] = document.errors;
+    if (parseError)
+        throw new Error(`invalid YAML: ${parseError.message.split("\n")[0]}`);
+    const [parseWarning] = document.warnings;
+    if (parseWarning)
+        throw new Error(`unsupported YAML construct: ${parseWarning.message}`);
+    assertBoundedTaskYamlDocument(document, {
+        filePath: input.filePath,
+        sourceLabel: "task v3 migration source",
+        lineCounter,
+    });
+    return { data: plainRecord(document.toJS({ maxAliasCount: 0 }), "task YAML"), source };
+}
+/** Convert one already-validated v3 raw record to final task source v4 bytes. */
+function planV3DataToV4(input, data) {
+    const unknownTop = Object.keys(data).filter((key) => !V3_TOP_LEVEL_KEYS.has(key));
+    if (unknownTop.length > 0) {
+        return blocked(input, "invalid-v3-task", `unknown v3 field(s): ${unknownTop.join(", ")}`);
+    }
+    const hasUses = Object.hasOwn(data, "uses");
+    const hasRun = Object.hasOwn(data, "run");
+    if (hasUses === hasRun) {
+        return blocked(input, "invalid-v3-task", "requires exactly one executable selector: uses or run");
+    }
+    let akm;
+    if (Object.hasOwn(data, "akm")) {
+        try {
+            akm = plainRecord(data.akm, "akm");
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        const unknownAkm = Object.keys(akm).filter((key) => !V3_AKM_KEYS.has(key));
+        if (unknownAkm.length > 0) {
+            return blocked(input, "unrecognized-akm-member", `akm has unknown field(s): ${unknownAkm.join(", ")}`);
+        }
+        if (Object.hasOwn(akm, "enabled") && typeof akm.enabled !== "boolean") {
+            return blocked(input, "invalid-v3-task", "akm.enabled must be a boolean");
+        }
+        if (Object.hasOwn(akm, "schedule") && typeof akm.schedule !== "string") {
+            return blocked(input, "invalid-v3-task", "akm.schedule must be a string");
+        }
+    }
+    const hasOn = Object.hasOwn(data, "on");
+    let onRecord;
+    if (hasOn) {
+        try {
+            onRecord = plainRecord(data.on, "on");
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        // Mirrors the frozen v3 reader's own `parseOn` gates exactly
+        // (task-source-v3-frozen.ts:395-427): an empty `on: {}` declares no
+        // trigger at all, and `on.workflow_dispatch` accepts only null or an
+        // empty mapping (inputs are unsupported in v3). The frozen parser
+        // rejects both shapes outright, so this migrator must too — translating
+        // a document the v3 oracle would refuse to parse into runnable v4 bytes
+        // would launder invalid input into a valid, schedule-less task.
+        if (Object.keys(onRecord).length === 0) {
+            return blocked(input, "invalid-v3-task", "on must declare schedule and/or workflow_dispatch.");
+        }
+        const unknownOn = Object.keys(onRecord).filter((key) => !V3_ON_KEYS.has(key));
+        if (unknownOn.length > 0) {
+            return blocked(input, "invalid-v3-task", `on has unknown field(s): ${unknownOn.join(", ")}`);
+        }
+        if (Object.hasOwn(onRecord, "workflow_dispatch") && onRecord.workflow_dispatch !== null) {
+            let dispatchMapping;
+            try {
+                dispatchMapping = plainRecord(onRecord.workflow_dispatch, "on.workflow_dispatch");
+            }
+            catch (cause) {
+                return blocked(input, "invalid-v3-task", causeMessage(cause));
+            }
+            if (Object.keys(dispatchMapping).length > 0) {
+                return blocked(input, "invalid-v3-task", "on.workflow_dispatch must be null or an empty mapping; inputs are unsupported.");
+            }
+        }
+    }
+    const hasAkmSchedule = akm !== undefined && Object.hasOwn(akm, "schedule");
+    if (hasAkmSchedule && hasOn) {
+        return blocked(input, "ambiguous-scheduling-source", "declares both akm.schedule and on:; task v3 requires exactly one scheduling source and the migrator will not guess which one wins.");
+    }
+    if (!hasAkmSchedule && !hasOn) {
+        return blocked(input, "invalid-v3-task", "requires exactly one scheduling source: akm.schedule or on.");
+    }
+    const hasWith = Object.hasOwn(data, "with");
+    let usesTarget;
+    if (hasUses) {
+        let usesValue;
+        try {
+            usesValue = exactString(data.uses, "uses", true);
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        try {
+            usesTarget = classifyTaskV3Uses(usesValue);
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        if (usesTarget.kind === "github-action") {
+            return blocked(input, "github-action-target-removed", `"${usesValue}" is a github-action target; the github-action uses: variant was removed in task source v4. Use commands/, scripts/, workflows/, or akm/command instead.`);
+        }
+        if (hasWith && usesTarget.kind !== "builtin-command") {
+            return blocked(input, "with-on-non-command-target", `a with: block on "${usesValue}" (a non-akm/command target) has no task source v4 equivalent; task-call inputs are declared and bound separately.`);
+        }
+    }
+    else if (hasWith) {
+        return blocked(input, "invalid-v3-task", "with is legal only with uses");
+    }
+    if (!input.writable || input.onDiskWritable === false) {
+        return blocked(input, "read-only-source", !input.writable ? "the owning source is not writable" : "the source file or publication directory is read-only");
+    }
+    const enabledFalse = akm !== undefined && akm.enabled === false;
+    let scheduleField;
+    // Several independent translation facts can need reporting on the SAME
+    // file (a manual-only trigger AND a dropped output schema, say), so
+    // notices accumulate and are joined into the single `notice` string the
+    // outcome carries.
+    const notices = [];
+    if (hasAkmSchedule) {
+        const cron = akm.schedule;
+        scheduleField = enabledFalse ? [{ cron, enabled: false }] : cron;
+    }
+    else {
+        const rawSchedule = onRecord !== undefined && Object.hasOwn(onRecord, "schedule") ? onRecord.schedule : undefined;
+        if (rawSchedule !== undefined) {
+            if (!Array.isArray(rawSchedule) || rawSchedule.length === 0) {
+                return blocked(input, "invalid-v3-task", "on.schedule must be a non-empty list of {cron} records");
+            }
+            const crons = [];
+            for (const entry of rawSchedule) {
+                let record;
+                try {
+                    record = plainRecord(entry, "on.schedule[]");
+                }
+                catch (cause) {
+                    return blocked(input, "invalid-v3-task", causeMessage(cause));
+                }
+                const keys = Object.keys(record);
+                if (keys.length !== 1 || keys[0] !== "cron" || typeof record.cron !== "string" || record.cron.length === 0) {
+                    return blocked(input, "invalid-v3-task", "each on.schedule entry must be exactly {cron: <non-empty string>}");
+                }
+                crons.push(record.cron);
+            }
+            scheduleField = crons.map((cron) => (enabledFalse ? { cron, enabled: false } : { cron }));
+        }
+        else if (enabledFalse) {
+            return blocked(input, "enabled-false-has-no-schedule-entry", "akm.enabled: false has no schedule entry to attach to (the only trigger is on.workflow_dispatch); task source v4 has no top-level enabled flag.");
+        }
+        else {
+            notices.push("schedule: is absent from the migrated document — the source's only trigger was on.workflow_dispatch (manual dispatch); task source v4 tasks are always runnable manually via `akm task run`, so no schedule: entry was emitted.");
+        }
+    }
+    const out = { version: 4 };
+    if (Object.hasOwn(data, "name"))
+        out.name = data.name;
+    if (hasUses)
+        out.uses = data.uses;
+    else
+        out.run = data.run;
+    if (Object.hasOwn(data, "shell"))
+        out.shell = data.shell;
+    if (hasWith)
+        out.with = data.with;
+    if (Object.hasOwn(data, "env"))
+        out.env = data.env;
+    if (Object.hasOwn(data, "working-directory"))
+        out["working-directory"] = data["working-directory"];
+    if (scheduleField !== undefined)
+        out.schedule = scheduleField;
+    if (akm) {
+        for (const key of AKM_HOIST_KEYS) {
+            if (Object.hasOwn(akm, key))
+                out[key] = akm[key];
+        }
+        // v3's `akm.outputSchema: null` means "no schema" (accepted verbatim by
+        // the frozen v3 reader, task-source-v3-frozen.ts:256-258); v4's
+        // `output:` has no null form (parseOutputSchema always requires a
+        // mapping). Omitting the key is the faithful v4 equivalent of an
+        // explicit v3 null — emitting `output: null` would fail the real
+        // parseTaskSourceV4 validation below and block the whole file.
+        if (Object.hasOwn(akm, "outputSchema") && akm.outputSchema !== null) {
+            // v4 accepts `output:` ONLY on a command target — `uses: commands/<ref>`
+            // or `uses: akm/command` (src/tasks/source/task-source-v4.ts's
+            // `targetConsumesOutputSchema`). v3 enforced no such rule: the frozen v3
+            // reader accepts `akm.outputSchema` on ANY target kind
+            // (task-source-v3-frozen.ts:256-263), and on `run:`/`uses: scripts/`/
+            // `uses: workflows/` it was equally inert there — nothing ever consumed
+            // it. Hoisting it unconditionally would therefore emit bytes the real
+            // parseTaskSourceV4 below rejects, blocking a valid, previously-runnable
+            // v3 file — and one blocked file aborts the whole plan
+            // (`applyTaskToV4MigrationPlan`, ./task-files-to-v4.ts). Dropping an
+            // already-inert field and SAYING SO is the faithful translation, and
+            // keeps spec row B-66 / §5.3's `changed` guarantee intact.
+            if (usesTarget !== undefined && (usesTarget.kind === "command" || usesTarget.kind === "builtin-command")) {
+                out.output = akm.outputSchema;
+            }
+            else {
+                const targetLabel = usesTarget === undefined ? "a run: target" : `the "${usesTarget.ref}" target`;
+                notices.push(`akm.outputSchema was dropped rather than hoisted to output: — task source v4 accepts output: only with a command target (uses: commands/<ref> or uses: akm/command), and ${targetLabel} never consumed the schema in v3 either, so nothing enforceable was lost.`);
+            }
+        }
+    }
+    const afterYaml = stringifyYaml(out);
+    const after = Buffer.from(afterYaml, "utf8");
+    try {
+        parseTaskSourceV4({
+            yaml: afterYaml,
+            filePath: input.filePath,
+            ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+        });
+    }
+    catch (cause) {
+        return blocked(input, "generated-v4-validation-failed", causeMessage(cause));
+    }
+    const notice = notices.join(" ");
+    return Object.freeze({
+        status: "changed",
+        ...base(input),
+        reason: "task-converted",
+        after,
+        afterHash: hash(after),
+        ...(notice ? { notice } : {}),
+    });
+}
+/** Plan exactly one source file without touching disk. */
+export function planTaskToV4File(input) {
+    let data;
+    let source;
+    try {
+        ({ data, source } = parseV3RawYaml(input));
+    }
+    catch (cause) {
+        return blocked(input, "invalid-task-yaml", causeMessage(cause));
+    }
+    if (data.version === 4) {
+        try {
+            parseTaskSourceV4({
+                yaml: source,
+                filePath: input.filePath,
+                ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+            });
+            return Object.freeze({ status: "skipped", ...base(input), reason: "already-v4" });
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v4-task", causeMessage(cause));
+        }
+    }
+    // Not this generation's document to validate — v2 grammar is entirely
+    // generation 1's domain (task-to-v3.ts). Reported skipped, not blocked
+    // (see TaskToV4Skipped's own header).
+    if (data.version === 2) {
+        return Object.freeze({
+            status: "skipped",
+            ...base(input),
+            reason: "pending-v2-to-v3-migration",
+        });
+    }
+    if (data.version !== 3) {
+        return blocked(input, "unsupported-task-version", `expected version 2, 3, or 4, got ${String(data.version)}`);
+    }
+    return planV3DataToV4(input, data);
+}
+function generationFor(files) {
+    const digest = crypto.createHash("sha256");
+    digest.update("akm-task-to-v4-plan-v1\0");
+    for (const file of files) {
+        digest.update(file.filePath);
+        digest.update("\0");
+        digest.update(file.status);
+        digest.update("\0");
+        digest.update(file.reason);
+        digest.update("\0");
+        digest.update(String(file.mode));
+        digest.update("\0");
+        digest.update(file.writable ? "writable" : "read-only");
+        digest.update("\0");
+        digest.update(file.onDiskWritable === false ? "disk-read-only" : "disk-writable-or-unspecified");
+        digest.update("\0");
+        if (file.containmentRoot)
+            digest.update(file.containmentRoot);
+        digest.update("\0");
+        digest.update(file.beforeHash);
+        digest.update("\0");
+        if (file.status === "changed")
+            digest.update(file.afterHash);
+        digest.update("\0");
+        if (file.detail)
+            digest.update(file.detail);
+        digest.update("\0");
+        if (file.status === "changed" && file.notice)
+            digest.update(file.notice);
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+/** Build/fingerprint a plan from already-derived immutable outcomes. */
+export function taskToV4PlanFromOutcomes(outcomes) {
+    const files = [...outcomes].sort((left, right) => left.filePath < right.filePath ? -1 : left.filePath > right.filePath ? 1 : 0);
+    for (let index = 1; index < files.length; index += 1) {
+        const previous = files[index - 1];
+        const current = files[index];
+        if (previous && current && path.resolve(previous.filePath) === path.resolve(current.filePath)) {
+            throw new Error(`duplicate task migration file path: ${current.filePath}`);
+        }
+    }
+    return Object.freeze({ schemaVersion: 1, generation: generationFor(files), files: Object.freeze(files) });
+}
+/** Plan a complete, stable file set. Input order cannot change the result. */
+export function planTaskToV4Migration(inputs) {
+    const sorted = [...inputs].sort((left, right) => left.filePath < right.filePath ? -1 : left.filePath > right.filePath ? 1 : 0);
+    let previous;
+    for (const current of sorted) {
+        if (previous && path.resolve(previous.filePath) === path.resolve(current.filePath)) {
+            throw new Error(`duplicate task migration file path: ${current.filePath}`);
+        }
+        previous = current;
+    }
+    return taskToV4PlanFromOutcomes(sorted.map(planTaskToV4File));
+}

package/docs/reference/cli.md

@@ -393,6 +393,11 @@ availability:
 - **`origin`** -- The source bundle (e.g. `npm:@scope/pkg`), present only for
   managed source assets; surfaced at `full` only
 - **`id`** -- Registry-level identifier (registry hits only)
+- **`matchStage`** -- Which stage of the progressive AND->OR lexical search
+  ladder produced the hit: `exact` (strict AND), `prefix` (prefix AND), or
+  `relaxed` (OR/prefix-OR recovery). Omitted for hits with no FTS component
+  (e.g. a pure-semantic hybrid match) and for registry hits; surfaced at
+  `normal`, `full`, and `--shape agent`
 
 The default brief shape is intentionally small. The exact field set per
 detail level (and per `--shape`) is authoritative in
@@ -402,9 +407,9 @@ assembled into the shape registry by the `src/output/shapes.ts` barrel:
 | Level | Local bundle hits | Registry hits |
 | --- | --- | --- |
 | `brief` (default) | `type`, `name`, `ref`, `action`, `estimatedTokens` | `name`, `installRef`, `score` |
-| `normal` | `type`, `name`, `description`, `action`, `score`, `estimatedTokens`, optional `warnings`/`quality`/`keys` | `name`, `description`, `action`, `installRef`, `score`, optional `warnings` |
-| `full` | full hit object (includes `ref`, `origin`, `tags`, `whyMatched`, optional `warnings`, optional `quality`, timings, bundle metadata) | full hit object |
-| `--shape agent` | `name`, `ref`, `type`, `path`, `editable`, conditional `editHint`, `description`, `action`, `score`, optional `estimatedTokens`/`keys` | no local access fields |
+| `normal` | `type`, `name`, `description`, `action`, `score`, `estimatedTokens`, optional `warnings`/`quality`/`keys`/`matchStage` | `name`, `description`, `action`, `installRef`, `score`, optional `warnings` |
+| `full` | full hit object (includes `ref`, `origin`, `tags`, `whyMatched`, optional `warnings`, optional `quality`, optional `matchStage`, timings, bundle metadata) | full hit object |
+| `--shape agent` | `name`, `ref`, `type`, `path`, `editable`, conditional `editHint`, `description`, `action`, `score`, optional `estimatedTokens`/`keys`/`matchStage` | no local access fields |
 
 `--shape summary` is **not valid on `search`** — see
 [`--shape summary`](#--shape-summary) above; it is a usage error (exit 2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "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": [
@@ -36,7 +36,7 @@
   "license": "MPL-2.0",
   "pinNotes": {
     "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for.",
-    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so akm's supported Node 24 line installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
+    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so every Node akm supports installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
     "@huggingface/transformers@4.2.0": "Exact semantic-search dependency pin. Re-run the real-model semantic gate before changing it."
   },
   "files": [
@@ -66,7 +66,7 @@
     "akm-migrate": "dist/akm-migrate"
   },
   "scripts": {
-    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=24;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 24.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -114,7 +114,7 @@
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",