akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/commands/tasks/validate.js

@@ -9,18 +9,23 @@
  * a bundle/adapter/concept id at all — it reads exactly the path it was
  * given and classifies it.
  *
- * Reuses the exact current-schema router `parseTaskSource`
- * (`src/tasks/source/parse-task-source.ts`) used by every other task-source
- * reader. Historical v2/v3 documents are deliberately rejected here and
- * point to `akm migrate apply`; validation does not embed a second legacy
- * parser or perform an in-memory migration.
+ * 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.
  *
  * 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` here. Cron dialect is checked against
+ * be reported `valid`/`converts` 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
@@ -43,12 +48,23 @@
  * 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.
- *   - `blocked`     — declared `version: 2` or `3`; runtime does not accept
- *                      it and the explicit migrator must rewrite it first.
+ *   - `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`.
  *   - `invalid`     — the document declares SOME version (`4`, or anything
  *                      other than 2/3/4) but fails to parse/validate, OR it
- *                      parsed but fails one of the two sync gates above, OR
- *                      the YAML itself does not parse at all
+ *                      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.
  *   - `not-a-task`  — the document parses as YAML but never declares a
@@ -62,7 +78,7 @@ import { UsageError } from "../../core/errors.js";
 import { backendNameForPlatform } from "../../tasks/backends/index.js";
 import { assertTaskScheduleCronValid, assertTaskScheduleInputsSatisfyContract } from "../../tasks/scheduler-sync.js";
 import { own, readBoundedTaskSourceYaml } from "../../tasks/source/bounded-document.js";
-import { parseTaskSource, peekTaskSourceVersion } from "../../tasks/source/parse-task-source.js";
+import { parseTaskSource, peekTaskSourceVersion, v4ScheduleHasRetiredEnabledKey, } from "../../tasks/source/parse-task-source.js";
 /** True when `root` is a YAML mapping that itself declares a `version:` key, regardless of that key's type/value. */
 function declaresVersionKey(root) {
     return root !== null && typeof root === "object" && !Array.isArray(root) && own(root, "version");
@@ -126,14 +142,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) {
-            return {
-                ok: false,
-                path: resolvedPath,
-                sourceVersion: declaredVersion,
-                outcome: "blocked",
-                reason: `${reason} Run \`akm migrate apply --dry-run\`, review the plan, then run \`akm migrate apply\`.`,
-            };
+            return { ok: false, path: resolvedPath, sourceVersion: declaredVersion, outcome: "blocked", reason };
         }
         if (peekFailed) {
             return { ok: false, path: resolvedPath, outcome: "invalid", reason };
@@ -152,8 +165,11 @@ 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.
     const sourceVersion = declaredVersion ?? 4;
-    // The current document parsed; now run the two gates `compileTaskSources`
-    // applies before accepting it.
+    // 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.
     try {
         assertTaskScheduleInputsSatisfyContract(parsed.v4, resolvedPath);
         assertTaskScheduleCronValid(parsed.v4, backend);
@@ -163,12 +179,17 @@ 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: "valid",
+        outcome: sourceVersion === 2 || sourceVersion === 3 || convertedFromRetiredScheduleEnabled ? "converts" : "valid",
         resolved: buildResolved(id, parsed.v4),
     };
 }

package/dist/commands/workflow/plan.js

@@ -2,13 +2,11 @@
 // 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/.
 /**
- * `akm workflow plan <ref>` — compile + freeze WITHOUT publishing (P3b, spec
- * docs/plans/specs/p3b-child-executor.md §4.6). Zero durable writes, zero
- * usage/event rows (row B-48): this module calls exactly the same two
- * functions `startWorkflowRun` does to reach a frozen plan
- * (`loadWorkflowAsset`, `compileResolveFreezeWorkflowV4`) and NOTHING else —
- * never `publishWorkflowRunV4`, `startWorkflowRun`, `warn()`, `appendEvent`,
- * or `akmIndex`.
+ * `akm workflow plan <ref>` — compile + freeze WITHOUT publishing. Zero
+ * durable writes, zero usage/event rows: this module calls exactly the same
+ * two functions `startWorkflowRun` does to reach a frozen plan
+ * (`loadWorkflowAsset`, `freezeWorkflow`) and NOTHING else — never
+ * `publishWorkflowRunV4`, `startWorkflowRun`, `appendEvent`, or `akmIndex`.
  *
  * SECRET-FREE, by construction (§4.6's closed print list): a resolved
  * reference VALUE is never printed (references resolve at pre-attempt, not
@@ -20,9 +18,8 @@
  */
 import path from "node:path";
 import { loadConfig } from "../../core/config/config.js";
