akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/storage/sqlite-transaction.js

@@ -0,0 +1,170 @@
+// 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/.
+/**
+ * `BEGIN IMMEDIATE` transactions and the one SQLite contention classifier.
+ *
+ * `db.transaction()` is DEFERRED by default on both Bun and better-sqlite3,
+ * which means two writers can both perform stale preflight reads and only race
+ * when they finally attempt the write. Proposal creation, queue mutation and
+ * schema migration need the write lock BEFORE those reads so concurrent
+ * processes serialize on the live state rather than clobbering each other.
+ *
+ * Every open already carries a 30 s `busy_timeout` (`sqlite-pragmas.ts`), so a
+ * single blocked statement waits before failing. {@link beginImmediateTransaction}
+ * additionally retries `BEGIN IMMEDIATE` itself ({@link WITH_IMMEDIATE_TX_MAX_ATTEMPTS}
+ * attempts) for the rarer case of two writers racing the BEGIN statement
+ * back-to-back. If every attempt is still contention-shaped
+ * ({@link isSqliteContentionError} — SQLITE_BUSY/LOCKED, the matching message
+ * text, or the phantom-BEGIN marker), the exhaustion throw is reclassified
+ * into `TransientError("STATE_DB_CONTENDED")` (exit 75, #948 addendum) instead
+ * of surfacing the raw driver text: another akm process (an unrelated
+ * `improve`, `workflow run`, or task run — not necessarily contending for the
+ * same row) is writing the database right now. A genuinely unrelated error
+ * (real corruption, a body-thrown failure) is never reclassified and rethrows
+ * exactly as raised.
+ *
+ * This is the single place SQLITE_BUSY/LOCKED becomes exit 75 for state.db:
+ * `openStateDatabase`'s migration transaction, every repository write and the
+ * shared migration runner (`engines/sqlite-migrations.ts`) all go through it.
+ * `core/state-db.ts` re-exports these helpers for its callers.
+ *
+ * @module storage/sqlite-transaction
+ */
+import { TransientError } from "../core/errors.js";
+import { sleepSync } from "../runtime.js";
+/**
+ * Whether `err` is one of the SQLite conditions a concurrent-writer race can
+ * throw that are transient — the statement did NOT corrupt anything, another
+ * writer just holds the lock right now — and therefore safe to retry or
+ * reclassify as ordinary contention rather than a genuine failure:
+ *   - `SQLITE_BUSY` / `SQLITE_LOCKED` (either driver's `.code`).
+ *   - "database is locked" / "database table is locked" message text.
+ *   - the phantom-BEGIN marker synthesized below when `BEGIN IMMEDIATE`
+ *     returns without actually opening a transaction.
+ *
+ * This is the single shared classifier for "is this ordinary contention"
+ * (#948): `reclassifyIndexDbContention` (indexer) and the workflow-runs
+ * repository's lease-contention classifier (which additionally matches a
+ * couple of corruption-shaped texts specific to its own narrower cross-process
+ * race and keeps its own live-lease confirmation before reclassifying) both
+ * delegate to it. Matching this set alone is never sufficient to declare
+ * something DEFINITELY contention when a caller needs corroborating evidence
+ * (see the lease path); for `beginImmediateTransaction`'s own exhaustion case
+ * there is no such evidence available, so the five 30 s `busy_timeout` waits
+ * already spent stand as the evidence instead.
+ */
+export function isSqliteContentionError(err) {
+    const code = err?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+        return true;
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes("database is locked") ||
+        msg.includes("database table is locked") ||
+        // Phantom BEGIN (see below) — synthesized when BEGIN IMMEDIATE returns
+        // without opening a transaction. Safe to retry: fn() has not run.
+        msg.includes("did not open a transaction"));
+}
+const WITH_IMMEDIATE_TX_MAX_ATTEMPTS = 5;
+/**
+ * Reclassify an exhausted-retry BEGIN failure that is still contention-shaped
+ * (#948) into a `TransientError("STATE_DB_CONTENDED")`, the same class as a
+ * held workflow run lock (`RUN_LEASE_HELD`): the driver text is accurate but unhelpful (`{"ok":false,"error":"database is
+ * locked"}`, exit 70/INTERNAL) — this instead reads as a retryable-shortly
+ * signal (exit 75, sysexits EX_TEMPFAIL) with the original error preserved as
+ * `cause` for `--verbose`/debugging. A genuinely unrelated error (not
+ * contention-shaped) is rethrown exactly as raised, never reclassified.
+ */
+function throwBeginFailure(err) {
+    if (isSqliteContentionError(err)) {
+        const contended = new TransientError("akm's state database is busy (another akm process is writing it); retry shortly.", "STATE_DB_CONTENDED");
+        contended.cause = err;
+        throw contended;
+    }
+    throw err;
+}
+/**
+ * Open, but deliberately do not finish, an immediate transaction.
+ *
+ * This is the split-phase counterpart to {@link withImmediateTransaction} for
+ * the source-update coordinator: index finalization must mutate state.db in a
+ * transaction that remains pending until content, lockfile, and index
+ * publication have all succeeded. The caller that asked for this split phase
+ * owns the matching COMMIT/ROLLBACK.
+ *
+ * Only a contention-shaped BEGIN failure is retried. "cannot start a
+ * transaction within a transaction" is deliberately NOT: it means a
+ * transaction is already open on this connection (a re-entrant call — handled
+ * by the entry guard in {@link withImmediateTransaction}), and "retrying" it
+ * with a ROLLBACK would destroy the caller's transaction (issue #686).
+ */
+export function beginImmediateTransaction(db) {
+    if (db.inTransaction) {
+        throw new Error("beginImmediateTransaction requires a connection with no active transaction");
+    }
+    let lastBeginErr;
+    for (let attempt = 1; attempt <= WITH_IMMEDIATE_TX_MAX_ATTEMPTS; attempt++) {
+        try {
+            db.exec("BEGIN IMMEDIATE");
+            if (!db.inTransaction) {
+                throw new Error("BEGIN IMMEDIATE did not open a transaction (phantom contention state)");
+            }
+            return;
+        }
+        catch (err) {
+            lastBeginErr = err;
+            if (isSqliteContentionError(err) && attempt < WITH_IMMEDIATE_TX_MAX_ATTEMPTS) {
+                if (db.inTransaction) {
+                    try {
+                        db.exec("ROLLBACK");
+                    }
+                    catch {
+                        // Transaction already gone — safe to retry BEGIN.
+                    }
+                }
+                sleepSync(2 ** (attempt - 1));
+                continue;
+            }
+            throwBeginFailure(err);
+        }
+    }
+    throwBeginFailure(lastBeginErr);
+}
+/** Run `fn` inside a `BEGIN IMMEDIATE` transaction, joining one that is already open on `db`. */
+export function withImmediateTransaction(db, fn) {
+    // Re-entrancy guard (issue #686): if a transaction is already open on this
+    // connection (e.g. a nested withImmediateTransaction call inside an outer
+    // frame's fn), join it — run fn directly with no BEGIN/COMMIT/ROLLBACK of
+    // our own. Without this, the nested BEGIN throws "cannot start a transaction
+    // within a transaction", which the old retry path answered with an
+    // unconditional ROLLBACK — destroying the OUTER transaction and leaving its
+    // COMMIT to fail with "cannot commit - no transaction is active".
+    if (db.inTransaction) {
+        return fn();
+    }
+    beginImmediateTransaction(db);
+    try {
+        const result = fn();
+        if (!db.inTransaction) {
+            // The transaction we opened vanished while fn() ran (e.g. an
+            // auto-rollback or a stray ROLLBACK inside fn). fn's writes may have
+            // escaped serialization, so retrying is unsafe — fail loudly instead of
+            // letting COMMIT throw the opaque "cannot commit - no transaction is
+            // active" SQLiteError.
+            throw new Error("withImmediateTransaction invariant violated: transaction opened by BEGIN IMMEDIATE was no longer active after the transaction body ran; refusing to COMMIT (writes may have escaped serialization)");
+        }
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        if (db.inTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Ignore rollback failures so the original error is preserved.
+            }
+        }
+        throw err;
+    }
+}

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

