akm-cli 0.9.0-rc.2 → 0.9.0-rc.3

package/dist/setup/detected-engines.js

@@ -1,8 +1,6 @@
 // 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 { createHash } from "node:crypto";
-import { ConfigError } from "../core/errors.js";
 const CHAT_SUFFIX = "/chat/completions";
 export function normalizeChatCompletionsEndpoint(input) {
     const url = new URL(input);
@@ -84,19 +82,13 @@ function availableName(config, preferred, fingerprint) {
             return name;
     }
     const base = slug(preferred);
-    const expectedKind = fingerprint.startsWith("llm:") ? "llm" : "agent";
-    const baseEngine = config.engines?.[base];
-    if (baseEngine && baseEngine.kind !== expectedKind) {
-        throw new ConfigError(`Detected ${expectedKind} engine name ${JSON.stringify(base)} conflicts with configured ${baseEngine.kind} engine of the same name. Rename one engine before rerunning setup.`, "INVALID_CONFIG_FILE");
-    }
     if (!config.engines?.[base])
         return base;
-    const suffix = createHash("sha256").update(fingerprint).digest("hex").slice(0, 8);
-    const candidate = `${base}-${suffix}`;
-    const collision = config.engines?.[candidate];
-    if (!collision || engineFingerprint(collision) === fingerprint)
-        return candidate;
-    throw new ConfigError(`Detected engine identity collision at ${JSON.stringify(candidate)}. Choose an explicit engine name before rerunning setup.`, "INVALID_CONFIG_FILE");
+    for (let suffix = 2;; suffix++) {
+        const candidate = `${base}-${suffix}`;
+        if (!config.engines?.[candidate])
+            return candidate;
+    }
 }
 /** Insert or reuse an LLM engine by canonical endpoint without modifying a match. */
 export function upsertDetectedLlmEngine(config, candidate) {
@@ -123,6 +115,8 @@ export function upsertDetectedLlmEngine(config, candidate) {
         (config.engines?.[currentDefault] && engineFingerprint(config.engines[currentDefault]) === fingerprint)) {
         defaults.llmEngine = name;
     }
+    if (!defaults.engine)
+        defaults.engine = defaults.llmEngine ?? name;
     return { config: { ...config, engines, defaults }, name, reused };
 }
 /** Insert or reuse an agent engine by canonical platform without modifying a match. */

package/dist/setup/engine-config.js

@@ -35,6 +35,8 @@ export function writeLlmEngine(config, llm) {
             delete engines[name];
         const defaults = { ...(config.defaults ?? {}) };
         delete defaults.llmEngine;
+        if (defaults.engine === name)
+            delete defaults.engine;
         return { engines, defaults };
     }
     if (config.engines?.[name] && config.engines[name].kind !== "llm") {
@@ -54,7 +56,7 @@ export function writeLlmEngine(config, llm) {
                 ...(capabilities?.structuredOutput !== undefined ? { supportsJsonSchema: capabilities.structuredOutput } : {}),
             },
         },
-        defaults: { ...(config.defaults ?? {}), llmEngine: name },
+        defaults: { ...(config.defaults ?? {}), engine: config.defaults?.engine ?? name, llmEngine: name },
     };
 }
 /** Merge setup-selected agent engines without translating profile-shaped data. */
@@ -66,9 +68,17 @@ export function writeAgentEngines(config, selection) {
         }
     }
     const defaults = { ...(config.defaults ?? {}) };