-import { lowerResolvedExecutionRequest } from "../../integrations/agent/execution-lowering.js";
-import { collectWorkflowWarnings } from "../../workflows/ir/compile.js";
-import { compileResolveFreezeWorkflowV4 } from "../../workflows/ir/freeze-v4.js";
+import { buildExecutionFromWire } from "../../integrations/agent/execution.js";
+import { freezeWorkflow } from "../../workflows/freeze/freeze.js";
 import { computePlanHash } from "../../workflows/ir/plan-hash.js";
 import { loadWorkflowAsset } from "../../workflows/runtime/workflow-asset-loader.js";
 /** The step's dispatch unit — the map template for a fan-out, else the root unit. Undefined for a route step. */
@@ -49,7 +46,7 @@ function childExportedOutputNames(frozenPlan) {
 }
 /**
  * A `child-workflow` target's `expansion`. Recurses into the embedded
- * plan's own steps in the identical shape (§4.6) — `sourceStepsById` is
+ * plan's own steps in the identical shape — `usesById` is
  * omitted for the recursive call because a nested child's own authored
  * source is not available here (only its already-frozen plan is), so a
  * task-wrapped step nested inside a child conservatively reports `via:
@@ -67,15 +64,15 @@ function childExpansion(target) {
     };
 }
 /** The task/child expansion boundary for one step (§4.6). */
