akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/tasks/validate.js

@@ -9,11 +9,13 @@
  * 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 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
@@ -41,16 +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.
- *   - `blocked`     — declared `version: 2` or `3`; runtime does not accept
- *                      it and the explicit migrator must rewrite it first.
+ *   - `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 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.
+ *                      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
@@ -62,7 +66,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 +130,12 @@ export async function akmTaskValidate(filePath) {
         if (!(cause instanceof UsageError))
             throw cause;
         const reason = cause.message;
-        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\`.`,
-            };
+        // 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) {
             return { ok: false, path: resolvedPath, outcome: "invalid", reason };
@@ -150,10 +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 current document parsed; now run the two gates `compileTaskSources`
-    // applies before accepting it.
+    // 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);

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,8 +192,9 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "cwd",
     "wikiRole",
     "sources",
-    "generation",
     "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-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

@@ -54,10 +54,10 @@
  * 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 } 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";
@@ -126,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)
@@ -246,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}`);
@@ -320,19 +342,25 @@ 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);
+                const uses = new Set();
+                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]);
+                    const used = workflowStepTarget(step.spec);
+                    if (used)
+                        uses.add(used);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
-                if (sourceIr.params) {
-                    const parameters = Object.entries(sourceIr.params).map(([name, schema]) => {
+                if (uses.size > 0)
+                    out.uses = [...uses];
+                if (plan.paramSchemas) {
+                    const parameters = Object.entries(plan.paramSchemas).map(([name, schema]) => {
                         const description = schema.description;
                         return { name, ...(typeof description === "string" && description ? { description } : {}) };
                     });
@@ -396,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));
+}

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/asset-placement.js

@@ -26,7 +26,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { toPosix } from "../common.js";
-import { DERIVED_SUFFIX, SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
+import { SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
 const workflowSpec = {
     isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
     toCanonicalName: (typeRoot, filePath) => {
@@ -245,21 +245,12 @@ export function assetPathForName(assetType, typeRoot, name) {
  * "default" alias is genuinely dual-owned: both `<dir>/.env` and
  * `<dir>/default.env` derive the same canonical name (`toCanonicalName`
  * above), so a physical-owner lookup must consider both without reading
- * either file. `memory` has a second, analogous duality (#882): a ref to
- * `<name>` may own either `<name>.md` or the LLM-inferred `<name>.derived.md`
- * twin — `.derived` is a provenance marker on the SAME identity, not part of
- * the name (see `resolveParentRef`/`isDerivedMemory` in
- * `commands/improve/memory/derived-ref.ts`, and the belief-edge identity
- * channel's own `memory:<name>.derived` refs). The plain `.md` file wins when
- * both exist, so it stays `primary` — first in the returned list — and every
- * caller here already prefers the first candidate that exists on disk. Every
- * other placement type has exactly one inverse spelling.
+ * either file. Every other placement type has exactly one inverse spelling —
+ * including `memory`: `<name>.derived.md` is a separate item that owns
+ * `<name>.derived`, never a second spelling of `<name>`.
  */
 export function assetPathCandidatesForName(assetType, typeRoot, name) {
     const primary = assetPathForName(assetType, typeRoot, name);
-    if (assetType === "memory" && !name.endsWith(DERIVED_SUFFIX)) {
-        return [primary, assetPathForName(assetType, typeRoot, `${name}${DERIVED_SUFFIX}`)];
-    }
     if (assetType !== "env")
         return [primary];
     const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;