-    if (!selection?.default)
-        delete defaults.engine;
-    else
+    if (selection?.disabled) {
+        const currentDefault = defaults.engine;
+        if (currentDefault && config.engines?.[currentDefault]?.kind === "agent") {
+            const llmDefault = defaults.llmEngine;
+            if (llmDefault && config.engines?.[llmDefault]?.kind === "llm")
+                defaults.engine = llmDefault;
+            else
+                delete defaults.engine;
+        }
+    }
+    if (selection?.default)
         defaults.engine = selection.default;
     const engines = { ...(config.engines ?? {}), ...(selection?.engines ?? {}) };
     if (selection?.default && engines[selection.default] && engines[selection.default].kind !== "agent") {

package/dist/setup/setup.js

@@ -430,7 +430,7 @@ export async function runSetupWizard(opts) {
     const registries = newConfig.registries;
     const allStashes = newConfig.sources ?? [];
     // Feature capability summary
-    const agentConfigured = Boolean(agentConfig);
+    const agentConfigured = Boolean(agentConfig && !agentConfig.disabled);
     printCapabilitySummary(smallModelResult.skipped, agentConfigured);
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];

package/dist/setup/steps/connection.js

@@ -653,7 +653,7 @@ export async function stepAgentConnection(current, smallModel) {
             "",
             "You can configure this later with `akm setup`.",
         ].join("\n"), "Warning");