-function stepExpansion(step, frozenTarget, sourceStepsById) {
+function stepExpansion(step, frozenTarget, usesById) {
     if (frozenTarget?.kind === "child-workflow")
         return childExpansion(frozenTarget);
-    const uses = sourceStepsById?.get(step.stepId)?.uses;
+    const uses = usesById?.get(step.stepId);
     if (uses?.startsWith("tasks/"))
         return { via: "task", taskRef: uses };
     return { via: "direct" };
 }
-function projectStep(step, sequenceIndex, sourceStepsById) {
+function projectStep(step, sequenceIndex, usesById) {
     const unit = stepUnit(step);
     const frozenTarget = unit?.frozenTarget;
     const kind = step.route ? "route" : step.root?.kind === "map" ? "map" : "unit";
@@ -95,7 +92,7 @@ function projectStep(step, sequenceIndex, sourceStepsById) {
             judgeEngine: step.gate.frozenJudge ? step.gate.frozenJudge.request.engine.name : null,
         },
         ...(step.outputSchema !== undefined ? { outputSchema: step.outputSchema } : {}),
-        expansion: stepExpansion(step, frozenTarget, sourceStepsById),
+        expansion: stepExpansion(step, frozenTarget, usesById),
     };
 }
 /**
@@ -103,30 +100,27 @@ function projectStep(step, sequenceIndex, sourceStepsById) {
  * from its own already-frozen `request` (the identical computation
  * `freeze/targets/command.ts`'s `commandResult` already performs at freeze
  * time and discards) — walked over the whole plan, including gate judges and
- * recursively into every embedded child plan. Read-only: `lowerResolvedExecutionRequest`
- * takes no config it could write through and dispatches nothing.
+ * recursively into every embedded child plan. Read-only: `buildExecutionFromWire`
+ * reads no config and dispatches nothing.
  */
 function collectLoweringNotices(plan, config) {
     const notices = [];
-    const lower = (request) => {
-        notices.push(...lowerResolvedExecutionRequest(request, config).notices);
+    const lower = (target) => {
+        notices.push(...buildExecutionFromWire(target).notices);
     };
     for (const step of plan.steps) {
         const unit = stepUnit(step);
         if (unit) {
             if (unit.frozenTarget.kind === "command")
-                lower(unit.frozenTarget.request);
+                lower(unit.frozenTarget);
             else if (unit.frozenTarget.kind === "child-workflow")
                 notices.push(...collectLoweringNotices(unit.frozenTarget.frozenPlan, config));
         }
         if (step.gate.frozenJudge)
-            lower(step.gate.frozenJudge.request);
+            lower(step.gate.frozenJudge);
     }
     return notices;
 }
-function relativeSourceReadSet(plan) {
-    return plan.sourceReadSet.map((snapshot) => snapshot.identity.file);
-}
 /**
  * Compile + freeze `ref` and project the frozen plan into the read-only
  * `akm workflow plan` envelope. Never publishes, never writes, never warns.
@@ -134,9 +128,9 @@ function relativeSourceReadSet(plan) {
 export async function akmWorkflowPlan(ref) {
     const asset = await loadWorkflowAsset(ref);
     const config = loadConfig();
-    const frozen = await compileResolveFreezeWorkflowV4(asset, config);
+    const frozen = await freezeWorkflow(asset, config);
     const plan = frozen.plan;
-    const sourceStepsById = new Map((asset.sourceIr.jobs[0]?.steps ?? []).map((step) => [step.id, step]));
+    const usesById = new Map(asset.plan.steps.map((step) => [step.stepId, step.spec?.uses]));
     const sourceFormat = path.extname(asset.path).toLowerCase() === ".md" ? "markdown" : "github-yaml";
     return {
         ok: true,
@@ -151,9 +145,8 @@ export async function akmWorkflowPlan(ref) {
         ...(plan.budget ? { budget: plan.budget } : {}),
         ...(plan.params ? { params: plan.params } : {}),
         ...(plan.outputs ? { outputs: plan.outputs } : {}),
-        steps: plan.steps.map((step, index) => projectStep(step, index, sourceStepsById)),
-        sourceReadSet: relativeSourceReadSet(plan),
+        steps: plan.steps.map((step, index) => projectStep(step, index, usesById)),
         notices: collectLoweringNotices(plan, config),
-        warnings: collectWorkflowWarnings(asset.sourceIr).map((warning) => warning.message),
+        warnings: frozen.warnings.map((warning) => warning.message),
     };
 }

package/dist/commands/workflow-cli.js

@@ -15,7 +15,7 @@ import { NotFoundError, TransientError, UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
-import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
+import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/resource-limits.js";
 import { abandonWorkflowRun, getWorkflowStatus, listWorkflowRuns, resolveWorkflowRunTarget, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
 import { akmWorkflowPlan } from "./workflow/plan.js";
 const workflowStatusCommand = defineJsonCommand({
@@ -174,8 +174,8 @@ const workflowCreateCommand = defineJsonCommand({
  * `--skip-if-locked` (#948) eligibility: only these two named, retryable
  * `TransientError` codes (#948 addendum — moved off UsageError, exit 75) turn
  * a `workflow run` failure into a graceful skip — `RUN_LEASE_HELD` (another
- * engine invocation is driving THIS run, `workflow-runs-repository.ts`'s
- * single-driver lease) and `STATE_DB_CONTENDED` (an unrelated akm process is
+ * live akm process holds THIS run's lock file, `exec/run-workflow.ts`) and
+ * `STATE_DB_CONTENDED` (an unrelated akm process is
  * writing state.db right now, `core/state-db.ts`'s BEGIN IMMEDIATE retry
  * exhaustion). Every other error — a bad flag, an unresolvable target —
  * still fails loudly.
@@ -202,7 +202,7 @@ const workflowRunCommand = defineJsonCommand({
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "If another akm process already holds this run's engine lease, or state.db is busy with another " +
+            description: "If another akm process is already driving this run, or state.db is busy with another " +
                 "writer, skip gracefully (exit 0) instead of failing (exit 75). Use for high-frequency scheduled runs " +
                 "so they don't pile up failures while a longer-running invocation is in progress.",
             default: false,

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

@@ -192,7 +192,6 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "cwd",
     "wikiRole",
     "sources",
-    "generation",
     "evidenceSources",
     // D2 (#730): the OKF v0.2 provenance `promoteProposal` stamps onto AKM-native
     // writes (generated/verified/sources, namespaced — see `types.ts`'s

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

@@ -54,8 +54,7 @@ import path from "node:path";
 import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
 import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { taskSourceErrorDetail } from "../../../tasks/source-v3.js";
-import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
-import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
+import { checkWorkflowPlan, compileWorkflowSource } from "../../../workflows/compile.js";
 import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
 import { isAkmRegistryCachePath, scanEnvKeyNames } from "../../common.js";
 /** Recommended `category` values for facts — `commands/lint/fact-linter.ts:9`. */
@@ -370,7 +369,7 @@ export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
             }
             return { errors, warnings };
         }