@@ -0,0 +1,130 @@
+// 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), and the VACUUM pass
+ * state.db and index.db share.
+ *
+ * `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 read-only connection via the plain
+ * {@link openDatabase} opener rather than `openStateDatabase`
+ * (src/core/state-db.ts), since a corrupt database must not need a clean
+ * migration-ledger read, let alone a migration, just to report itself as
+ * corrupt.
+ *
+ * {@link vacuumIfReclaimable} is the 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
+ * when asked to or when the freelist ratio crosses
+ * {@link STATE_DB_FREELIST_WARN_RATIO}, and never throws — a locked/busy
+ * database is reported, not raised. improve's post-purge pass runs it on
+ * state.db, and `akm index` on index.db.
+ *
+ * @module storage/state-db-integrity
+ */
+import { appendEvent } from "../core/events.js";
+import { openDatabase } from "./database.js";
+import { applyReadonlyPragmas } 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
+ * {@link vacuumIfReclaimable} compacts state.db (after improve's retention
+ * purge) or index.db (at the end of `akm index`).
+ */
+export const STATE_DB_FREELIST_WARN_RATIO = 0.5;
+/** Event appended by {@link vacuumIfReclaimable} after a successful VACUUM of state.db. */
+export const STATE_DB_VACUUMED_EVENT = "state_db_vacuumed";
+/** Event appended by {@link vacuumIfReclaimable} after a successful VACUUM of index.db. */
+export const INDEX_DB_VACUUMED_EVENT = "index_db_vacuumed";
+function firstColumn(row) {
+    return row === undefined ? undefined : Object.values(row)[0];
+}
+function openReadonlyStateDb(dbPath) {
+    const db = openDatabase(dbPath, { readonly: true, create: false });
+    applyReadonlyPragmas(db);
+    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 `vacuum.force` is set or `freelist.ratio` exceeds
+ * {@link STATE_DB_FREELIST_WARN_RATIO}, appending `vacuum.eventType` with
+ * the pages before/after. Runs on the caller's read-write connection — for
+ * state.db right after the retention purge, for index.db at the end of an
+ * index run. 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 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 vacuumIfReclaimable(db, freelist, vacuum, eventsCtx) {
+    if (!vacuum.force && 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: vacuum.eventType,
+        metadata: { pagesBefore: freelist.pageCount, pagesAfter, freelistRatioBefore: freelist.ratio },
+    }, eventsCtx);
+    return { ran: true, pagesBefore: freelist.pageCount, pagesAfter };
+}

package/dist/tasks/activation-config.js

@@ -1,88 +1,160 @@
 // 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 { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
-import { deriveBundleId } from "../core/bundle-id.js";
-import { resolveStashDir } from "../core/common.js";
-import { mutateConfig } from "../core/config/config.js";
-import { bundleSourceId, filesystemBundleSourceId, isBundleEnabled } from "../core/config/config-sources.js";
+/**
+ * The host's scheduling choice.
+ *
+ * `scheduler.enabled` in config.json is the list of fully-qualified refs
+ * (`bundle//tasks/x`, `bundle//workflows/y`) this host installs in its native
+ * scheduler. Installing a bundle never schedules anything: a task only gets a
+ * native row once its ref is on this list (`akm task enable`, `akm setup`),
+ * and only bundles that are active on this host are eligible.
+ *
+ * A config that predates the list (`scheduler.enabled` absent) is read as
+ * "keep what is installed": `akm task sync` takes the akm-written rows already
+ * in the native scheduler as the host's choice and writes the list once. A
+ * 0.9.17-alpha `{kind, ref, sourceId}` entry is read as its `ref`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../core/asset/asset-placement.js";
+import { bundleRefToString, makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
+import { typeNameFromConceptId } from "../core/asset/resolve-ref.js";
+import { mutateConfig, schedulerSourceIdFor } from "../core/config/config.js";
+import { bundleComponentConfig, bundleContentRoots, isBundleEnabled } from "../core/config/config-sources.js";
 import { UsageError } from "../core/errors.js";
-export function canonicalSchedulerActivationRef(ref) {
+import { warnOnce } from "../core/warn.js";
+export function canonicalSchedulerRef(ref) {
     const parsed = parseBundleRef(ref);
     if (!parsed.bundle || parsed.fragment !== undefined || bundleRefToString(parsed) !== ref) {
-        throw new UsageError(`Scheduler activation requires a canonical fully-qualified ref, got ${JSON.stringify(ref)}.`, "INVALID_FLAG_VALUE");
+        throw new UsageError(`Scheduling requires a canonical fully-qualified ref, got ${JSON.stringify(ref)}.`, "INVALID_FLAG_VALUE");
     }
     return ref;
 }
-export function schedulerActivations(config) {
-    return Object.freeze((config.scheduler?.enabled ?? []).map((activation) => Object.freeze({
-        kind: activation.kind,
-        ref: canonicalSchedulerActivationRef(activation.ref),
-        sourceId: activation.sourceId,
-    })));
-}
-export function isSchedulerRefEnabled(config, kind, ref) {
-    const canonicalRef = canonicalSchedulerActivationRef(ref);
-    const bundle = parseBundleRef(canonicalRef).bundle;
-    const currentSourceId = schedulerActivationSourceId(config, bundle);
-    if (!currentSourceId)
-        return false;
-    return schedulerActivations(config).some((activation) => activation.kind === kind && activation.ref === canonicalRef && activation.sourceId === currentSourceId);
+/**
+ * Refs this host schedules, or `undefined` when the host has never chosen
+ * (the config predates the list). An entry that is not a canonical ref is
+ * skipped with a warning, never fatal.
+ */
+export function schedulerEnabledRefs(config) {
+    const enabled = config.scheduler?.enabled;
+    if (enabled === undefined)
+        return undefined;
+    const refs = new Set();
+    for (const ref of enabled) {
+        try {
+            refs.add(canonicalSchedulerRef(ref));
+        }
+        catch {
+            warnOnce(`scheduler:enabled:${ref}`, `Ignoring scheduler.enabled entry ${JSON.stringify(ref)}: not a canonical ref.`);
+        }
+    }
+    return Object.freeze([...refs]);
 }
-/** Grants that still name the same active source installation they approved. */
-export function activeSchedulerActivations(config) {
-    return schedulerActivations(config).filter((activation) => {
-        const bundle = parseBundleRef(activation.ref).bundle;
-        return activation.sourceId === schedulerActivationSourceId(config, bundle);
-    });
+export function isSchedulerRefEnabled(config, ref) {
+    return (schedulerEnabledRefs(config) ?? []).includes(canonicalSchedulerRef(ref));
 }
-/** Pure lifecycle helper used when a bundle is removed or replaced. */
 export function revokeSchedulerActivationsForBundle(config, bundleId) {
-    const enabled = schedulerActivations(config).filter((activation) => parseBundleRef(activation.ref).bundle !== bundleId);
-    if (enabled.length === (config.scheduler?.enabled ?? []).length)
+    const current = config.scheduler?.enabled;
+    if (current === undefined)
+        return config;
+    const enabled = current.filter((ref) => bundleOf(ref) !== bundleId);
+    if (enabled.length === current.length)
         return config;
     return { ...config, scheduler: { ...config.scheduler, enabled } };
 }
-export function setSchedulerRefEnabled(kind, ref, enabled) {
-    let canonicalRef = ref;
+/** Whether refs from this bundle may be scheduled here: configured and enabled, or the implicit `AKM_BUNDLE_DIR` stash. */
+export function isSchedulerBundleActive(config, bundleId) {
+    return schedulerSourceIdFor(config, bundleId) !== undefined;
+}
+/**
+ * Add or remove one ref on this host's list. Callers must have made the host's
+ * choice explicit first (see `initializeSchedulerChoice` in
+ * `commands/tasks/tasks.ts`): on a config without the list this writes just
+ * the one ref, which is the whole choice from then on.
+ */
+export function setSchedulerRefEnabled(ref, enabled) {
+    const canonicalRef = canonicalSchedulerRef(ref);
     const result = mutateConfig((current) => {
-        canonicalRef = canonicalSchedulerActivationRef(ref);
-        const existing = schedulerActivations(current);
-        const bundle = parseBundleRef(canonicalRef).bundle;
-        const sourceId = enabled ? schedulerActivationSourceId(current, bundle) : undefined;
-        if (enabled && !sourceId) {
-            throw new UsageError(`Cannot enable scheduled execution from inactive or unconfigured bundle ${JSON.stringify(bundle)}.`, "INVALID_FLAG_VALUE");
+        const existing = current.scheduler?.enabled ?? [];
+        if (enabled && !isSchedulerBundleActive(current, bundleOf(canonicalRef) ?? "")) {
+            throw new UsageError(`Cannot enable scheduled execution from inactive or unconfigured bundle ${JSON.stringify(bundleOf(canonicalRef))}.`, "INVALID_FLAG_VALUE");
         }
-        const present = existing.some((activation) => activation.kind === kind && activation.ref === canonicalRef && (!enabled || activation.sourceId === sourceId));
-        if (present === enabled)
+        if (current.scheduler?.enabled !== undefined && existing.includes(canonicalRef) === enabled)
             return current;
-        const next = enabled
-            ? [
-                ...existing.filter((activation) => activation.kind !== kind || activation.ref !== canonicalRef),
-                { kind, ref: canonicalRef, sourceId: sourceId },
-            ]
-            : existing.filter((activation) => activation.kind !== kind || activation.ref !== canonicalRef);
-        next.sort((left, right) => left.ref.localeCompare(right.ref) || left.kind.localeCompare(right.kind));
-        return {
-            ...current,
-            scheduler: {
-                ...current.scheduler,
-                enabled: next,
-            },
-        };
+        const next = existing.filter((entry) => entry !== canonicalRef);
+        if (enabled)
+            next.push(canonicalRef);
+        next.sort((left, right) => left.localeCompare(right));
+        return { ...current, scheduler: { ...current.scheduler, enabled: next } };
     });
     return { config: result.config, changed: result.written, ref: canonicalRef };
 }
-/** Current active source identity for a configured or environment-only bundle. */
-export function schedulerActivationSourceId(config, bundleId) {
-    if (isBundleEnabled(config, bundleId))
-        return bundleSourceId(config, bundleId);
-    if (config.bundles?.[bundleId] !== undefined || !process.env.AKM_BUNDLE_DIR?.trim())
+/**
+ * The refs behind the akm-written rows currently installed in the native
+ * scheduler: what this host was running before it had a `scheduler.enabled`
+ * list. Rows the backend proves disabled, rows for bundles that are not
+ * active here, and rows whose task file is gone are left out.
+ */
+export function enabledRefsFromInstalled(installed, config) {
+    const refs = new Set();
+    for (const entry of installed) {
+        const ref = installedEntryRef(entry, config);
+        if (ref !== undefined)
+            refs.add(ref);
+    }
+    return Object.freeze([...refs].sort((left, right) => left.localeCompare(right)));
+}
+function installedEntryRef(entry, config) {
+    if (entry.enabled === false || !entry.invocation)
+        return undefined;
+    const invocation = entry.invocation;
+    try {
+        if (invocation[0] === "workflow" && invocation[1] === "run" && invocation.length === 3 && invocation[2]) {
+            const ref = canonicalSchedulerRef(invocation[2]);
+            const parsed = parseBundleRef(ref);
+            if (!parsed.bundle || !isBundleEnabled(config, parsed.bundle))
+                return undefined;
+            return hasBackingFile(config, parsed.bundle, parsed.conceptId) ? ref : undefined;
+        }
+        if (invocation[0] !== "task" || invocation[1] !== "run" || !invocation[2])
+            return undefined;
+        const bundleIndex = invocation.indexOf("--bundle", 3);
+        const bundle = bundleIndex === -1 ? config.defaultBundle : invocation[bundleIndex + 1];
+        if (!bundle || !isBundleEnabled(config, bundle))
+            return undefined;
+        const bundleConfig = config.bundles?.[bundle];
+        const adapter = bundleConfig ? (bundleComponentConfig(bundleConfig)?.adapter ?? "akm") : "akm";
+        const conceptId = adapter === "akm-task" ? invocation[2] : `tasks/${invocation[2]}`;
+        if (!hasBackingFile(config, bundle, conceptId))
+            return undefined;
+        return canonicalSchedulerRef(makeBundleRef(bundle, conceptId));
+    }
+    catch {
         return undefined;
+    }
+}
+function hasBackingFile(config, bundle, conceptId) {
+    const parts = typeNameFromConceptId(conceptId);
+    if (!parts)
+        return true;
+    const typeDir = stashDirFor(parts.type);
+    if (!typeDir)
+        return true;
+    const contentRoot = bundleContentRoots(config).find((entry) => entry.id === bundle)?.contentRoot;
+    if (!contentRoot)
+        return true;
+    try {
+        const target = assetPathForName(parts.type, path.join(contentRoot, typeDir), parts.name);
+        return fs.existsSync(target) && fs.statSync(target).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function bundleOf(ref) {
     try {
-        const root = resolveStashDir();
-        const implicitId = deriveBundleId(undefined, root, new Set(Object.keys(config.bundles ?? {})));
-        return implicitId === bundleId ? filesystemBundleSourceId(root) : undefined;
+        return parseBundleRef(ref).bundle;
     }
     catch {
         return undefined;