akm-cli 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -4,7 +4,79 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.9.4] - 2026-08-30
+
+### Changed
+
+- **Node.js 22 support is restored for the npm package.** 0.9.3 raised the
+  npm bootstrap floor to Node >= 24 as a policy simplification; no code in
+  the package actually requires a Node-24-only API, and the pinned
+  better-sqlite3 12.11.1 ships a prebuilt binary for Node 22 (ABI 127), so
+  nothing compiles from source. The floor returns to Node >= 22 across the
+  preinstall check, the CLI bootstrap guard, and the pinned-registry
+  helper, and the CI node-smoke matrix again runs BOTH Node 22 and 24 so
+  the supported floor is tested on every run, not merely declared.
+
+### Added
+
+- **`akm task sync --dry-run` previews the reconcile without touching the
+  scheduler (#849).** Prints the planned adds/updates/removes — removals
+  now carry their owning bundle — makes zero scheduler writes, and exits
+  non-zero when removals are pending so scripts can gate on it. The plan
+  renderer is shared, ready for the planned `task prune` (#851) to reuse.
+- **Search hits now report which stage of the progressive AND->OR lexical
+  ladder produced them (#856).** `akm search` already ran strict AND, then
+  prefix AND, then an OR/prefix-OR recovery, stopping at the first stage
+  that returned candidates — but callers had no way to tell a strict match
+  from a heavily relaxed one. Local bundle hits now carry an optional
+  `matchStage: "exact" | "prefix" | "relaxed"` field (omitted for hits with
+  no FTS component, e.g. a pure-semantic hybrid contribution), surfaced at
+  `--detail normal`, `--detail full`, and `--shape agent` across all output
+  formats. Purely additive; no `schemaVersion` bump.
+- **Previous-release corpus test.** New
+  `tests/integration/previous-release-corpus.test.ts` holds fixtures of
+  data shapes prior releases actually wrote (task v2/v3 sources, pre-#858
+  proposal rows) and asserts the current CLI reads or auto-handles every
+  one. Policy: every schema bump must add the old shape here — this suite
+  failing means an upgrade break was about to ship.
+
+### Fixed
+
+- **`akm show`, `task run`/`explain`, `workflow run`/`plan`, and
+  `command run` no longer fail on bundles past 16,384 files (#857).**
+  Single-ref owner resolution walked the entire bundle tree on every
+  lookup, aborting with `file limit 16384 exceeded` once a bundle grew past
+  the cap — normal `improve` output accumulation was enough to get there.
+  Path-to-conceptId derivation is deterministic, so its inverse is now
+  computed in closed form: each adapter's `readCandidates` enumerates every
+  physical spelling that could own a conceptId (canonical placement, loose
+  off-canonical fallback, env `.env` duality) and the existing
+  verification/collision pipeline runs over that fixed set. The tree walk,
+  both scan caps, and `AdapterConceptScanError` are gone — no cap is needed
+  when nothing walks. Collision guarantees are unchanged (the pinned
+  loose-vs-canonical conformance case still throws), and symlinked
+  off-canonical files are now reachable where the old scan skipped them.
+- **`akm health --report` and `akm proposal list --status accepted` no
+  longer crash on proposal rows written before the `changes` metadata
+  envelope existed (#858), and `improve` outcome-score salience no longer
+  silently computes from zero accepted-counts (#859).** ~89% of real
+  archived accepted/rejected rows predate the field and can never recover
+  it; `storedToChanges` now treats a fully-absent `changes` key as a
+  documented legacy gap (empty change list — the rows still count toward
+  accepted/rejected history), `listStateProposals` skips-and-warns on
+  genuinely corrupt rows instead of aborting the whole list, and the write
+  path still refuses to persist a new proposal without changes.
+- **Task v2/v3 sources are auto-read as v4 instead of hard-failing with
+  `TASK_SCHEMA_VERSION_UNSUPPORTED`.** The v4 source gate would have broken
+  every pre-0.9.4 scheduled task headlessly on upgrade until the operator
+  manually ran `akm migrate apply`. `parseTaskSource` now runs the same
+  pure, deterministic migration planners the migrator uses (chained
+  v2->v3->v4) entirely in memory, emits a one-line stderr deprecation
+  warning, and never writes the file; the hard error survives only for
+  sources the deterministic conversion genuinely cannot translate.
+  `akm migrate apply` remains the way to rewrite files on disk and silence
+  the warning. The planner core moved from `scripts/akm-migrate/` into
+  `src/tasks/source/` so there is exactly one copy.
 
 ## [0.9.3] - 2026-08-29
 

package/README.md

@@ -16,7 +16,7 @@ assistant, including [Claude Code](https://claude.ai/code),
 
 ## Install
 
-**Option 1 — npm package (recommended; requires [Node.js](https://nodejs.org) >= 24):**
+**Option 1 — npm package (recommended; requires [Node.js](https://nodejs.org) >= 22):**
 
 ```sh
 npm install -g akm-cli

package/SECURITY.md

@@ -96,7 +96,7 @@ containing secrets or private notes.
 
 ## Known non-issues
 
-- **The `akm-cli` npm package requires Node.js >= 24 as its bootstrap.** A
+- **The `akm-cli` npm package requires Node.js >= 22 as its bootstrap.** A
   working Bun >= 1.0 is preferred for execution when it is also on `PATH`; old,
   unusable, or absent Bun installations fall back to Node.js. Bun does not
   remove the package's Node.js requirement. Standalone binaries are

package/STABILITY.md

@@ -220,7 +220,7 @@ enumeration of the whole `proposal` noun group.
   | `78` | Configuration error |
 - **Install scripts** — `install.sh` and `install.ps1` URLs; the `--prefix`
   / `AKM_INSTALL_DIR` environment override.
-- **Runtime** — the npm package requires Node.js >= 24 as its bootstrap and
+- **Runtime** — the npm package requires Node.js >= 22 as its bootstrap and
   prefers a working Bun >= 1.0 for execution when both are available; old,
   unusable, or absent Bun installations fall back to Node.js. Standalone
   binaries are runtime-free.

package/dist/akm

@@ -120,8 +120,8 @@ if (contextValid) {
 
   if (!process.versions.bun) {
     const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
-    if (major < 24) {
-      console.error("The akm-cli npm package requires Node.js >= 24 to bootstrap.");
+    if (major < 22) {
+      console.error("The akm-cli npm package requires Node.js >= 22 to bootstrap.");
       process.exit(1);
     }
   }

package/dist/akm-migrate

@@ -8,8 +8,8 @@ import { fileURLToPath } from "node:url";
 
 if (!process.versions.bun) {
   const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
-  if (major < 24) {
-    console.error("The akm-cli npm package requires Node.js >= 24 to bootstrap.");
+  if (major < 22) {
+    console.error("The akm-cli npm package requires Node.js >= 22 to bootstrap.");
     process.exit(1);
   }
 }

package/dist/cli.js

@@ -2,22 +2,22 @@
 // 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/.
-// Runtime guard: the akm-cli npm package bootstraps with Node.js >= 24
+// Runtime guard: the akm-cli npm package bootstraps with Node.js >= 22
 // (#465, #560), then its launcher prefers a working Bun >= 1.0 when available.
 // The runtime boundary (src/runtime.ts, src/storage/database.ts) supports both.
 // Under Node the CLI must be launched via the
 // `dist/cli-node.mjs` wrapper, which registers the text-import loader hook
 // before this module graph loads; running `node dist/cli.js` directly still
 // works for code paths that touch no embedded text asset, but the wrapper is
-// the supported entry. The hard floor is Node 24; Node 22 is no longer a
-// supported npm bootstrap runtime.
+// the supported entry. The hard floor is Node 22 (Node 20 support dropped 2026-07; `@clack/core` imports
+// `node:util`'s `styleText` (added in Node 20.12) — Node 18 (EOL) throws at import.
 {
     const isBun = typeof globalThis.Bun !== "undefined";
     if (!isBun) {
         const [major = 0] = (process.versions.node ?? "0").split(".").map((part) => Number.parseInt(part, 10) || 0);
-        const nodeOk = major >= 24;
+        const nodeOk = major >= 22;
         if (!nodeOk) {
-            console.error("\n  ERROR: the akm-cli npm package requires Node.js >= 24.\n" +
+            console.error("\n  ERROR: the akm-cli npm package requires Node.js >= 22.\n" +
                 `  Detected Node.js ${process.versions.node ?? "unknown"}.\n` +
                 "  Bun >= 1.0 is optional for execution; it does not replace the Node.js bootstrap.\n" +
                 "  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\n" +

package/dist/commands/health/improve-metrics.js

@@ -15,6 +15,23 @@ export function parseTaskMetadata(row) {
         ...(metadata.engine !== undefined ? { engine: metadata.engine } : {}),
     };
 }
+/**
+ * `parseTaskMetadata`, but per-row skip-and-warn instead of throwing (mirrors
+ * `listStateProposals`). `decodeTaskHistoryMetadata` already tolerates
+ * legacy/additive shapes; only genuine corruption reaches this catch, and a
+ * corrupt row must degrade the metric (excluded, not fatal) rather than abort
+ * the whole `akm health` computation.
+ */
+export function taskFailureDetail(row) {
+    try {
+        return parseTaskMetadata(row).detail;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[akm] Skipping unparseable task_history row in agent-failure-rate (task_id=${row.task_id}, started_at=${row.started_at}): ${message}`);
+        return undefined;
+    }
+}
 /**
  * D8 read-boundary predicate (spec docs/plans/specs/p1b-model-extraction.md
  * §5.3) for `akm health`'s `agentFailureRate`: true for a `task_history` row

package/dist/commands/health/windows.js

@@ -11,7 +11,7 @@ import { readEvents } from "../../core/events.js";
 import { buildTaskRunId, getLoggedRunIds } from "../../core/logs-db.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { queryTaskHistory } from "../../storage/repositories/task-history-repository.js";
-import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./improve-metrics.js";
+import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./improve-metrics.js";
 import { readLlmUsageAggregate } from "./llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage } from "./metrics.js";
 import { buildPerRunSummaries } from "./task-runs.js";
@@ -154,7 +154,7 @@ export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Da
     // isAgentTaskHistoryRow's header comment for the full mapping).
     const agentRows = taskRows.filter((row) => isAgentTaskHistoryRow(row));
     const agentFailures = agentRows.filter((row) => {
-        const detail = parseTaskMetadata(row).detail;
+        const detail = taskFailureDetail(row);
         return typeof detail?.reason === "string" && detail.reason.length > 0;
     });
     const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;

package/dist/commands/health.js

@@ -20,7 +20,7 @@ import { queryTaskHistory } from "../storage/repositories/task-history-repositor
 import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS, runHealthEngineProbes } from "./health/checks.js";
-import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./health/improve-metrics.js";
+import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
 import { collectPluginStalenessAdvisories } from "./health/plugin-staleness.js";
@@ -130,7 +130,7 @@ function gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now) {
     // isAgentTaskHistoryRow's header comment for the full mapping).
     const agentRows = taskRows.filter((row) => isAgentTaskHistoryRow(row));
     const agentFailures = agentRows.filter((row) => {
-        const detail = parseTaskMetadata(row).detail;
+        const detail = taskFailureDetail(row);
         return typeof detail?.reason === "string" && detail.reason.length > 0;
     });
     const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;

package/dist/commands/improve/preparation.js

@@ -1744,6 +1744,13 @@ function updateOutcomeScores(args) {
             // inflate counts with proposals from other stashes.
             const acceptedCountByRef = new Map();
             try {
+                // #858/#859: listStateProposals() now skips-and-warns on individual
+                // unparseable rows (including legacy pre-#578 rows with no
+                // persisted `changes`, which it tolerates directly) instead of
+                // throwing, so this no longer silently zeroes out every ref's
+                // count on a single bad row. The outer try/catch stays as a
+                // defense-in-depth fallback for unexpected failures (e.g. a query
+                // error), not the primary safeguard it used to be.
                 const acceptedProposals = listStateProposals(outcomeDb, {
                     status: "accepted",
                     ...(primaryStashDir ? { stashDir: primaryStashDir } : {}),
@@ -1753,7 +1760,7 @@ function updateOutcomeScores(args) {
                 }
             }
             catch {
-                // best-effort: if proposals query fails, accepted counts stay at 0
+                // best-effort: if the query itself fails, accepted counts stay at 0
             }
             // Update each ref's outcome row and collect the resulting outcome scores.
             const rawOutcomeScores = new Map();

package/dist/commands/lint/index.js

@@ -11,7 +11,7 @@ import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
 import { deriveBundleIds } from "../../core/bundle-id.js";
-import { resolveStashDir } from "../../core/common.js";
+import { isAkmRegistryCachePath, resolveStashDir } from "../../core/common.js";
 import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
@@ -80,10 +80,6 @@ function collectMarkdownFiles(dir, caseInsensitive = false) {
     }
     return results;
 }
-function isCachedLintPath(filePath) {
-    const posixPath = filePath.replace(/\\/g, "/");
-    return posixPath.includes("/.cache/") || posixPath.includes("/registry/");
-}
 /** Peer workflow sources accepted by the source-IR compiler; `.yaml` remains unsupported. */
 function collectWorkflowFiles(dir) {
     if (!fs.existsSync(dir))
@@ -546,7 +542,7 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
                 : collectMarkdownFiles(dirPath, true);
         let assetFiles = subdir === "workflows" ? files.filter((file) => path.basename(file).toLowerCase() !== "readme.md") : files;
         if (subdir === "workflows") {
-            assetFiles = assetFiles.filter((file) => !isCachedLintPath(file));
+            assetFiles = assetFiles.filter((file) => !isAkmRegistryCachePath(file));
             const ownership = resolveWorkflowLintOwnership(stashRoot, assetFiles);
             assetFiles = ownership.files;
             flagged.push(...ownership.issues);
@@ -575,7 +571,7 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             // Compare on a separator-normalized copy: on Windows these paths carry
             // backslashes, so the forward-slash substring never matched and --fix
             // rewrote files inside the registry cache.
-            if (isCachedLintPath(filePath))
+            if (isAkmRegistryCachePath(filePath))
                 continue;
             const relPath = path.relative(stashRoot, filePath);
             let raw;

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

@@ -27,11 +27,11 @@
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS } from "../../tasks/task-run-reserved-flags.js";
 import { akmTaskExplain } from "./explain.js";
-import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksRun, akmTasksSync } from "./tasks.js";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksRun, akmTasksSync, akmTasksSyncPlan } from "./tasks.js";
 /** Shared `--bundle <bundle>` arg wired onto every task subcommand. */
 const bundleArg = {
     bundle: {
@@ -303,6 +303,15 @@ const tasksHistoryCommand = defineJsonCommand({
         output("task-history", result);
     },
 });
+/**
+ * #849: `task sync --dry-run`'s exit-code contract, "non-zero when the plan
+ * contains removals" — factored out as a pure function (rather than left
+ * inline in the command's `run()`) so it's directly unit-testable without
+ * driving the whole CLI through a real scheduler backend.
+ */
+export function taskSyncDryRunExitCode(preview) {
+    return preview.hasRemovals ? EXIT_CODES.GENERAL : undefined;
+}
 const tasksSyncCommand = defineJsonCommand({
     meta: {
         name: "sync",
@@ -315,10 +324,26 @@ const tasksSyncCommand = defineJsonCommand({
             description: "Replace installed bindings with the current invocation",
             default: false,
         },
+        "dry-run": {
+            type: "boolean",
+            description: "Compute and print the full reconcile plan (adds/updates/removes, with owning bundle on every " +
+                "removal) without touching the OS scheduler. Zero durable writes. Exits non-zero when the plan " +
+                "contains removals.",
+            default: false,
+        },
     },
     async run({ args }) {
         rejectRetiredTaskTargetFlag();
-        const result = await akmTasksSync({}, args.bundle, { rebind: args.rebind === true });
+        const rebind = args.rebind === true;
+        if (args["dry-run"] === true) {
+            const preview = await akmTasksSyncPlan({}, args.bundle, { rebind });
+            output("task-sync-dry-run", preview);
+            const exitCode = taskSyncDryRunExitCode(preview);
+            if (exitCode !== undefined)
+                process.exitCode = exitCode;
+            return;
+        }
+        const result = await akmTasksSync({}, args.bundle, { rebind });
         output("task-sync", result);
     },
 });

package/dist/commands/tasks/tasks.js

@@ -36,6 +36,7 @@ import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/sched
 import { assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "../../tasks/scheduler-binding.js";
 import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
 import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
+import { renderSchedulerSyncPlanPreview } from "../../tasks/scheduler-sync-preview.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
 import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
 import { TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
@@ -326,7 +327,16 @@ export async function akmTasksHistory(input) {
  * scans all bundles. Activation happens only through explicit `add --bundle`
  * (or `sync --bundle` on a bundle whose task files are already present).
  */
-export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
+/**
+ * Compute (but never apply) a scheduler sync plan: everything through
+ * `finalizeSchedulerSyncPlan`'s final call, stopping strictly before
+ * `applySchedulerSyncPlan`. Shared by `akmTasksSync` (applies the plan) and
+ * `akmTasksSyncPlan` (#849 `--dry-run`, never applies it) so the two paths
+ * can never drift on what "the plan" means. `prepared?.publish`, the one
+ * deferred write-producing closure in this pipeline, is returned but never
+ * invoked here — only `applySchedulerSyncPlan` may call it.
+ */
+async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const resolved = resolveTaskReadBundle(undefined, bundleTarget);
     const config = loadConfig();
     const stashDir = resolved.source.path;
@@ -393,6 +403,10 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
             }
             : {}),
     }, preparedSources);
+    return { sched, plan, prepared, warnings };
+}
+export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
+    const { sched, plan, prepared, warnings } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
     await applySchedulerSyncPlan(sched, plan, prepared?.publish && plan.operations.some((operation) => operation.kind !== "remove")
         ? prepared.publish
         : undefined);
@@ -406,6 +420,20 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
+/**
+ * `akm task sync --dry-run` (#849): compute the exact same plan
+ * `akmTasksSync` would apply, then return a non-mutating preview instead of
+ * calling `applySchedulerSyncPlan`. `buildSchedulerSyncPlan` is shared with
+ * the real sync path specifically so this can never see a different plan
+ * than the one a real sync would apply — and specifically so this function
+ * never even holds a reference to a callable `publish` closure past this
+ * point: `prepared.publish`, if any, is dropped on the floor here, never
+ * invoked. Zero durable writes, mirroring `akm workflow plan`.
+ */
+export async function akmTasksSyncPlan(deps = {}, bundleTarget, options = {}) {
+    const { sched, plan } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
+    return renderSchedulerSyncPlanPreview(sched.name, plan);
+}
 export async function akmTasksDoctor(deps = {}) {
     const warnings = [];
     let invocation = {

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

@@ -82,10 +82,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, } from "../../../indexer/passes/metadata.js";
-import { assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
+import { assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
-import { recognizeMatch, recognizePathCandidateMatches } from "../recognize-match.js";
+import { recognizeMatch } from "../recognize-match.js";
 import { perTypeValidateChecks, skillDirectoryDiagnostics, workflowYamlSourceDiagnostics } from "./akm-lint.js";
 import { applyFoldedMetadata, foldRecognizedMetadata } from "./akm-metadata.js";
 import { hashContent, runBaseValidateChecks } from "./shared.js";
@@ -252,14 +252,6 @@ function conceptIdForRecognizedType(root, filePath, type) {
     const stashDir = stashDirFor(type);
     return stashDir !== undefined ? `${stashDir}/${canonicalName}` : canonicalName;
 }
-function recognizePathCandidates(c, file) {
-    if (isReservedFileName(file.fileName) || akmStashAbstains(c.root, file.absPath))
-        return [];
-    return recognizePathCandidateMatches(file).flatMap((match) => {
-        const conceptId = conceptIdForRecognizedType(c.root, file.absPath, match.type);
-        return conceptId === undefined ? [] : [conceptId];
-    });
-}
 function recognize(c, file) {
     // D-R6 (spec §5.1): `index.md` / `log.md` are OKF reserved structural files at
     // every depth — never items. Excluded BEFORE classification so a directory
@@ -481,9 +473,19 @@ export const akmAdapter = {
         ".kts",
     ],
     recognize,
-    recognizePathCandidates,
     renderExecutionSource,
     validate,
+    /**
+     * Closed-form owner candidates (#857): every physical path spelling that
+     * could claim `conceptId` without walking the bundle. `deriveCanonicalAssetNameFromStashRoot`
+     * (recognize's own conceptId derivation) is a pure function of (type,
+     * filePath); this is its inverse, enumerated for the two placements that
+     * function can produce for one conceptId — CANONICAL (authored under the
+     * type's own stash subdir) and the LOOSE FALLBACK (authored anywhere else
+     * in the bundle, so the canonical name is the file's full path relative to
+     * the bundle root instead of the stash subdir). `assetPathCandidatesForName`
+     * additionally expands `env`'s `.env`/`<name>.env` duality on each.
+     */
     readCandidates(c, conceptId) {
         const posix = conceptId.replace(/\\/g, "/");
         const slash = posix.indexOf("/");
@@ -492,9 +494,14 @@ export const akmAdapter = {
         const head = posix.slice(0, slash);
         const rest = posix.slice(slash + 1);
         const type = stashDirToType(head);
-        return type === undefined || rest.length === 0
-            ? []
-            : [{ path: assetPathForName(type, path.join(c.root, head), rest), conceptId: posix }];
+        if (type === undefined || rest.length === 0)
+            return [];
+        const canonical = assetPathCandidatesForName(type, path.join(c.root, head), rest);
+        const loose = assetPathCandidatesForName(type, c.root, rest);
+        return [...new Set([...canonical, ...loose])].map((candidatePath) => ({
+            path: candidatePath,
+            conceptId: posix,
+        }));
     },
     /**
      * Type-driven placement (§5.1), reproducing `path-resolver.ts#buildDiskCandidates`:

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

@@ -57,6 +57,7 @@ import { taskSourceErrorDetail } from "../../../tasks/source-v3.js";
 import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
 import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
 import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
+import { isAkmRegistryCachePath } from "../../common.js";
 /** Recommended `category` values for facts — `commands/lint/fact-linter.ts:9`. */
 const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
 /** Placeholder markers a workflow stub carries — `commands/lint/workflow-linter.ts:10`. */
@@ -336,7 +337,7 @@ function lineOf(err) {
  * like the established Markdown frontend without inventing another parser.
  */
 export function workflowYamlSourceDiagnostics(relPath, raw, parsePath, workspaceRoot) {
-    if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
+    if (isAkmRegistryCachePath(parsePath))
         return { errors: [], warnings: [] };
     const compiled = compileWorkflowSource(raw, { path: parsePath, workspaceRoot });
     if (compiled.ok)
@@ -369,7 +370,7 @@ export function workflowYamlSourceDiagnostics(relPath, raw, parsePath, workspace
  */
 export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
     const none = { errors: [], warnings: [] };
-    if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
+    if (isAkmRegistryCachePath(parsePath))
         return none;
     const errors = [];
     const warnings = [];

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

@@ -17,12 +17,15 @@
  * ── validate (spec §6 task validation column) ──
  *
  * Validation enters the canonical task source parser (`parseTaskSource`,
- * task source v4 only as of P4 — a `version: 3` or `version: 2` document now
- * fails closed with `TASK_SCHEMA_VERSION_UNSUPPORTED`). 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 diagnostic shape.
+ * 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,
+ * 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
+ * diagnostic shape.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens

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

@@ -29,7 +29,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { assetPathForName, typeForStashDir } from "../../asset/asset-placement.js";
+import { assetPathCandidatesForName, assetPathForName, typeForStashDir } from "../../asset/asset-placement.js";
 import { dangerousEnvKeyDiagnostics } from "./akm-lint.js";
 import { hashContent } from "./shared.js";
 /** A dotenv bundle is single-component; its one component is `main`. */
@@ -103,12 +103,6 @@ function conceptIdForPath(type, relativePath) {
     const stripped = posix.replace(/\.env$/i, "");
     return stripped.endsWith("/") ? `${stripped}default` : stripped;
 }
-function recognizePathCandidates(_c, file) {
-    const type = classify(file.relPath);
-    if (type === null || hasSensitiveMarker(file.absPath, type))
-        return [];
-    return [conceptIdForPath(type, file.relPath)];
-}
 function recognize(c, file) {
     const type = classify(file.relPath);
     if (type === null)
@@ -172,8 +166,15 @@ export const dotenvAdapter = {
     version: "0.9.0",
     extensions: [".env"],
     recognize,
-    recognizePathCandidates,
     validate,
+    /**
+     * Closed-form owner candidates (#857): `env`/`secret` are always authored
+     * directly under their own stash subdir (`classify` requires it — no
+     * off-canonical loose placement exists for this adapter), so there is no
+     * loose-fallback class to enumerate here, unlike `akm-adapter`.
+     * `assetPathCandidatesForName` expands `env`'s `.env`/`<name>.env` duality;
+     * the sensitive-marker sibling spellings are then layered on each.
+     */
     readCandidates(c, conceptId) {
         const posix = toPosix(conceptId);
         const slash = posix.indexOf("/");
@@ -184,10 +185,11 @@ export const dotenvAdapter = {
         const type = typeForStashDir(head);
         if ((type !== "env" && type !== "secret") || rest.length === 0)
             return [];
-        const primary = assetPathForName(type, path.join(c.root, head), rest);
-        return (type === "env"
+        const primaries = assetPathCandidatesForName(type, path.join(c.root, head), rest);
+        const expanded = primaries.flatMap((primary) => type === "env"
             ? [primary, primary.replace(/\.env$/i, ".sensitive")]
-            : [primary, `${primary}.sensitive`, `${primary}.lock`]).map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
+            : [primary, `${primary}.sensitive`, `${primary}.lock`]);
+        return expanded.map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
     },
     /**
      * env places to `env/<name>.env`, secret to `secrets/<name>` (identity join,

package/dist/core/adapter/recognize-match.js

@@ -1,7 +1,7 @@
 // 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 { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher, smartMdPathCandidates, } from "../../indexer/walk/matchers.js";
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher } from "../../indexer/walk/matchers.js";
 /**
  * The four builtin matchers, in registration order. The array index IS the
  * registration index `runMatchers` uses for tie-breaking. (The `wiki` matcher
@@ -46,22 +46,3 @@ export function recognizeMatch(file) {
     }
     return winningMatch(hits);
 }
-/**
- * Every AKM matcher winner possible from path fields alone. The three
- * path-only matchers run exactly as production does; each possible result of
- * the shared smart-Markdown fact table is then arbitrated at its real index.
- */
-export function recognizePathCandidateMatches(file) {
-    const fileContext = file;
-    const pathHits = [extensionMatcher, directoryMatcher, parentDirHintMatcher].flatMap((matcher, index) => {
-        const result = matcher(fileContext);
-        return result ? [{ result, index }] : [];
-    });
-    const smartCandidates = smartMdPathCandidates(file);
-    const variants = smartCandidates.length > 0 ? smartCandidates : [undefined];
-    const winners = variants.flatMap((smart) => {
-        const winner = winningMatch(smart ? [...pathHits, { result: smart, index: 3 }] : [...pathHits]);
-        return winner ? [winner] : [];
-    });
-    return [...new Map(winners.map((winner) => [`${winner.type}\0${winner.renderer}`, winner])).values()];
-}