-        const compiled = compileWorkflowPlan(result.ir, path.basename(parsePath, path.extname(parsePath)));
+        const compiled = checkWorkflowPlan(result.plan);
         if (!compiled.ok) {
             for (const err of compiled.errors) {
                 errors.push({

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

@@ -56,8 +56,7 @@
  */
 import { scanEnvKeyNames } from "../../../commands/env/env.js";
 import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
-import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
-import { sourceStepInstructions } from "../../../workflows/source-ir/program.js";
+import { compileWorkflowSource, workflowStepInstructions } from "../../../workflows/compile.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { parseMarkdownToc } from "../../asset/markdown.js";
 import { nonEmptyString } from "./shared.js";
@@ -320,19 +319,19 @@ export function foldRecognizedMetadata(rendererName, file) {
                 const result = compileWorkflowSource(file.content(), { path: file.relPath, workspaceRoot: file.stashRoot });
                 if (!result.ok)
                     return out;
-                const sourceIr = result.ir;
+                const plan = result.plan;
                 const hints = new Set();
-                if (sourceIr.preamble)
-                    hints.add(sourceIr.preamble);
-                for (const step of sourceIr.jobs.flatMap((job) => job.steps)) {
-                    hints.add(step.id);
-                    hints.add(sourceStepInstructions(step));
-                    if (step.gate?.rubric)
-                        hints.add(step.gate.rubric);
+                if (plan.preamble)
+                    hints.add(plan.preamble);
+                for (const step of plan.steps) {
+                    hints.add(step.stepId);
+                    hints.add(workflowStepInstructions(step));
+                    if (step.gate.criteria[0])
+                        hints.add(step.gate.criteria[0]);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
-                if (sourceIr.params) {
-                    const parameters = Object.entries(sourceIr.params).map(([name, schema]) => {
+                if (plan.paramSchemas) {
+                    const parameters = Object.entries(plan.paramSchemas).map(([name, schema]) => {
                         const description = schema.description;
                         return { name, ...(typeof description === "string" && description ? { description } : {}) };
                     });

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

@@ -21,7 +21,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { looksLikeGithubWorkflowSource } from "../../../workflows/source-ir/compile.js";
+import { looksLikeGithubWorkflowSource } from "../../../workflows/compile.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { toPosix } from "../../common.js";
 import { perTypeValidateChecks, workflowYamlSourceDiagnostics } from "./akm-lint.js";

package/dist/core/adapter/execution-source.js

@@ -4,7 +4,7 @@
 import { createHash } from "node:crypto";
 import { isMap, isScalar, parseDocument, visit } from "yaml";
 import { cloneExecutionJson, cloneExecutionJsonObject, } from "../../execution/json.js";
-import { assertSnapshotKeys, snapshotStrictRecord } from "../../execution/record.js";
+import { snapshotStrictRecord } from "../../execution/record.js";
 import { cloneToolSelection, createAdapterRenderedExecutionSource, } from "../../execution/source.js";
 import { UsageError } from "../errors.js";
 import { warnOnce } from "../warn.js";
@@ -137,20 +137,16 @@ function nullableTimeout(value, path) {
 /** Adapter helper for the common frontmatter fields fixed by the 0.9.2 design. */
 export function executionDefaultsFromFrontmatter(data, options) {
     const frontmatter = snapshotStrictRecord(data, "frontmatter");
-    const optionRecord = snapshotStrictRecord(options, "execution frontmatter projection options");
-    assertSnapshotKeys(optionRecord, ["kind", "allowTopLevelEngine", "toolsKeys"], "execution frontmatter projection options");
-    const kind = optionRecord.kind;
+    const kind = options.kind;
     if (kind !== "command" && kind !== "persona") {
         throw new TypeError("execution frontmatter projection options.kind is invalid");
     }
-    const allowTopLevelEngine = Object.hasOwn(optionRecord, "allowTopLevelEngine")
-        ? optionRecord.allowTopLevelEngine
-        : false;
+    const allowTopLevelEngine = Object.hasOwn(options, "allowTopLevelEngine") ? options.allowTopLevelEngine : false;
     if (typeof allowTopLevelEngine !== "boolean") {
         throw new TypeError("execution frontmatter projection options.allowTopLevelEngine must be a boolean");
     }
-    const configuredToolsKeys = Object.hasOwn(optionRecord, "toolsKeys")
-        ? cloneExecutionJson(optionRecord.toolsKeys, "execution frontmatter projection options.toolsKeys")
+    const configuredToolsKeys = Object.hasOwn(options, "toolsKeys")
+        ? cloneExecutionJson(options.toolsKeys, "execution frontmatter projection options.toolsKeys")
         : ["tools"];
     if (!Array.isArray(configuredToolsKeys) || configuredToolsKeys.some((key) => typeof key !== "string" || !key)) {
         throw new TypeError("execution frontmatter projection options.toolsKeys must be an array of non-empty strings");
@@ -272,43 +268,35 @@ export function executionDefaultsFromFrontmatter(data, options) {
     }
     return out;
 }
-function snapshotRendererInput(input) {
-    const inputSnapshot = snapshotStrictRecord(input, "adapter execution source");
-    assertSnapshotKeys(inputSnapshot, ["kind", "raw", "identity", "defaults", "extensions"], "adapter execution source");
-    const identity = snapshotStrictRecord(inputSnapshot.identity, "adapter execution source identity");
-    assertSnapshotKeys(identity, ["ref", "bundle", "adapter", "file"], "adapter execution source identity");
-    return { input: inputSnapshot, identity };
-}
 export function renderMarkdownExecutionSource(input) {
-    const snapshots = snapshotRendererInput(input);
-    const raw = snapshots.input.raw;
+    const raw = input.raw;
     if (typeof raw !== "string")
         throw new TypeError("adapter execution source.raw must be a string");
-    const kind = snapshots.input.kind;
+    const kind = input.kind;
     if (kind !== "command" && kind !== "persona")
         throw new TypeError("adapter execution source.kind is invalid");
-    const identityFile = snapshots.identity.file;
-    const parsed = parseExecutionMarkdown(raw, typeof identityFile === "string" ? identityFile : undefined);
-    const hasDefaults = Object.hasOwn(snapshots.input, "defaults");
-    const defaultsProjection = snapshots.input.defaults;
+    const identity = input.identity;
+    const parsed = parseExecutionMarkdown(raw, identity.file);
+    const hasDefaults = Object.hasOwn(input, "defaults");
+    const defaultsProjection = input.defaults;
     const defaults = typeof defaultsProjection === "function" ? defaultsProjection(parsed.data) : defaultsProjection;
     if (hasDefaults && defaults === undefined) {
         throw new TypeError("adapter execution source defaults must be omitted or resolve to an object");
     }
-    const extensionsProjection = snapshots.input.extensions;
+    const extensionsProjection = input.extensions;
     const extensionsAreProjected = typeof extensionsProjection === "function";
     const extensions = extensionsAreProjected ? extensionsProjection(parsed.data) : extensionsProjection;
-    if (Object.hasOwn(snapshots.input, "extensions") && !extensionsAreProjected && extensions === undefined) {
+    if (Object.hasOwn(input, "extensions") && !extensionsAreProjected && extensions === undefined) {
         throw new TypeError("adapter execution source extensions must be omitted or be an adapter-owned extension object");
     }
     return createAdapterRenderedExecutionSource({
         kind,
         content: parsed.content,
         identity: {
-            ref: snapshots.identity.ref,
-            bundle: snapshots.identity.bundle,
-            adapter: snapshots.identity.adapter,
-            file: snapshots.identity.file,
+            ref: identity.ref,
+            bundle: identity.bundle,
+            adapter: identity.adapter,
+            file: identity.file,
             hash: createHash("sha256").update(raw, "utf8").digest("hex"),
         },
         ...(hasDefaults ? { defaults } : {}),

package/dist/core/asset/resolve-ref.js

@@ -89,7 +89,7 @@ function notFound(conceptId, triedForms, ctx) {
  *
  * Exported (Chunk-8 WI-8.5c) as the ONE conceptId derivation the improve
  * correlation sites (`eligibility.ts` candidate refs, `salience.ts`
- * last-use lookup, `collapse-detector.ts` canary mint/score) share with the
+ * last-use lookup) share with the
  * display rule — the permanent successor to the retired transient
  * `legacyConceptId`.
  */

package/dist/core/bundle-id.js

@@ -4,18 +4,55 @@
 import crypto from "node:crypto";
 import path from "node:path";
 import { isBundleSlug } from "./asset/asset-ref.js";
+import { UsageError } from "./errors.js";
 /** Deterministic, filesystem-safe bundle slug from a source path. */
 export function slugForPath(sourcePath) {
     const resolved = path.resolve(sourcePath);
-    const base = path
-        .basename(resolved)
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
+    const base = slugify(path.basename(resolved));
     if (base.length > 0)
         return base;
     return `bundle-${shortHash(resolved)}`;
 }
+/**
+ * Bundle slug from the package/repo name a registry install id names
+ * (`npm:@scope/pkg` → `pkg`, `github:owner/repo` → `repo`,
+ * `git:https://host/owner/repo` → `repo`); empty when it names none.
+ */
+export function slugForRegistryId(registryId) {
+    const locator = registryId.slice(registryId.indexOf(":") + 1);
+    return slugify(locator.split(/[/:]/).filter(Boolean).pop() ?? "");
+}
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Enforce the `--name` contract on every add path (D6): an explicit name is
+ * not a silent hint that may fall back to a derived id — it is a request
+ * that either succeeds exactly or fails loudly, before anything is written.
+ *
+ * `existingKeyForThisInstall` is the bundle key this exact source (path/URL/
+ * registry id) is already configured under, if any. Re-adding that same
+ * source under a *different* explicit name is rejected in favor of
+ * `akm bundle rename`, which is the one command allowed to change a bundle's
+ * key. A caller with no existing install for this source (the common case)
+ * omits it.
+ */
+export function validateExplicitBundleName(bundles, name, existingKeyForThisInstall) {
+    if (!isBundleSlug(name)) {
+        throw new UsageError(`"${name}" is not a legal bundle name: it must not contain whitespace or the characters ":" "." "#" "/".`, "INVALID_FLAG_VALUE");
+    }
+    if (existingKeyForThisInstall !== undefined && name !== existingKeyForThisInstall) {
+        throw new UsageError(`This source is already installed as bundle "${existingKeyForThisInstall}". Re-adding it under a ` +
+            `different name is not supported — run \`akm bundle rename ${existingKeyForThisInstall} ${name}\` instead.`, "INVALID_FLAG_VALUE");
+    }
+    if (Object.hasOwn(bundles, name) && name !== existingKeyForThisInstall) {
+        throw new UsageError(`Bundle name "${name}" already exists. Choose another name, or run ` +
+            `\`akm bundle rename ${name} <new-name>\` first.`, "INVALID_FLAG_VALUE");
+    }
+}
 /** Derive one batch-unique bundle id. */
 export function deriveBundleId(registryId, sourcePath, usedIds) {
     const preferred = registryId && registryId.length > 0 && isBundleSlug(registryId) ? registryId : slugForPath(sourcePath);