akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.8

package/dist/commands/read/show.js

@@ -24,7 +24,7 @@ import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
 import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
-import { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { displayRef, displayRefForConceptId, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString, isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -43,6 +43,7 @@ import { buildFileContext, buildRenderContext, getRenderer, } from "../../indexe
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { getIndexedMarkdownFragment } from "../../storage/repositories/index-fts-repository.js";
+import { readEntryLinks } from "../../storage/repositories/index-links-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { buildWorkflowAction } from "../../workflows/renderer.js";
 import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
@@ -318,12 +319,13 @@ export async function showLocal(input) {
     response.type = indexedEntry.type;
     response.name = indexedEntry.name;
     const isPrimaryStash = source?.isDefault === true;
+    const displayDefaultBundle = config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined);
     const canonicalRef = displayRef({
         type: indexedEntry.type,
         name: presentedName,
         conceptId: indexedEntry.conceptId,
         bundleId: indexedEntry.bundleId,
-    }, config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined));
+    }, displayDefaultBundle);
     if (parsed.fragment && indexedFragment) {
         const selectedFragmentId = indexedFragment.fragments[indexedFragment.ordinal].fragmentId;
         const selectedRef = `${canonicalRef}#${selectedFragmentId}`;
@@ -395,6 +397,7 @@ export async function showLocal(input) {
                 return { total: 0, hits: [] };
             }
         })(),
+        ...showLinks(indexedEntry.itemRef, displayDefaultBundle),
     };
     const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
