akm-cli 0.9.0-beta.5 → 0.9.0-beta.50

package/dist/storage/repositories/registry-cache.js

@@ -0,0 +1,92 @@
+// 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 { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { closeDatabase, getRegistryIndexCache, openIndexDatabase, upsertRegistryIndexCache } from "../../indexer/db/db.js";
+/**
+ * RAII-style lifecycle helper for the registry cache DB. Opens the DB (treating
+ * a failed open exactly like the legacy fall-through: the bun-test isolation
+ * guard is re-thrown, any other failure yields `db = undefined`), runs `fn`,
+ * and guarantees the DB is closed in a `finally` after `fn` has fully settled
+ * (the await is required: the callbacks are async, and closing before they
+ * settle would tear the DB down mid-write).
+ */
+export async function withRegistryCacheDb(fn) {
+    let db;
+    try {
+        db = openIndexDatabase();
+    }
+    catch (err) {
+        // Never mask the bun-test isolation guard as "DB unavailable".
+        rethrowIfTestIsolationError(err);
+        db = undefined;
+    }
+    try {
+        return await fn(db);
+    }
+    finally {
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * Shared registry index-cache fetch template. Opens the cache DB, returns a
+ * fresh cache hit when present, otherwise fetches live (writing the result back
+ * to the cache best-effort), and falls back to a stale cache row when the fetch
+ * fails. Behaviour-preserving extraction of the logic previously duplicated in
+ * `skills-sh.ts` (`fetchSkills`) and `static-index.ts` (`loadIndex`).
+ */
+export async function fetchCachedJson(opts) {
+    const { cacheKey, ttlMs, parseCache, fetchFresh } = opts;
+    return withRegistryCacheDb(async (db) => {
+        // ── Step 1: Try DB cache (index.db) ─────────────────────────────────────
+        let dbCacheResult;
+        try {
+            if (db) {
+                dbCacheResult = getRegistryIndexCache(db, cacheKey, ttlMs);
+            }
+        }
+        catch (err) {
+            // Never mask the bun-test isolation guard as "DB unavailable" — see
+            // rethrowIfTestIsolationError in src/core/errors.ts. Without this, a
+            // leaky test silently gets a cold cache instead of the loud
+            // TEST_ISOLATION_MISSING failure the guard intends.
+            rethrowIfTestIsolationError(err);
+            // index.db read failed (pre-migration install or test env) — fall through
+        }
+        if (dbCacheResult) {
+            const cached = parseCache(dbCacheResult.indexJson, { stale: false });
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        // ── Step 2: Fetch fresh ──────────────────────────────────────────────────
+        try {
+            const { value, cacheJson, cacheOpts } = await fetchFresh(db);
+            if (db) {
+                try {
+                    upsertRegistryIndexCache(db, cacheKey, cacheJson, cacheOpts);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            return value;
+        }
+        catch (err) {
+            // Fetch failed — use stale DB cache if available.
+            if (dbCacheResult) {
+                const stale = parseCache(dbCacheResult.indexJson, { stale: true });
+                if (stale !== undefined)
+                    return stale;
+            }
+            throw err;
+        }
+    });
+}

package/dist/storage/sqlite-pragmas.js

@@ -0,0 +1,146 @@
+// 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 PRAGMA application + journal-mode resolution (#628).
+ *
+ * Every AKM SQLite opener applies the same opening PRAGMAs: a journal mode, a
+ * 30 s busy_timeout, and (for most) foreign_keys = ON. Historically each opener
+ * hard-coded `PRAGMA journal_mode = WAL`. WAL is impossible on network
+ * filesystems (NFS/SMB) because its `-shm` shared-memory wal-index cannot be
+ * mmap'd over a network mount, so AKM could not run with its data dir on a
+ * network share.
+ *
+ * This module centralises that PRAGMA block behind {@link applyStandardPragmas}
+ * and makes the journal mode configurable via the `AKM_SQLITE_JOURNAL_MODE`
+ * env var (WAL | DELETE | TRUNCATE; default WAL = unchanged behaviour). When the
+ * mode is the WAL default and the data directory is detected to live on a
+ * network filesystem, it auto-falls-back to DELETE with a one-line warning.
+ *
+ * Boundary note: this is a PLAIN module, not a runtime-boundary file. It only
+ * does pure string work plus `db.exec()` (allowed everywhere). The single
+ * runtime primitive it needs — a filesystem-type probe (statfs) — lives in
+ * src/runtime.ts and is injected here, keeping the network-FS classifier a
+ * pure, unit-testable function.
+ *
+ * @module storage/sqlite-pragmas
+ */
+import { warn } from "../core/warn.js";
+import { statfsType } from "../runtime.js";
+const VALID_MODES = new Set(["WAL", "DELETE", "TRUNCATE"]);
+// One-shot warning guards so a misconfigured env var or a network-FS fallback
+// each emit AT MOST ONCE per process rather than on every db open.
+let warnedInvalid = false;
+let warnedNetworkFallback = false;
+/**
+ * Resolve a raw `AKM_SQLITE_JOURNAL_MODE` value to a canonical {@link JournalMode}.
+ *
+ * PURE and unit-testable: the raw string is passed in (not read from
+ * `process.env` here). Trims + uppercases; an empty/undefined value yields the
+ * WAL default; a recognised value yields its canonical form; any other
+ * non-empty value warns once and falls back to WAL. Never throws.
+ */
+export function resolveJournalMode(raw) {
+    if (raw === undefined)
+        return "WAL";
+    const normalized = raw.trim().toUpperCase();
+    if (normalized === "")
+        return "WAL";
+    if (VALID_MODES.has(normalized)) {
+        return normalized;
+    }
+    warnInvalidJournalModeOnce(raw);
+    return "WAL";
+}
+/**
+ * The single env-reading seam: resolve the configured journal mode from
+ * `process.env.AKM_SQLITE_JOURNAL_MODE`. Read at call time (per open) so tests
+ * that set the env per-case see the right value and we avoid stale-env flakes.
+ */
+export function resolveConfiguredJournalMode() {
+    return resolveJournalMode(process.env.AKM_SQLITE_JOURNAL_MODE);
+}
+function warnInvalidJournalModeOnce(raw) {
+    if (warnedInvalid)
+        return;
+    warnedInvalid = true;
+    warn(`[akm] invalid AKM_SQLITE_JOURNAL_MODE=${JSON.stringify(raw)} — using WAL (valid: WAL, DELETE, TRUNCATE)`);
+}
+// Known Linux f_type magic numbers for network filesystems. node's statfs
+// normalises `type` to this numeric f_type magic on all platforms.
+const FS_MAGIC_NFS = 0x6969; // 26985    — NFS
+const FS_MAGIC_SMB = 0x517b; // 20859    — older SMB_SUPER_MAGIC
+const FS_MAGIC_CIFS = 0xff534d42; // 4283649346 — SMB/CIFS
+const FS_MAGIC_SMB2 = 0xfe534d42; // 4267272514 — SMB2
+const FS_MAGIC_FUSE = 0x65735546; // 1702057286 — FUSE (sshfs + many network FUSE mounts)
+const NETWORK_FS_MAGICS = new Set([
+    FS_MAGIC_NFS,
+    FS_MAGIC_SMB,
+    FS_MAGIC_CIFS,
+    FS_MAGIC_SMB2,
+    // FUSE is a judgment call: it backs BOTH network mounts (sshfs) and local
+    // mounts (some encrypted/overlay FS). Treating it as network falls back to
+    // DELETE — conservative-but-safe (DELETE works everywhere; the only cost is
+    // losing WAL concurrency). An operator can always force WAL via the env var.
+    FS_MAGIC_FUSE,
+]);
+/**
+ * PURE classifier: is `fsType` a known network-filesystem magic number?
+ * Returns false for `undefined` (probe failed/unsupported) and for local
+ * magics (ext4 0xEF53, btrfs, xfs, tmpfs, apfs, …). Unit-testable with
+ * injected magic numbers — no real mount required.
+ */
+export function isNetworkFilesystem(fsType) {
+    if (fsType === undefined)
+        return false;
+    return NETWORK_FS_MAGICS.has(fsType);
+}
+/**
+ * Apply AKM's standard opening PRAGMAs to `db`, in order:
+ *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)
+ *   2. `busy_timeout = 30000`
+ *   3. `foreign_keys = ON`  (unless `opts.foreignKeys === false`)
+ *   4. `synchronous = FULL` (only in a rollback-journal mode — DELETE/TRUNCATE)
+ *
+ * Returns the effective {@link JournalMode} so callers/tests can assert it.
+ *
+ * `synchronous = FULL` is set explicitly only in DELETE/TRUNCATE so durability
+ * intent is clear: rollback journals need FULL for crash-durability across
+ * power loss, whereas WAL is durable at NORMAL. SQLite's default synchronous is
+ * already FULL when unset, so this never changes WAL-default behaviour — the
+ * WAL path emits no `synchronous` pragma, exactly as before.
+ */
+export function applyStandardPragmas(db, opts = {}) {
+    let mode = resolveConfiguredJournalMode();
+    // Network-FS fallback only fires for the WAL default and only when we have a
+    // directory to probe. An explicitly-requested DELETE/TRUNCATE is never
+    // overridden, and a failed/unsupported probe (undefined) keeps WAL.
+    if (mode === "WAL" && opts.dataDir) {
+        const probe = opts.fsTypeProbe ?? statfsType;
+        if (isNetworkFilesystem(probe(opts.dataDir))) {
+            mode = "DELETE";
+            warnNetworkFallbackOnce(opts.dataDir);
+        }
+    }
+    // PRAGMAs must run before any DDL or DML. busy_timeout is applied FIRST so a
+    // journal-mode change that must reclaim a leftover `-wal` file (WAL→DELETE on
+    // reopen of an unclean WAL db, e.g. after a crash) can wait out a transient
+    // lock instead of failing immediately with SQLITE_BUSY. For the WAL default
+    // this is a no-op (WAL→WAL changes nothing), so byte-identical behaviour is
+    // preserved.
+    db.exec("PRAGMA busy_timeout = 30000");
+    db.exec(`PRAGMA journal_mode = ${mode}`);
+    if (opts.foreignKeys !== false) {
+        db.exec("PRAGMA foreign_keys = ON");
+    }
+    if (mode !== "WAL") {
+        db.exec("PRAGMA synchronous = FULL");
+    }
+    return mode;
+}
+function warnNetworkFallbackOnce(dataDir) {
+    if (warnedNetworkFallback)
+        return;
+    warnedNetworkFallback = true;
+    warn(`[akm] network filesystem detected at ${dataDir} — WAL unsupported, using DELETE journal mode`);
+}

package/dist/tasks/backends/cron.js

@@ -29,7 +29,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
 const BEGIN = (id) => `# akm:task ${id} BEGIN`;
 const END = (id) => `# akm:task ${id} END`;

package/dist/tasks/backends/launchd.js

@@ -27,7 +27,7 @@ import path from "node:path";
 import launchdTemplate from "../../assets/backends/launchd-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";

package/dist/tasks/backends/schtasks.js

@@ -35,7 +35,7 @@ import path from "node:path";
 import schtasksTemplate from "../../assets/backends/schtasks-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToSchtasks } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const DEFAULT_FOLDER_PREFIX = "\\akm\\";

package/dist/tasks/{resolveAkmBin.js → resolve-akm-bin.js}

@@ -44,8 +44,8 @@ export function resolveAkmInvocation(options = {}) {
 /**
  * From the URL of a module inside `src/tasks/` figure out the CLI entry.
  *
- *   • dev      `…/src/tasks/resolveAkmBin.ts`   → `…/src/cli.ts`
- *   • build    `…/dist/tasks/resolveAkmBin.js`  → `…/dist/cli.js`
+ *   • dev      `…/src/tasks/resolve-akm-bin.ts`   → `…/src/cli.ts`
+ *   • build    `…/dist/tasks/resolve-akm-bin.js`  → `…/dist/cli.js`
  */
 function resolveCliEntry(moduleUrl) {
     let modulePath;

package/dist/tasks/runner.js

@@ -33,7 +33,7 @@ import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { buildTaskRunId, insertTaskLogLines, openLogsDatabase, } from "../core/logs-db.js";
 import { getTaskLogDir } from "../core/paths.js";
-import { getTaskHistory, openStateDatabase, queryTaskHistory, upsertTaskHistory } from "../core/state-db.js";
+import { getTaskHistory, queryTaskHistory, upsertTaskHistory, withStateDb } from "../core/state-db.js";
 import { error } from "../core/warn.js";
 import { requireAgentProfile, runAgent } from "../integrations/agent/index.js";
 import { resolveProcessAgentProfile } from "../integrations/agent/config.js";
@@ -460,8 +460,7 @@ function persistRunLog(input) {
 // ── history ─────────────────────────────────────────────────────────────────
 function appendHistory(result) {
     try {
-        const db = openStateDatabase();
-        try {
+        withStateDb((db) => {
             upsertTaskHistory(db, {
                 task_id: result.id,
                 status: result.status,
@@ -477,10 +476,7 @@ function appendHistory(result) {
                     profile: result.target.kind === "prompt" ? result.target.profile : undefined,
                 }),
             });
-        }
-        finally {
-            db.close();
-        }
+        });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -488,8 +484,7 @@ function appendHistory(result) {
     }
 }
 export function readTaskHistory(options = {}) {
-    const db = openStateDatabase();
-    try {
+    return withStateDb((db) => {
         let rows;
         if (options.id) {
             const row = getTaskHistory(db, options.id);
@@ -503,10 +498,7 @@ export function readTaskHistory(options = {}) {
             return rows.slice(0, options.limit);
         }
         return rows;
-    }
-    finally {
-        db.close();
-    }
+    });
 }
 /**
  * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape

package/dist/wiki/wiki.js

@@ -224,6 +224,43 @@ function readSchemaDescription(wikiDir) {
         return undefined;
     }
 }
+/**
+ * Load a wiki's `schema.md` body and frontmatter.
+ *
+ * Unlike {@link readSchemaDescription} (which returns only the frontmatter
+ * `description` for `listWikis` summaries), this returns the markdown **body**
+ * — everything after the closing `---` of the frontmatter — which is where the
+ * page contract, operations, and hard rules live. The body is the rulebook
+ * injected into the write-time prompt for wiki-page edits.
+ *
+ * Swallow-and-degrade like the existing reader: a missing file, an unresolvable
+ * wiki dir, or malformed content yields `{ body: "", frontmatter: {} }`. Never
+ * throws.
+ */
+export function loadWikiSchema(stashRoot, name) {
+    const empty = { body: "", frontmatter: {} };
+    let wikiDir;
+    try {
+        wikiDir = resolveWikiDir(stashRoot, name);
+    }
+    catch {
+        return empty;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(wikiDir, SCHEMA_MD), "utf8");
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = parseFrontmatter(raw);
+        return { body: parsed.content, frontmatter: parsed.data };
+    }
+    catch {
+        return empty;
+    }
+}
 function toIsoDate(ms) {
     return new Date(ms).toISOString();
 }

package/dist/workflows/db.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
 import { 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.
  *
@@ -46,12 +47,10 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = openDatabase(dbPath);
-    db.exec("PRAGMA journal_mode = WAL");
     // #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.
-    db.exec("PRAGMA busy_timeout = 30000");
-    db.exec("PRAGMA foreign_keys = ON");
+    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
+    applyStandardPragmas(db, { dataDir: dir });
     ensureBaseSchema(db);
     runMigrations(db);
     return db;

package/dist/workflows/runtime/runs.js

@@ -2,23 +2,16 @@
 // 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 { randomUUID } from "node:crypto";
-import fs from "node:fs";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { getDbPath } from "../../core/paths.js";
-import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
-import { resolveAssetPath } from "../../sources/resolve.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
-import { formatWorkflowErrors } from "../authoring/authoring.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
-import { parseWorkflow } from "../parser.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
+import { loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
 export async function startWorkflowRun(ref, params = {}, options) {
     const asset = await loadWorkflowAsset(ref);
     return withWorkflowRunsRepo(async (repo) => {
@@ -299,115 +292,6 @@ async function resolveRunSpecifier(repo, specifier, params) {
     const started = await startWorkflowRun(ref, params ?? {});
     return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
 }
-async function loadWorkflowAsset(ref) {
-    const parsed = parseAssetRef(ref);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
-    }
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    let assetPath;
-    let sourcePath;
-    for (const source of searchSources) {
-        try {
-            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
-            sourcePath = source.path;
-            break;
-        }
-        catch {
-            /* continue */
-        }
-    }
-    if (!assetPath) {
-        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
-    }
-    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
-    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
-    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
-    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
-}
-function loadWorkflowDocumentFromDisk(assetPath) {
-    const content = fs.readFileSync(assetPath, "utf8");
-    const result = parseWorkflow(content, { path: assetPath });
-    if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
-    }
-    return result.document;
-}
-function readWorkflowDocumentFromIndex(sourcePath, ref) {
-    const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
-        return null;
-    const db = openExistingDatabase(dbPath);
-    try {
-        const parsed = parseAssetRef(ref);
-        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
-        const row = db
-            .prepare(`SELECT wd.document_json AS document_json
-           FROM workflow_documents wd
-           JOIN entries e ON e.id = wd.entry_id
-          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
-          LIMIT 1`)
-            .get(entryKey);
-        if (!row)
-            return null;
-        try {
-            return JSON.parse(row.document_json);
-        }
-        catch {
-            return null;
-        }
-    }
-    finally {
-        closeDatabase(db);
-    }
-}
-function projectAsset(doc, ref, assetPath, sourcePath) {
-    return {
-        ref,
-        path: assetPath,
-        sourcePath,
-        title: doc.title,
-        ...(doc.parameters
-            ? {
-                parameters: doc.parameters.map((p) => ({
-                    name: p.name,
-                    ...(p.description ? { description: p.description } : {}),
-                })),
-            }
-            : {}),
-        steps: doc.steps.map((s) => ({
-            id: s.id,
-            title: s.title,
-            instructions: s.instructions.text,
-            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
-            sequenceIndex: s.sequenceIndex,
-        })),
-    };
-}
-function resolveWorkflowEntryId(sourcePath, ref) {
-    const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
-        return null;
-    const db = openExistingDatabase(dbPath);
-    try {
-        const parsed = parseAssetRef(ref);
-        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
-        const row = db
-            .prepare(`SELECT id
-         FROM entries
-         WHERE entry_type = 'workflow'
-            AND entry_key = ?
-          LIMIT 1`)
-            .get(entryKey);
-        return row?.id ?? null;
-    }
-    finally {
-        closeDatabase(db);
-    }
-}
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -0,0 +1,125 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { getDbPath } from "../../core/paths.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { formatWorkflowErrors } from "../authoring/authoring.js";
+import { parseWorkflow } from "../parser.js";
+/**
+ * Resolve a `workflow:<name>` ref to a fully-projected {@link WorkflowAsset}.
+ *
+ * Prefers the parsed document cached in `index.db` (fast path) and falls back to
+ * reading + parsing the source file from disk. Pure loading/parsing concern —
+ * extracted from the run repository so run orchestration no longer owns asset
+ * resolution.
+ */
+export async function loadWorkflowAsset(ref) {
+    const parsed = parseAssetRef(ref);
+    if (parsed.type !== "workflow") {
+        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
+    }
+    const config = loadConfig();
+    const allSources = resolveSourceEntries(undefined, config);
+    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    let assetPath;
+    let sourcePath;
+    for (const source of searchSources) {
+        try {
+            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
+            sourcePath = source.path;
+            break;
+        }
+        catch {
+            /* continue */
+        }
+    }
+    if (!assetPath) {
+        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
+    }
+    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
+    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
+    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
+    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
+}
+/**
+ * Resolve the `entries.id` for an indexed workflow, or null when the index
+ * database does not yet exist or has no matching entry.
+ */
+export function resolveWorkflowEntryId(sourcePath, ref) {
+    if (!fs.existsSync(getDbPath()))
+        return null;
+    const parsed = parseAssetRef(ref);
+    const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+    return withIndexDb((db) => {
+        const row = db
+            .prepare(`SELECT id
+         FROM entries
+         WHERE entry_type = 'workflow'
+            AND entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        return row?.id ?? null;
+    });
+}
+function loadWorkflowDocumentFromDisk(assetPath) {
+    const content = fs.readFileSync(assetPath, "utf8");
+    const result = parseWorkflow(content, { path: assetPath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
+    }
+    return result.document;
+}
+function readWorkflowDocumentFromIndex(sourcePath, ref) {
+    if (!fs.existsSync(getDbPath()))
+        return null;
+    const parsed = parseAssetRef(ref);
+    const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+    return withIndexDb((db) => {
+        const row = db
+            .prepare(`SELECT wd.document_json AS document_json
+           FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        if (!row)
+            return null;
+        try {
+            return JSON.parse(row.document_json);
+        }
+        catch {
+            return null;
+        }
+    });
+}
+function projectAsset(doc, ref, assetPath, sourcePath) {
+    return {
+        ref,
+        path: assetPath,
+        sourcePath,
+        title: doc.title,
+        ...(doc.parameters
+            ? {
+                parameters: doc.parameters.map((p) => ({
+                    name: p.name,
+                    ...(p.description ? { description: p.description } : {}),
+                })),
+            }
+            : {}),
+        steps: doc.steps.map((s) => ({
+            id: s.id,
+            title: s.title,
+            instructions: s.instructions.text,
+            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
+            sequenceIndex: s.sequenceIndex,
+        })),
+    };
+}