-        return undefined;
+        return { disabled: true };
     }
     if (agentChoice === "same-connection") {
         if (smallModel.skipped || !smallModel.llm) {

package/dist/setup/steps/tasks.js

@@ -56,7 +56,7 @@ const DEFAULT_SCHEDULED_TASKS_DEPS = {
     gitSync: saveGitStash,
 };
 export async function stepScheduledTasks(deps = DEFAULT_SCHEDULED_TASKS_DEPS) {
-    const embedded = listEmbeddedTasks();
+    const embedded = listEmbeddedTasks().filter((task) => task.enabled);
     if (embedded.length === 0)
         return;
     // Snapshot current state so we can diff against the user's selection.

package/dist/sources/providers/git-stash.js

@@ -22,6 +22,27 @@ import { getCachePaths, parseGitRepoUrl } from "./git-provider.js";
 export function isGitBackedStash(stashDir) {
     return fs.existsSync(path.join(stashDir, ".git"));
 }
+/** Return repo-relative dirty/staged paths without changing the index. */
+export function listGitChangedPaths(repoDir) {
+    const result = runGit(["-C", repoDir, "status", "--porcelain", "-z", "--untracked-files=all"]);
+    if (result.status !== 0)
+        return [];
+    const records = result.stdout.split("\0");
+    const paths = [];
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        if (!record)
+            continue;
+        const status = record.slice(0, 2);
+        paths.push(record.slice(3));
+        if (status.includes("R") || status.includes("C")) {
+            const previousPath = records[++i];
+            if (previousPath)
+                paths.push(previousPath);
+        }
+    }
+    return paths;
+}
 /**
  * Resolve the writable-override flag for an end-of-run / `akm sync` commit on
  * the primary stash. Returns `true` when the root config explicitly marks the
@@ -110,16 +131,25 @@ export function saveGitStash(name, message, writableOverride, options) {
     //   2. Managed pathspecs (TYPE_DIRS values + `.akm`) that exist on disk —
     //      stages everything akm owns and, by construction, never stages non-akm
     //      WIP. This preserves the #476 protection WITHOUT refusing.
-    //   3. Last-resort `git add -A` — ONLY when neither an explicit list nor any
-    //      managed pathspec can be resolved. This is the maintainer-approved
-    //      "or all files if we cannot determine the exact file list" fallback and
-    //      is the one (rare) path that could include unrelated non-akm files.
-    if (!stageScopedChanges(repoDir, options?.paths)) {
+    //   3. No resolvable managed path — no commit. Broad staging is never safe
+    //      because it can absorb unrelated work already present in the index.
+    const staged = stageScopedChanges(repoDir, options?.paths);
+    if (!staged.ok) {
         throw new Error(`git add failed while staging akm changes in ${repoDir}`);
     }
+    if (staged.pathspecs && staged.pathspecs.length === 0) {
+        return { committed: false, pushed: false, skipped: false, output: "nothing to commit" };
+    }
     // Nothing actually staged → don't create an empty commit. This happens when
     // only non-akm files were dirty (precedence 2 staged nothing).
-    const stagedResult = runGit(["-C", repoDir, "diff", "--cached", "--quiet"]);
+    const stagedResult = runGit([
+        "-C",
+        repoDir,
+        "diff",
+        "--cached",
+        "--quiet",
+        ...(staged.pathspecs ? ["--", ...staged.pathspecs] : []),
+    ]);
     if (stagedResult.status === 0) {
         return { committed: false, pushed: false, skipped: false, output: "nothing to commit" };
     }
@@ -135,6 +165,7 @@ export function saveGitStash(name, message, writableOverride, options) {
         "commit",
         "-m",
         commitMessage,
+        ...(staged.pathspecs ? ["--only", "--", ...staged.pathspecs] : []),
     ]);
     if (commitResult.status !== 0) {
         throw new Error(`git commit failed: ${commitResult.stderr?.trim() || "unknown error"}`);
@@ -161,34 +192,40 @@ export function saveGitStash(name, message, writableOverride, options) {
 }
 /**
  * Stage akm's changes in `repoDir` using the scoped-staging precedence
- * documented at the call site (#476). Returns `false` only when a `git add`
- * subprocess fails; returns `true` otherwise (including when nothing matched —
- * the caller then detects "nothing staged" via `git diff --cached --quiet`).
+ * documented at the call site (#476). The returned pathspecs are reduced to
+ * exact staged files so `git commit --only` cannot absorb unrelated index state.
  *
  * @param paths Optional explicit repo-relative paths akm wrote this run. When
  *   provided and non-empty, exactly those are staged (chunked to stay under
  *   argv length limits). Otherwise we fall back to the managed pathspecs, and
- *   finally to `git add -A` only if no managed pathspec exists on disk.
+ *   skip the commit when no managed pathspec exists on disk.
  */
 function stageScopedChanges(repoDir, paths) {
+    if (paths !== undefined && paths.length === 0)
+        return { ok: true, pathspecs: [] };
     // Precedence 1: explicit modified-file list.
     const explicit = (paths ?? []).filter((p) => typeof p === "string" && p.length > 0);
     if (explicit.length > 0) {
-        return addPathspecsChunked(repoDir, explicit);
+        const ok = addPathspecsChunked(repoDir, explicit);
+        return { ok, pathspecs: ok ? listStagedPaths(repoDir, explicit) : [] };
     }
     // Precedence 2: managed pathspecs that exist on disk (TYPE_DIRS + `.akm`).
     const managed = [...Object.values(TYPE_DIRS), ".akm"].filter((dir) => fs.existsSync(path.join(repoDir, dir)));
     if (managed.length > 0) {
-        return addPathspecsChunked(repoDir, managed);
-    }
-    // Precedence 3 (last resort): nothing akm-managed resolved on disk. Stage
-    // everything. This is the ONLY branch that can include unrelated non-akm
-    // files — it is the explicit, maintainer-approved "or all files if we cannot
-    // determine the exact file list" fallback and should be rare/never in
-    // practice (a git-backed stash always has at least one managed subtree once
-    // akm has written to it).
-    const addAll = runGit(["-C", repoDir, "add", "-A"]);
-    return addAll.status === 0;
+        const ok = addPathspecsChunked(repoDir, managed);
+        return { ok, pathspecs: ok ? listStagedPaths(repoDir, managed) : [] };
+    }
+    // No managed target means there is no safe commit scope.
+    return { ok: true, pathspecs: [] };
+}
+function listStagedPaths(repoDir, pathspecs) {
+    const result = runGit(["-C", repoDir, "diff", "--cached", "--name-only", "--", ...pathspecs]);
+    if (result.status !== 0)
+        return [];
+    return result.stdout
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
 }
 /**
  * Run `git add -- <pathspec>...` in chunks so a very large path list never

package/dist/sources/providers/git.js

@@ -10,4 +10,4 @@
 // keeps importing from a single module namespace.
 export { classifyCloneFailure, cloneRepo, syncRegistryGitRef } from "./git-install.js";
 export { ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl, syncMirroredRepo, } from "./git-provider.js";
-export { isGitBackedStash, resolveWritableOverride, saveGitStash, } from "./git-stash.js";
+export { isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "./git-stash.js";

package/dist/storage/engines/sqlite-migrations.js

@@ -1,6 +1,115 @@
 // 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/.
+/**
+ * Shared SQLite migration engine.
+ *
+ * state.db (`src/core/state-db.ts`) and workflow.db (`src/workflows/db.ts`)
+ * both evolve their schema through an identical, idempotent, transaction-per-
+ * migration runner backed by a `schema_migrations` ledger. The two runners
+ * were byte-identical except for ONE line: workflow.db must back-fill a
+ * `schema_migrations` row for pre-versioning databases before evaluating the
+ * migration list (see `bootstrapPreVersioningDb` in workflows/db.ts).
+ *
+ * This module factors that runner out once. Each DB module supplies only its
+ * own `MIGRATIONS` array; workflow.db additionally passes a `bootstrap` hook.
+ *
+ * Migration-safety contract:
+ *   - `id` is permanent and must never be reused.
+ *   - `up` must be idempotent (use IF NOT EXISTS, INSERT OR IGNORE, etc.).
+ *   - `up` must not DROP any table that holds durable (non-regenerable) data.
+ *   - `up` must not RENAME or change the type of an existing column.
+ *   - To add a column: use `ALTER TABLE … ADD COLUMN … DEFAULT …`.
+ *   - Applied IDs must be an exact ordered prefix of the registry.
+ *   - Released migration bodies are sealed by SHA-256 in the same ledger.
+ */
+import crypto from "node:crypto";
+export function migrationChecksum(migration) {
+    return crypto.createHash("sha256").update(migration.id).update("\0").update(migration.up).digest("hex");
+}
+function migrationsTableExists(db) {
+    return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
+}
+function ledgerHasChecksum(db) {
+    return db.prepare("PRAGMA table_info(schema_migrations)").all().some((column) => column.name === "checksum");
+}
+export function inspectMigrationLedger(db, migrations) {
+    const registryIds = migrations.map((migration) => migration.id);
+    if (new Set(registryIds).size !== registryIds.length) {
+        return {
+            status: "inconsistent",
+            migrationIds: [],
+            checksums: [],
+            detail: "migration registry contains duplicate IDs",
+        };
+    }
+    if (!migrationsTableExists(db))
+        return { status: registryIds.length === 0 ? "current" : "old", migrationIds: [], checksums: [] };
+    const hasChecksum = ledgerHasChecksum(db);
+    const rows = db
+        .prepare(`SELECT id${hasChecksum ? ", checksum" : ""} FROM schema_migrations ORDER BY rowid`)
+        .all();
+    const migrationIds = rows.map((row) => row.id);
+    const checksums = rows.map((row) => row.checksum ?? null);
+    for (let index = 0; index < rows.length; index += 1) {
+        const expected = migrations[index];
+        const row = rows[index];
+        if (!expected) {
+            return { status: "newer", migrationIds, checksums, detail: `unknown migration ID ${row.id}` };
+        }
+        if (row.id !== expected.id) {
+            const knownLater = registryIds.includes(row.id);
+            return {
+                status: knownLater ? "inconsistent" : "newer",
+                migrationIds,
+                checksums,
+                detail: knownLater
+                    ? `migration ledger is not an exact ordered prefix at position ${index + 1}`
+                    : `unknown migration ID ${row.id}`,
+            };
+        }
+        const expectedChecksum = migrationChecksum(expected);
+        if (row.checksum && row.checksum !== expectedChecksum) {
+            return {
+                status: "inconsistent",
+                migrationIds,
+                checksums,
+                detail: `migration ${row.id} checksum does not match the released migration body`,
+            };
+        }
+    }
+    const missingChecksum = checksums.indexOf(null);
+    if (missingChecksum >= 0) {
+        return {
+            status: "old",
+            migrationIds,
+            checksums,
+            detail: `migration ${migrationIds[missingChecksum]} has not been sealed with a checksum`,
+        };
+    }
+    return {
+        status: rows.length === migrations.length ? "current" : "old",
+        migrationIds,
+        checksums,
+    };
+}
+export function assertMigrationLedger(db, migrations) {
+    const state = inspectMigrationLedger(db, migrations);
+    if (state.status === "newer") {
+        throw new Error(`Refusing to open a database with a newer migration ledger: ${state.detail}.`);
+    }
+    if (state.status === "inconsistent") {
+        throw new Error(`Refusing a database whose migrations are not an exact ordered prefix: ${state.detail}.`);
+    }
+    return state;
+}
+export function assertCurrentMigrationLedger(db, migrations) {
+    const state = assertMigrationLedger(db, migrations);
+    if (state.status !== "current") {
+        throw new Error(`Refusing to open an obsolete writable schema; run \`akm migrate apply\`: ${state.detail ?? "pending migrations"}.`);
+    }
+    return state;
+}
 /**
  * Create the migrations ledger table if it does not exist. Must be called
  * unconditionally on every open so a fresh database bootstraps correctly.
@@ -9,9 +118,12 @@ export function ensureMigrationsTable(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
       id         TEXT    PRIMARY KEY,
-      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now')),
+      checksum   TEXT
     );
   `);
+    if (!ledgerHasChecksum(db))
+        db.exec("ALTER TABLE schema_migrations ADD COLUMN checksum TEXT");
 }
 /**
  * Apply every pending migration, one transaction per migration.
@@ -27,9 +139,32 @@ export function ensureMigrationsTable(db) {
  * @param opts        Optional `bootstrap` hook (see {@link RunMigrationsOptions}).
  */
 export function runMigrations(db, migrations, opts) {
+    if (opts?.applyPending === false) {
+        assertMigrationLedger(db, migrations);
+        return;
+    }
+    if (migrationsTableExists(db))
+        assertMigrationLedger(db, migrations);
     ensureMigrationsTable(db);
     opts?.bootstrap?.(db);
-    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
+    const ledger = assertMigrationLedger(db, migrations);
+    db.transaction(() => {
+        const update = db.prepare("UPDATE schema_migrations SET checksum = ? WHERE id = ? AND checksum IS NULL");
+        for (let index = 0; index < ledger.migrationIds.length; index += 1) {
+            update.run(migrationChecksum(migrations[index]), ledger.migrationIds[index]);
+        }
+        if (opts?.generationMarker) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS akm_migration_generation (
+          singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+          operation_id TEXT NOT NULL,
+          phase TEXT NOT NULL
+        )
+      `);
+            db.prepare("INSERT INTO akm_migration_generation(singleton, operation_id, phase) VALUES (1, ?, ?) ON CONFLICT(singleton) DO UPDATE SET operation_id=excluded.operation_id, phase=excluded.phase").run(opts.generationMarker.operationId, opts.generationMarker.phase);
+        }
+    })();
+    const appliedRows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
     const applied = new Set(appliedRows.map((r) => r.id));
     for (const migration of migrations) {
         if (applied.has(migration.id))
@@ -37,7 +172,7 @@ export function runMigrations(db, migrations, opts) {
         opts?.beforeMigration?.(migration);
         db.transaction(() => {
             db.exec(migration.up);
-            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+            db.prepare("INSERT INTO schema_migrations (id, checksum) VALUES (?, ?)").run(migration.id, migrationChecksum(migration));
         })();
     }
 }

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

@@ -51,6 +51,30 @@ export function insertEvent(db, input) {
         return undefined;
     }
 }
+/** Strict idempotent event insert for durable mutation journals. */
+export function insertEventOnce(db, input) {
+    const rows = db
+        .prepare("SELECT id, metadata_json FROM events WHERE event_type = ? AND ref IS ? ORDER BY id")
+        .all(input.eventType, input.ref ?? null);
+    for (const row of rows) {
+        try {
+            const metadata = JSON.parse(row.metadata_json);
+            if (metadata[input.idempotencyMetadataKey ?? "proposalTransactionId"] === input.idempotencyKey)
+                return row.id;
+        }
+        catch {
+            // Corrupt unrelated event metadata cannot satisfy this idempotency key.
+        }
+    }
+    const result = db
+        .prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
+       VALUES (?, ?, ?, ?)
+       RETURNING id`)
+        .get(input.eventType, input.ts, input.ref ?? null, JSON.stringify(input.metadata));
+    if (!result)
+        throw new Error(`Failed to persist ${input.eventType} event.`);
+    return result.id;
+}
 /**
  * Read events from the database matching the filter. Returns events in
  * ascending id order so consumers can process them in emission order.

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

@@ -37,6 +37,10 @@ export function proposalRowToProposal(row) {
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
+        ...(typeof meta.acceptedContentHash === "string" ? { acceptedContentHash: meta.acceptedContentHash } : {}),
+        ...(meta.acceptedTarget !== undefined ? { acceptedTarget: meta.acceptedTarget } : {}),
+        ...(meta.legacyAcceptedTargetDerived === true ? { legacyAcceptedTargetDerived: true } : {}),
+        ...(meta.legacyAcceptedAssetWasAbsent === true ? { legacyAcceptedAssetWasAbsent: true } : {}),
         ...(typeof meta.eligibilitySource === "string"
             ? { eligibilitySource: meta.eligibilitySource }
             : {}),
@@ -59,6 +63,16 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.gateDecision = proposal.gateDecision;
     if (proposal.backupContent !== undefined)
         metaObj.backupContent = proposal.backupContent;
+    if (proposal.acceptedContentHash !== undefined)
+        metaObj.acceptedContentHash = proposal.acceptedContentHash;
+    if (proposal.acceptedTarget !== undefined)
+        metaObj.acceptedTarget = proposal.acceptedTarget;
+    if (proposal.legacyAcceptedTargetDerived !== undefined) {
+        metaObj.legacyAcceptedTargetDerived = proposal.legacyAcceptedTargetDerived;
+    }
+    if (proposal.legacyAcceptedAssetWasAbsent !== undefined) {
+        metaObj.legacyAcceptedAssetWasAbsent = proposal.legacyAcceptedAssetWasAbsent;
+    }
     if (proposal.eligibilitySource !== undefined)
         metaObj.eligibilitySource = proposal.eligibilitySource;
     return {

package/dist/tasks/embedded.js

@@ -58,12 +58,14 @@ export function listEmbeddedTasks() {
         const command = typeof doc.command === "string" ? doc.command : "";
         const schedule = typeof doc.schedule === "string" ? doc.schedule : "";
         const description = typeof doc.description === "string" ? doc.description : "";
+        const enabled = doc.enabled !== false;
         tasks.push({
             id,
             label: `core/${id}`,
             command,
             schedule,
             description,
+            enabled,
             yaml,
         });
     }

package/dist/workflows/db.js

@@ -4,10 +4,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { acquireMaintenanceActivitySync } from "../core/maintenance-barrier.js";
-import { ensureMigrationBackup, getMigrationBackupDir } from "../core/migration-backup.js";
+import { assertNoPendingMigrationOperation } from "../core/migration-operation.js";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
-import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { assertCurrentMigrationLedger, assertMigrationLedger, runMigrations as runSqliteMigrations, } from "../storage/engines/sqlite-migrations.js";
 import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 /**
  * workflow.db — Durable SQLite database for workflow run state.
@@ -45,24 +45,37 @@ import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 // ── Public API ───────────────────────────────────────────────────────────────
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const isCanonical = path.resolve(dbPath) === path.resolve(getWorkflowDbPath());
+    if (isCanonical)
+        assertNoPendingMigrationOperation();
     const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("workflow-db") : undefined;
     let db;
     try {
-        // Preserve an originally absent workflow.db in the recovery manifest. SQLite
-        // creates the file at open time, so the cutover bundle must exist first.
-        if (isCanonical && !fs.existsSync(getMigrationBackupDir()))
-            ensureMigrationBackup();
+        if (isCanonical)
+            assertNoPendingMigrationOperation();
+        const existed = fs.existsSync(dbPath);
         const dir = path.dirname(dbPath);
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
+        if (existed) {
+            const preflight = openDatabase(dbPath, { readonly: true });
+            try {
+                if (isCanonical)
+                    assertCurrentMigrationLedger(preflight, WORKFLOW_MIGRATIONS);
+                else
+                    assertMigrationLedger(preflight, WORKFLOW_MIGRATIONS);
+            }
+            finally {
+                preflight.close();
+            }
+        }
         db = openDatabase(dbPath);
         // #589: 30 s busy timeout, matching index.db / state.db. Without it the
         // default is 0 ms, so any concurrent writer fails immediately with
         // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
         applyStandardPragmas(db, { dataDir: dir });
         ensureBaseSchema(db);
-        runMigrations(db, { ensureCutoverBackup: isCanonical });
+        runMigrations(db, { applyPending: !(isCanonical && existed) });
         if (!releaseActivity)
             return db;
         const openedDb = db;
@@ -156,7 +169,7 @@ function ensureBaseSchema(db) {
  * All workflow.db migrations in application order. New migrations are
  * APPENDED — never inserted in the middle or reordered.
  */
-const MIGRATIONS = [
+export const WORKFLOW_MIGRATIONS = [
     // ── Migration 001 — add scope_key column ────────────────────────────────────
     //
     // Adds the `scope_key` column to `workflow_runs` so runs can be partitioned
@@ -392,11 +405,9 @@ function bootstrapPreVersioningDb(db) {
  * Called automatically by {@link openWorkflowDatabase}.
  */
 export function runMigrations(db, options) {
-    runSqliteMigrations(db, MIGRATIONS, {
+    runSqliteMigrations(db, WORKFLOW_MIGRATIONS, {
         bootstrap: bootstrapPreVersioningDb,
-        beforeMigration(migration) {
-            if (options?.ensureCutoverBackup && migration.id === "010-ir-v3-engine")
-                ensureMigrationBackup();
-        },
+        applyPending: options?.applyPending,
+        generationMarker: options?.generationMarker,
     });
 }

package/dist/workflows/validator.js

@@ -8,15 +8,37 @@
  * the whole document or the raw frontmatter at once: duplicate step IDs,
  * step-id format, and the frontmatter key whitelist.
  */
+import { parseAssetRef, refToString } from "../core/asset/asset-ref.js";
 import { utf8Bytes, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_STEPS } from "./resource-limits.js";
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use"]);
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use", "xrefs"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
+    checkXrefs(frontmatterData.xrefs, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);
     checkDuplicateStepIds(draft, errors);
     checkResourceLimits(draft, errors);
 }
+function checkXrefs(value, line, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push({ line, message: 'Workflow frontmatter "xrefs" must be an array of canonical asset refs.' });
+        return;
+    }
+    for (const ref of value) {
+        try {
+            if (typeof ref !== "string" || refToString(parseAssetRef(ref)) !== ref)
+                throw new Error("non-canonical ref");
+        }
+        catch {
+            errors.push({
+                line,
+                message: `Workflow frontmatter "xrefs" contains an invalid or non-canonical ref: ${String(ref)}.`,
+            });
+        }
+    }
+}
 function checkResourceLimits(draft, errors) {
     if (draft.steps.length > WORKFLOW_MAX_STEPS) {
         errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
@@ -39,7 +61,7 @@ function checkFrontmatterKeys(data, fmEndLine, errors) {
             continue;
         errors.push({
             line: fmEndLine,
-            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use.`,
+            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use, xrefs.`,
         });
     }
 }