@@ -408,6 +411,56 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/** Refs listed per kind of declared link; `total` still counts them all (one memory is named by 1,437 others). */
+const LINKS_PER_KIND = 10;
+/**
+ * The declared links (#935) of an indexed asset, grouped by kind: outgoing in
+ * authored order, incoming by ref, and unresolved tokens as authored. Empty
+ * parts are omitted, and the field when nothing links either way.
+ */
+function showLinks(itemRef, defaultBundle) {
+    let rows;
+    try {
+        rows = withIndexDb((db) => readEntryLinks(db, itemRef));
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        rethrowIfDataDirUnreadable(err);
+        return {};
+    }
+    const outgoing = [];
+    const unresolved = [];
+    for (const row of rows.outgoing) {
+        if (row.conceptId === undefined)
+            unresolved.push({ kind: row.kind, ref: row.raw ?? "" });
+        else
+            outgoing.push({ kind: row.kind, ref: displayRefForConceptId(row.conceptId, row.bundleId, defaultBundle) });
+    }
+    const incoming = rows.incoming.map((row) => ({
+        kind: row.kind,
+        ref: displayRefForConceptId(row.conceptId ?? "", row.bundleId, defaultBundle),
+    }));
+    const links = {
+        ...groupLinks("outgoing", outgoing),
+        ...groupLinks("incoming", incoming),
+        ...groupLinks("unresolved", unresolved),
+    };
+    return Object.keys(links).length > 0 ? { links } : {};
+}
+function groupLinks(part, rows) {
+    if (rows.length === 0)
+        return {};
+    const groups = {};
+    for (const kind of [...new Set(rows.map((row) => row.kind))].sort())
+        groups[kind] = { total: 0, refs: [] };
+    for (const { kind, ref } of rows) {
+        const group = groups[kind];
+        group.total++;
+        if (group.refs.length < LINKS_PER_KIND)
+            group.refs.push(ref);
+    }
+    return { [part]: groups };
+}
 /**
  * Warn and ignore body fragments for namespaces whose authored bytes are
  * sensitive. `warnOnce`-keyed on the exact ref: `akmShowUnified` calls this

package/dist/commands/sources/info.js

@@ -10,6 +10,7 @@ import { formatRegistryUrl } from "../../core/registry-url.js";
 import { error } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount, getEntryCountByType } from "../../storage/repositories/index-entries-repository.js";
+import { countLinksByKind } from "../../storage/repositories/index-links-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { pkgVersion } from "../../version.js";
 /**
@@ -99,9 +100,11 @@ function readIndexStats(resolvedPath) {
     let db;
     try {
         db = openExistingDatabase(resolvedPath);
+        const links = countLinksByKind(db);
         return {
             entryCount: getEntryCount(db),
             byType: getEntryCountByType(db),
+            ...(Object.keys(links).length > 0 ? { links } : {}),
             lastBuiltAt: getMeta(db, "builtAt") ?? null,
             hasEmbeddings: getMeta(db, "hasEmbeddings") === "1",
         };

package/dist/commands/tasks/tasks-cli.js

@@ -435,17 +435,15 @@ const tasksDoctorCommand = defineJsonCommand({
     },
 });
 /**
- * #907: `akm task validate`'s exit-code contract — `valid` and `converts`
- * (a v2/v3 document the in-memory shim converted successfully) are both
- * successful (exit 0); `blocked`/`invalid`/`not-a-task` are diagnosed
- * defects the caller must act on (exit 1, mirroring `task sync`'s own
- * `failures.length > 0 -> EXIT_CODES.GENERAL`). A missing path or an
- * unreadable file never reaches this function at all — `akmTaskValidate`
- * throws a `UsageError` for those, which `defineJsonCommand`'s wrapping
- * already maps to exit 2.
+ * #907: `akm task validate`'s exit-code contract — `valid` succeeds (exit
+ * 0); `blocked`/`invalid`/`not-a-task` are diagnosed defects the caller must
+ * act on (exit 1, mirroring `task sync`'s own `failures.length > 0 ->
+ * EXIT_CODES.GENERAL`). A missing path or an unreadable file never reaches
+ * this function at all — `akmTaskValidate` throws a `UsageError` for those,
+ * which `defineJsonCommand`'s wrapping already maps to exit 2.
  */
 export function taskValidateExitCode(result) {
-    return result.outcome === "valid" || result.outcome === "converts" ? undefined : EXIT_CODES.GENERAL;
+    return result.outcome === "valid" ? undefined : EXIT_CODES.GENERAL;
 }
 const tasksValidateCommand = defineJsonCommand({
     meta: {
@@ -478,9 +476,9 @@ export function taskPruneExitCode(result) {
 const tasksPruneCommand = defineJsonCommand({
     meta: {
         name: "prune",
-        description: "Remove installed scheduler entries `sync` can never reclaim because their own descriptor no longer " +
-            "resolves to a live bundle (corrupt/missing --scheduler-context, or the owning bundle directory is " +
-            "gone). Defaults to a dry-run preview — zero scheduler writes. Requires --yes to remove anything; " +
+        description: "Remove installed scheduler entries `sync` can never reclaim because they no longer resolve to a live " +
+            "bundle (the bundle directory a row names is gone, or an older row's --scheduler-context descriptor " +
+            "cannot be read). Defaults to a dry-run preview — zero scheduler writes. Requires --yes to remove anything; " +
             "--id narrows removal to specific binding ids (comma-separated).",
     },
     args: {

package/dist/commands/tasks/tasks.js

@@ -41,7 +41,7 @@ import { readTaskHistory } from "../../tasks/run/task-history.js";
 import { exitCodeForStatus } from "../../tasks/run/task-result.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
 import { compileTaskSchedulerBindings, schedulerBindingNativeId, } from "../../tasks/scheduler-binding.js";
-import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
+import { readLegacySchedulerContext, scheduledRowEnvironment } from "../../tasks/scheduler-invocation.js";
 import { withSchedulerLock } from "../../tasks/scheduler-lock.js";
 import { compileSchedulerSources, installedRowNativeId, installedRowOwner, installedRowScope, planSchedulerSync, renderSchedulerPlanPreview, scheduledInvocationBundle, } from "../../tasks/scheduler-sync.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
@@ -301,9 +301,7 @@ export async function akmTasksHistory(input) {
  */
 export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
     return withSchedulerLock(async () => {
-        const { sched, plan, publish, warnings } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
-        if (publish && plan.operations.some((operation) => operation.kind !== "remove"))
-            publish();
+        const { sched, plan, warnings } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
         const failed = new Set();
         const failures = [...plan.failures];
         for (const operation of plan.operations) {
@@ -343,7 +341,7 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
 }
 /**
  * `akm task sync --dry-run` (#849): the exact plan `akmTasksSync` would
- * apply, previewed. It writes nothing: no config, no descriptor, no row.
+ * apply, previewed. It writes nothing: no config, no row.
  */
 export async function akmTasksSyncPlan(deps = {}, bundleTarget, options = {}) {
     const { sched, plan } = await buildSchedulerSyncPlan(deps, bundleTarget, { ...options, dryRun: true });
@@ -440,7 +438,7 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
         installed,
         scopes,
         ...(sched.expectedSignature ? { expectedSignature: sched.expectedSignature.bind(sched) } : {}),
-        ...(runtime.options ? { installOptions: runtime.options } : {}),
+        installOptions: runtime.options,
         rebind: options.rebind === true,
         extraRemovals,
         keepRefs,
@@ -450,53 +448,45 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
         ? plan.operations.some((operation) => operation.kind !== "remove")
         : plan.installed.length > 0;
     if (runtime.via === "checkout" && writesLauncher) {
-        warnings.push(`Scheduled tasks now run akm from a source checkout (${runtime.options?.binding?.join(" ")}); they run whatever the checkout holds when they fire. Install akm with \`npm install --global akm-cli\` or a standalone release, then run \`akm task sync --rebind\`.`);
+        warnings.push(`Scheduled tasks now run akm from a source checkout (${runtime.options.binding?.join(" ")}); they run whatever the checkout holds when they fire. Install akm with \`npm install --global akm-cli\` or a standalone release, then run \`akm task sync --rebind\`.`);
     }
-    return {
-        sched,
-        plan: { ...plan, failures: [...failures, ...plan.failures] },
-        ...(runtime.publish ? { publish: runtime.publish } : {}),
-        warnings,
-    };
+    return { sched, plan: { ...plan, failures: [...failures, ...plan.failures] }, warnings };
 }
 /**
- * The launcher and descriptor rows are written with. The descriptor follows
- * the current policy on every sync; a row that is already installed keeps its
- * launcher unless `--rebind` (see `installOptionsFor`). An injected backend
- * (tests) renders with its own defaults.
+ * The launcher and environment rows are written with. The environment
+ * follows the current policy on every sync; a row that is already installed
+ * keeps its launcher unless `--rebind` (see `installOptionsFor`). An injected
+ * backend (tests) renders with its own launcher.
  */
 function prepareSchedulerRuntime(deps) {
+    const environment = scheduledRowEnvironment();
     if (deps.schedulerRuntime) {
         const runtime = deps.schedulerRuntime();
-        return {
-            options: { binding: runtime.binding, contextPath: runtime.contextPath },
-            ...(runtime.via ? { via: runtime.via } : {}),
-        };
+        return { options: { binding: runtime.binding, environment }, ...(runtime.via ? { via: runtime.via } : {}) };
     }
     if (deps.backend)
-        return {};
-    const descriptor = schedulerContextDescriptor();
+        return { options: { environment } };
     const invocation = resolveAkmInvocation();
-    return {
-        options: { binding: invocation.argv, contextPath: schedulerContextPath(descriptor) },
-        // The content-addressed descriptor is written once, before the first row that references it.
-        publish: () => {
-            writeSchedulerContextDescriptor(descriptor);
-        },
-        via: invocation.via,
-    };
+    return { options: { binding: invocation.argv, environment }, via: invocation.via };
 }
-/** One read of the akm-owned rows, each attributed to the bundle path its own descriptor names (#846). */
+/** One read of the akm-owned rows, each attributed to the bundle path it names (#846). */
 async function listInstalledRows(sched) {
     return (await sched.list()).map((row) => {
-        const ownerBundlePath = row.contextPath ? resolveInstalledOwnerPath(row.contextPath) : undefined;
+        const ownerBundlePath = installedRowBundleDir(row);
         return ownerBundlePath !== undefined ? { ...row, ownerBundlePath } : row;
     });
 }
-/** Best-effort recovery of an installed binding's owning bundle path (#846). */
-function resolveInstalledOwnerPath(contextPath) {
+/**
+ * The `AKM_BUNDLE_DIR` an installed row names: its inline one, or the one in
+ * the descriptor a row written before 0.9.17-alpha.7 references. Undefined
+ * when it names none, or its descriptor cannot be read — which never means
+ * "mine".
+ */
+function installedRowBundleDir(row) {
+    if (row.contextPath === undefined)
+        return row.environment?.AKM_BUNDLE_DIR;
     try {
-        return validateSchedulerContextDescriptor(contextPath).environment.AKM_BUNDLE_DIR;
+        return readLegacySchedulerContext(row.contextPath).AKM_BUNDLE_DIR;
     }
     catch {
         return undefined;
@@ -515,26 +505,34 @@ function installedSchedulerBundle(config, row) {
     return bundleKeyForContentRoot(config, row.ownerBundlePath);
 }
 /**
- * Why `akm task prune` (#851) would remove an installed row: its own
- * descriptor does not load (`invalid-context`) or names a bundle directory
- * that is gone (`dead-bundle-path`). A row that still resolves to a live
- * bundle is never a candidate.
+ * Why `akm task prune` (#851) would remove an installed row: a row written
+ * before 0.9.17-alpha.7 whose descriptor cannot be read (`invalid-context`),
+ * or one naming a bundle directory that is gone (`dead-bundle-path`). A row
+ * that still resolves to a live bundle is never a candidate.
  */
 function classifyPruneCandidate(entry) {
-    let ownerBundlePath;
-    try {
-        ownerBundlePath = validateSchedulerContextDescriptor(entry.contextPath).environment.AKM_BUNDLE_DIR;
+    let bundleDir;
+    if (entry.contextPath !== undefined) {
+        try {
+            bundleDir = readLegacySchedulerContext(entry.contextPath).AKM_BUNDLE_DIR;
+        }
+        catch {
+            return "invalid-context";
+        }
+        // Every descriptor akm wrote names the bundle; one that does not cannot be attributed.
+        if (bundleDir === undefined)
+            return "invalid-context";
     }
-    catch {
-        return "invalid-context";
+    else {
+        bundleDir = entry.environment?.AKM_BUNDLE_DIR;
     }
-    if (ownerBundlePath !== undefined && !fs.existsSync(ownerBundlePath))
+    if (bundleDir !== undefined && !fs.existsSync(bundleDir))
         return "dead-bundle-path";
     return undefined;
 }
 /**
  * `akm task prune` (#851): remove installed rows `sync` can never reclaim
- * because their descriptor no longer resolves to a live bundle. It scans
+ * because they no longer resolve to a live bundle. It scans
  * every installed row, not one bundle's. Without `--yes` it only previews and
  * writes nothing; `--id` narrows it to named candidates.
  */
@@ -655,7 +653,7 @@ function groupInstalledBindings(entries) {
         }
         groups.set(key, {
             argv,
-            contextPath: entry.contextPath,
+            ...(entry.contextPath !== undefined ? { contextPath: entry.contextPath } : {}),
             taskIds: [entry.id],
             status,
         });
@@ -669,13 +667,15 @@ function inspectInstalledBinding(entry) {
         status.push("checkout");
     if (binding.some((part) => part === "akm" || part === "bun" || part === "node"))
         status.push("path-selected");
-    try {
-        validateSchedulerContextDescriptor(entry.contextPath);
-    }
-    catch {
-        status.push("invalid-context");
+    if (entry.contextPath !== undefined) {
+        try {
+            readLegacySchedulerContext(entry.contextPath);
+        }
+        catch {
+            status.push("invalid-context");
+        }
     }
-    const absolutePaths = [...binding.filter((part) => path.isAbsolute(part)), entry.contextPath];
+    const absolutePaths = binding.filter((part) => path.isAbsolute(part));
     if (absolutePaths.some((part) => !fs.existsSync(part)))
         status.push("missing-path");
     if (status.length === 0)
@@ -734,8 +734,9 @@ export function resolveTaskReadBundle(refBundle, flagBundle) {
  * New scheduler bindings always carry a canonical `--bundle <owner>` token,
  * including an env-selected working stash. That stash need not be persisted in
  * config (CI, one-shot tools, and fresh installs commonly use only
- * AKM_BUNDLE_DIR), so its scheduled child must accept precisely its derived
- * owner name after the scheduler context restores the environment.
+ * AKM_BUNDLE_DIR), so its scheduled child — every row sets AKM_BUNDLE_DIR to
+ * the working stash it was synced from — must accept precisely its derived
+ * owner name.
  *
  * This is intentionally narrower than an unknown-bundle fallback: a configured
  * source always wins, and an unconfigured selector is accepted only when it is

package/dist/commands/tasks/validate.js

@@ -9,23 +9,20 @@
  * a bundle/adapter/concept id at all — it reads exactly the path it was
  * given and classifies it.
  *
- * Reuses the exact version-routing shim `parseTaskSource`
- * (`src/tasks/source/parse-task-source.ts`) already applies for every other
- * task-source reader (`akm task sync`'s `compileTaskSources` included) —
- * this module never forks a second parser or a second v2/v3 migration
- * planner. `readBoundedTaskSourceYaml` / `peekTaskSourceVersion` / `own` are
- * the SAME front-end helpers that shim itself calls first; they are used
- * here only to recover the file's ORIGINALLY DECLARED schema version for
- * the report, because `parseTaskSource`'s own `ParsedTaskSource.version` is
- * always `4` post-shim — it cannot answer "was this a v2/v3/v4 file?" on
- * its own once a v2/v3 source has been converted in memory.
+ * Reuses the exact version router `parseTaskSource`
+ * (`src/tasks/source/parse-task-source.ts`) every other task-source reader
+ * uses (`akm task sync`'s `compileTaskSources` included) — this module never
+ * forks a second parser. `readBoundedTaskSourceYaml` /
+ * `peekTaskSourceVersion` / `own` are the SAME front-end helpers the router
+ * calls first; they are used here only to recover the file's DECLARED schema
+ * version for the report and to tell `blocked` from `invalid`.
  *
  * Beyond parsing, this module also runs the SAME two per-source gates
  * `akm task sync`'s `compileTaskSources` runs before it ever installs a
  * schedule — `assertTaskScheduleInputsSatisfyContract` and
  * `assertTaskScheduleCronValid` (both extracted from `scheduler-sync.ts` for
  * exactly this reuse) — so a file `sync` would reject can never
- * be reported `valid`/`converts` here. Cron dialect is checked against
+ * be reported `valid` here. Cron dialect is checked against
  * `backendNameForPlatform()`, the same platform default `sync` falls back
  * to whenever it has no injected/native-inspected backend to hand (see
  * `akmTasksAdd`, `src/commands/tasks/tasks.ts`); a bare file was never
@@ -46,27 +43,18 @@
  *
  * Outcome classification (mirrors `parse-task-source.ts`'s own routing
  * table in its header, extended for the two gates above):
- *   - `valid`       — parses as task source v4 directly (declared `version: 4`)
- *                      and passes both sync gates.
- *   - `converts`    — declared `version: 2` or `3`; the deterministic
- *                      in-memory migrator produced a valid v4 document that
- *                      passes both sync gates. A declared `version: 4`
- *                      document whose only defect is a retired
- *                      `schedule[].enabled` key also reports `converts`
- *                      (`sourceVersion` is still `4`) — it read through the
- *                      same in-memory shim, not the direct v4 parse path.
- *   - `blocked`     — declared `version: 2` or `3`; the migrator itself
- *                      could not convert it (an ambiguous/unmigratable
- *                      shape) — the ONLY way `parseTaskSource` ever throws
- *                      for those two version numbers, so no message-text
- *                      sniffing is needed to tell this apart from `invalid`.
+ *   - `valid`       — parses as task source v4 and passes both sync gates.
+ *   - `blocked`     — declared `version: 2` or `3`, or a `version: 4`
+ *                      document still carrying the retired
+ *                      `schedule[].enabled`: what `akm migrate apply`
+ *                      rewrites. The runtime reads only v4 (#987), so the
+ *                      reason names that command.
  *   - `invalid`     — the document declares SOME version (`4`, or anything
  *                      other than 2/3/4) but fails to parse/validate, OR it
- *                      parsed (directly or via a SUCCESSFUL v2/v3
- *                      conversion) but fails one of the two sync gates
- *                      above, OR the YAML itself does not parse at all
- *                      (a genuine syntax error, not merely a non-task
- *                      shape) — reported with the parser's own reason.
+ *                      parsed but fails one of the two sync gates above, OR
+ *                      the YAML itself does not parse at all (a genuine
+ *                      syntax error, not merely a non-task shape) — reported
+ *                      with the parser's own reason.
  *   - `not-a-task`  — the document parses as YAML but never declares a
  *                      `version:` field at all (or isn't a YAML mapping) —
  *                      the strongest signal available that the file was
@@ -142,10 +130,11 @@ export async function akmTaskValidate(filePath) {
         if (!(cause instanceof UsageError))
             throw cause;
         const reason = cause.message;
-        // `parseTaskSource` only ever throws for a declared version 2/3 via the
-        // unmigratable-conversion branch (see this file's header) — no separate
-        // message check needed to recognize "blocked" here.
-        if (declaredVersion === 2 || declaredVersion === 3) {
+        // What `akm migrate apply` rewrites is the only refusal for these
+        // shapes (`parse-task-source.ts`), so no message-text sniffing is needed.
+        if (declaredVersion === 2 ||
+            declaredVersion === 3 ||
+            (declaredVersion === 4 && v4ScheduleHasRetiredEnabledKey(root))) {
             return { ok: false, path: resolvedPath, sourceVersion: declaredVersion, outcome: "blocked", reason };
         }
         if (peekFailed) {
@@ -163,13 +152,10 @@ export async function akmTaskValidate(filePath) {
         };
     }
     // Success is unreachable from any path that leaves `declaredVersion`
-    // undefined — the router requires a numeric 2/3/4 version to reach here.
+    // undefined — the router requires a numeric version 4 to reach here.
     const sourceVersion = declaredVersion ?? 4;
-    // The document itself parsed (directly, or via a successful v2/v3
-    // conversion) — now the two gates `compileTaskSources` runs before
-    // accepting it. A violation here is `invalid`, never `blocked`: the
-    // migrator already succeeded, so this is the same kind of defect a
-    // native v4 document with the identical schedule would have.
+    // The document itself parsed — now the two gates `compileTaskSources`
+    // runs before accepting it. A violation here is `invalid`.
     try {
         assertTaskScheduleInputsSatisfyContract(parsed.v4, resolvedPath);
         assertTaskScheduleCronValid(parsed.v4, backend);
@@ -179,17 +165,12 @@ export async function akmTaskValidate(filePath) {
             throw cause;
         return { ok: false, path: resolvedPath, sourceVersion, outcome: "invalid", reason: cause.message };
     }
-    // A declared `version: 4` document with a retired `schedule[].enabled`
-    // key parsed through `parseTaskSource`'s in-memory shim, not the direct
-    // v4 path, even though `sourceVersion` reads `4` — report it the same
-    // way a converted v2/v3 document is reported.
-    const convertedFromRetiredScheduleEnabled = sourceVersion === 4 && !peekFailed && v4ScheduleHasRetiredEnabledKey(root);
     const id = path.parse(resolvedPath).name;
     return {
         ok: true,
         path: resolvedPath,
         sourceVersion,
-        outcome: sourceVersion === 2 || sourceVersion === 3 || convertedFromRetiredScheduleEnabled ? "converts" : "valid",
+        outcome: "valid",
         resolved: buildResolved(id, parsed.v4),
     };
 }

package/dist/core/adapter/adapters/akm-adapter.js

@@ -193,6 +193,8 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "wikiRole",
     "sources",
     "evidenceSources",
+    // #935: a workflow's step targets and a task's target, read as declared links.
+    "uses",
     // D2 (#730): the OKF v0.2 provenance `promoteProposal` stamps onto AKM-native
     // writes (generated/verified/sources, namespaced — see `types.ts`'s
     // `OkfProvenance` doc). Carried so the akm adapter rereads what it wrote and

package/dist/core/adapter/adapters/akm-metadata.js

@@ -54,6 +54,7 @@
  * concern (Chunk 4/5), not recognition's. On the valid Chunk-0b fixture this
  * distinction never triggers.
  */
+import { parseBuiltinCommandAction } from "../../../commands/command/builtin-action.js";
 import { scanEnvKeyNames } from "../../../commands/env/env.js";
 import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { compileWorkflowSource, workflowStepInstructions } from "../../../workflows/compile.js";
@@ -125,6 +126,25 @@ function applyFrontmatterDescriptionAndTags(fm, out) {
         }
     }
 }
+/** The command a stored `akm/command` action runs; inline content names no asset. */
+function storedCommandRef(action) {
+    return action?.kind === "stored" ? action.ref : undefined;
+}
+/** The asset a workflow step targets: its `uses:` ref, or the ref of a stored `akm/command`. Prose and `run:` steps target none. */
+function workflowStepTarget(spec) {
+    if (!spec?.uses)
+        return undefined;
+    if (spec.uses !== "akm/command")
+        return spec.uses;
+    if (spec.commandMode !== "stored-ref")
+        return undefined;
+    try {
+        return storedCommandRef(parseBuiltinCommandAction(spec.with));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Collect + finalize a searchHints set the way every contributor does (`Array.from(hints).filter(Boolean)`, assigned only when non-empty). */
 function finalizeHints(out, hints) {
     if (hints.size > 0)
@@ -245,6 +265,9 @@ export function foldRecognizedMetadata(rendererName, file) {
                         hints.add(`prompt:${target.command.ref}`);
                     else
                         hints.add(`uses:${target.uses.ref}`);
+                    const used = target.uses.kind !== "builtin-command" ? target.uses.ref : storedCommandRef(target.command);
+                    if (used)
+                        out.uses = [used];
                 }
                 else {
                     hints.add(`run:${target.run}`);
@@ -321,6 +344,7 @@ export function foldRecognizedMetadata(rendererName, file) {
                     return out;
                 const plan = result.plan;
                 const hints = new Set();
+                const uses = new Set();
                 if (plan.preamble)
                     hints.add(plan.preamble);
                 for (const step of plan.steps) {
@@ -328,8 +352,13 @@ export function foldRecognizedMetadata(rendererName, file) {
                     hints.add(workflowStepInstructions(step));
                     if (step.gate.criteria[0])
                         hints.add(step.gate.criteria[0]);
+                    const used = workflowStepTarget(step.spec);
+                    if (used)
+                        uses.add(used);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
+                if (uses.size > 0)
+                    out.uses = [...uses];
                 if (plan.paramSchemas) {
                     const parameters = Object.entries(plan.paramSchemas).map(([name, schema]) => {
                         const description = schema.description;
@@ -395,4 +424,6 @@ export function applyFoldedMetadata(entry, folded) {
         entry.toc = folded.toc;
     if (folded.parameters)
         entry.parameters = folded.parameters;
+    if (folded.uses)
+        entry.uses = folded.uses;
 }

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -17,11 +17,9 @@
  * ── validate (spec §6 task validation column) ──
  *
  * Validation enters the canonical task source parser (`parseTaskSource`,
- * task source v4 native as of P4 — a `version: 3` or `version: 2` document
- * is auto-read through the in-memory migration shim in
- * `parse-task-source.ts`; only a version the shim's deterministic planners
- * cannot convert, or any other unsupported number, fails closed with
- * `TASK_SCHEMA_VERSION_UNSUPPORTED`). That parser owns the closed key sets,
+ * which reads only task source v4 — a `version: 2` or `version: 3`
+ * document fails closed with `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming
+ * `akm migrate apply`, which converts it). That parser owns the closed key sets,
  * the executable-selector XOR, hostile YAML policy, the `akm/command`
  * builtin, bounds, and physical `working-directory` containment. The
  * adapter only translates a parser failure into the format-family
@@ -33,7 +31,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
+import { readBoundedTaskSourceYaml } from "../../../tasks/source/bounded-document.js";
+import { parseTaskSource, peekTaskSourceVersion } from "../../../tasks/source/parse-task-source.js";
 import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskSourceErrorDetail, } from "../../../tasks/source-v3.js";
 import { toPosix } from "../../common.js";
 import { hashContent } from "./shared.js";
@@ -125,8 +124,11 @@ export const akmTaskAdapter = {
         return ["."];
     },
     /**
-     * Install-time probe (§1.2): a root holding a top-level, valid task-v3
-     * `.yml` file. The full parser keeps this disjoint from unrelated YAML and
+     * Install-time probe (§1.2): a root holding a top-level, valid task source
+     * v4 `.yml` file, or a task v2/v3 file that `akm migrate apply` has yet to
+     * convert (the runtime refuses those, so without this the migrator and
+     * `akm task sync` would not find them in a bundle whose adapter config does
+     * not record). The full parser keeps this disjoint from unrelated YAML and
      * prevents probe semantics from drifting from validation semantics.
      */
     looksLikeRoot(root) {
@@ -152,9 +154,28 @@ export const akmTaskAdapter = {
                 return true;
             }
             catch {
+                if (isLegacyTaskDocument(raw, entry.name))
+                    return true;
                 // Continue probing the remaining top-level .yml files.
             }
         }
         return false;
     },
 };
+/** The executable keys each retired task schema version required one of. */
+const LEGACY_TASK_TARGET_KEYS = {
+    2: ["workflow", "prompt", "command"],
+    3: ["uses", "run"],
+};
+/** A task v2/v3 document: its schema version, plus a target key that version used. */
+function isLegacyTaskDocument(yaml, filePath) {
+    let root;
+    try {
+        root = readBoundedTaskSourceYaml({ yaml, filePath }, { sourceLabel: "task source" }).root;
+    }
+    catch {
+        return false;
+    }
+    const keys = LEGACY_TASK_TARGET_KEYS[peekTaskSourceVersion(root) ?? 0];
+    return keys !== undefined && keys.some((key) => Object.hasOwn(root, key));
+}