akm-cli 0.9.3 → 0.9.5

package/dist/storage/repositories/proposals-repository.js

@@ -23,8 +23,24 @@ function changesToStored(changes) {
 /**
  * Reconstruct `Proposal.changes` from `metadata_json.changes` + the `content`
  * column.
+ *
+ * Read-time compatibility shim (#858/#859): proposals created before this
+ * field existed have no `changes` key in `metadata_json` at all (~89% of the
+ * archived accepted/rejected rows on real installs) and that history cannot
+ * be reconstructed from `content` alone. Treat a completely absent `changes`
+ * key as a known legacy gap — return an empty change list rather than
+ * throwing — so these rows still round-trip as real proposals (and count
+ * toward accepted/rejected totals) instead of being dropped or crashing
+ * every reader. A `changes` value that *is* present but malformed (wrong
+ * type, invalid entries) is still corruption and throws, same as before; the
+ * write path (`proposalToRowValues`) still refuses to persist an empty or
+ * missing change list for new proposals, so this leniency only ever applies
+ * to pre-existing rows.
  */
 function storedToChanges(stored, content) {
+    if (stored === undefined) {
+        return [];
+    }
     if (!Array.isArray(stored) || stored.length === 0) {
         throw new Error("Proposal metadata is missing changes.");
     }
@@ -69,7 +85,7 @@ function currentProposalRef(ref, requireQualified = false) {
 }
 function currentProposalTarget(value) {
     if (typeof value !== "object" || value === null)
-        throw new Error("Proposal metadata is missing proposedTarget.");
+        throw new Error("Proposal metadata has an invalid proposedTarget.");
     const target = value;
     if (typeof target.source !== "string" ||
         !isBundleSlug(target.source) ||
@@ -184,7 +200,13 @@ export function proposalRowToProposal(row) {
     }
     validatePresentMetadata(meta);
     const changes = storedToChanges(meta.changes, row.content);
-    const proposedTarget = currentProposalTarget(meta.proposedTarget);
+    // #859: absent proposedTarget (~93% of the real archive's accepted/rejected
+    // rows) is envelope metadata that predates this field, not corruption — an
+    // already-decided proposal is counted/displayed, never re-applied, so
+    // decode tolerates its absence the same way it already tolerates absent
+    // `changes`. A *present but malformed* value is still corruption and
+    // throws via currentProposalTarget, same as before.
+    const proposedTarget = meta.proposedTarget !== undefined ? currentProposalTarget(meta.proposedTarget) : undefined;
     return {
         id: row.id,
         ref: currentProposalRef(row.ref),
@@ -198,7 +220,7 @@ export function proposalRowToProposal(row) {
             ...(frontmatter !== undefined ? { frontmatter } : {}),
         },
         changes,
-        proposedTarget,
+        ...(proposedTarget !== undefined ? { proposedTarget } : {}),
         ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
         ...(meta.review !== undefined ? { review: meta.review } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
@@ -217,8 +239,27 @@ export function proposalRowToProposal(row) {
 export function proposalToRowValues(proposal, stashDir) {
     // Fields that have no dedicated column live in metadata_json.
     const metaObj = {};
-    if (!Array.isArray(proposal.changes) || proposal.changes.length === 0) {
-        throw new Error(`Proposal ${proposal.id} has no file changes.`);
+    // #859: `changes` and `proposedTarget` are only enforced as REQUIRED when
+    // minting/updating a `pending` proposal — the one status createProposal
+    // ever writes, and the one status every real accept/reject transition
+    // writes FROM (a pending row always carries the full envelope; see
+    // storedToChanges / currentProposalTarget doc comments). Writing a
+    // non-pending status (accepted/rejected/reverted) is always a status
+    // TRANSITION of an already-persisted proposal, spread-copied from the row
+    // this same repository just decoded — for a legacy archived row that
+    // never had `changes`/`proposedTarget` to begin with (the pre-envelope
+    // shape), re-persisting it unchanged (e.g. `proposal revert` on an old
+    // accepted row) must not be blocked by a requirement the row never met.
+    // This does NOT weaken validation of a genuinely new proposal: every
+    // pending-status write still requires the full envelope, exactly as
+    // before.
+    if (proposal.status === "pending") {
+        if (!Array.isArray(proposal.changes) || proposal.changes.length === 0) {
+            throw new Error(`Proposal ${proposal.id} has no file changes.`);
+        }
+        if (proposal.proposedTarget === undefined) {
+            throw new Error(`Proposal ${proposal.id} is missing proposedTarget.`);
+        }
     }
     if (proposal.changes.some((change) => typeof change.path !== "string" ||
         change.path.length === 0 ||
@@ -227,7 +268,8 @@ export function proposalToRowValues(proposal, stashDir) {
         throw new Error(`Proposal ${proposal.id} has invalid file changes.`);
     }
     metaObj.changes = changesToStored(proposal.changes);
-    metaObj.proposedTarget = currentProposalTarget(proposal.proposedTarget);
+    if (proposal.proposedTarget !== undefined)
+        metaObj.proposedTarget = currentProposalTarget(proposal.proposedTarget);
     if (proposal.beforeHash !== undefined)
         metaObj.beforeHash = proposal.beforeHash;
     if (proposal.sourceRun !== undefined)
@@ -307,7 +349,23 @@ export function listStateProposals(db, options = {}) {
               content, frontmatter_json, metadata_json
        FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
         .all(...params);
-    return rows.map(proposalRowToProposal);
+    // Per-row skip-and-warn (#858/#859): a single row that fails to parse
+    // (invalid ref/status/metadata shape — genuine corruption, distinct from
+    // the tolerated legacy-missing-`changes` case in `storedToChanges` above)
+    // must not abort the entire list. Every caller of this function reads a
+    // multi-row archive; one bad row hiding the rest behind a thrown error is
+    // strictly worse than surfacing the well-formed rows plus a warning.
+    const proposals = [];
+    for (const row of rows) {
+        try {
+            proposals.push(proposalRowToProposal(row));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[akm] Skipping unparseable proposal row (id=${row.id}, ref=${row.ref}): ${message}`);
+        }
+    }
+    return proposals;
 }
 /**
  * Look up a single proposal by id, optionally scoped to one stash root.

package/dist/storage/repositories/task-history-repository.js

@@ -24,7 +24,23 @@ function validateDetail(value) {
         metadataError("detail.exitCode must be a number or null");
     }
 }
-/** Decode the current task-history metadata shape. */
+/**
+ * Decode the task-history metadata shape.
+ *
+ * Read-time compatibility shim (mirrors proposals-repository's
+ * `storedToChanges`): `metadataVersion` was added in a later release. 58% of
+ * a real install's `task_history` rows (8,596/14,801) predate the field
+ * entirely, and 88 more carry additive fields (`profile`, `repairReason`)
+ * written by prior releases. An absent `metadataVersion` is a LEGACY row, not
+ * corruption — decode what's present (defaulting the absent `detail` key to
+ * `null`) instead of throwing. Unknown keys are ignored rather than
+ * hard-rejected, so the next additive field never regresses this again;
+ * neither `profile` nor `repairReason` is read anywhere downstream, so they
+ * are dropped harmlessly rather than round-tripped. A `metadataVersion` that
+ * IS present but not `2` is a genuinely unknown/future shape and still
+ * rejected, as is a non-number `durationMs` or a `detail` that fails
+ * {@link validateDetail} — real corruption, not version skew.
+ */
 export function decodeTaskHistoryMetadata(input) {
     let parsed = input;
     if (typeof input === "string") {
@@ -37,27 +53,23 @@ export function decodeTaskHistoryMetadata(input) {
     }
     if (!isRecord(parsed))
         metadataError("root must be an object");
-    if (parsed.metadataVersion !== 2)
+    if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 2) {
         metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
-    const allowed = new Set(["metadataVersion", "durationMs", "detail", "engine", "targetVocab"]);
-    const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
-    if (unknown.length > 0)
-        metadataError(`unknown fields: ${unknown.sort().join(", ")}`);
+    }
     if (typeof parsed.durationMs !== "number")
         metadataError("durationMs must be a number");
-    if (!("detail" in parsed))
-        metadataError("detail is required");
+    const detail = "detail" in parsed ? parsed.detail : null;
     if (parsed.engine !== undefined && parsed.engine !== null && typeof parsed.engine !== "string") {
         metadataError("engine must be a string or null");
     }
     if (parsed.targetVocab !== undefined && parsed.targetVocab !== 2) {
         metadataError("targetVocab must be 2 when present");
     }
-    validateDetail(parsed.detail);
+    validateDetail(detail);
     return {
         metadataVersion: 2,
         durationMs: parsed.durationMs,
-        detail: parsed.detail ?? null,
+        detail: detail ?? null,
         ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
         ...(parsed.targetVocab === 2 ? { targetVocab: 2 } : {}),
     };

package/dist/tasks/run/task-history.js

@@ -79,14 +79,34 @@ export function readTaskHistory(options = {}) {
             // discarded and `akm task history --id X --limit 20` always returned one
             // run. The CLI documents --limit as "Maximum rows to return"; honour it.
             if (options.limit !== undefined && options.limit > 0) {
-                return getTaskHistoryRuns(db, options.id, options.limit).map(taskHistoryRowToResult);
+                return decodeTaskHistoryRows(getTaskHistoryRuns(db, options.id, options.limit));
             }
             const row = getTaskHistory(db, options.id);
-            return row ? [taskHistoryRowToResult(row)] : [];
+            return row ? decodeTaskHistoryRows([row]) : [];
         }
-        return queryTaskHistory(db, options.limit !== undefined && options.limit > 0 ? { limit: options.limit } : {}).map(taskHistoryRowToResult);
+        return decodeTaskHistoryRows(queryTaskHistory(db, options.limit !== undefined && options.limit > 0 ? { limit: options.limit } : {}));
     });
 }
+/**
+ * Per-row skip-and-warn (mirrors `listStateProposals` in
+ * proposals-repository.ts): a single genuinely-corrupt `metadata_json` row
+ * must not abort the entire history read. `decodeTaskHistoryMetadata` (via
+ * `taskHistoryRowToResult`) already tolerates legacy/additive shapes; only
+ * real corruption reaches this catch.
+ */
+function decodeTaskHistoryRows(rows) {
+    const results = [];
+    for (const row of rows) {
+        try {
+            results.push(taskHistoryRowToResult(row));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[akm] Skipping unparseable task_history row (task_id=${row.task_id}, started_at=${row.started_at}): ${message}`);
+        }
+    }
+    return results;
+}
 /**
  * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape
  * that callers of `readTaskHistory()` expect.

package/dist/tasks/scheduler-binding.js

@@ -159,12 +159,15 @@ export function schedulerLogicalBindingOwner(nativeId, invocation) {
     return schedulerNativeArtifactOwner(nativeId, invocation)?.logicalId;
 }
 export function schedulerNativeArtifactOwner(nativeId, invocation) {
-    if (invocation[0] === "workflow" && invocation[1] === "run") {
-        return { logicalId: nativeId, logicalKind: "workflow" };
+    if (invocation[0] === "workflow" && invocation[1] === "run" && invocation.length === 3) {
+        const ref = invocation[2];
+        if (ref && workflowRefDigestsToNativeId(ref, nativeId)) {
+            return { logicalId: nativeId, logicalKind: "workflow" };
+        }
+        return undefined;
     }
     const taskId = invocation[0] === "task" && invocation[1] === "run" ? invocation[2] : undefined;
-    const bundleIndex = invocation.indexOf("--bundle", 3);
-    if (!taskId || bundleIndex === -1 || !invocation[bundleIndex + 1])
+    if (!taskId)
         return undefined;
     return {
         logicalId: schedulerNativeBindingId(taskId) === nativeId ? taskId : nativeId,
@@ -225,7 +228,6 @@ export function assertSchedulerMutationArtifact(artifact, expected) {
         artifact.nativeId === expected.nativeId &&
         artifact.bindingId === expected.bindingId &&
         artifact.invocation !== undefined &&
-        sameInvocation(artifact.invocation, expected.invocation) &&
         expected.fingerprint !== undefined &&
         artifact.fingerprint === expected.fingerprint) {
         return;
@@ -306,6 +308,14 @@ export function schedulerBindingOrdinal(bindingId, logicalSource, invocation) {
     }
     return undefined;
 }
+/** Whether some schedule ordinal on `ref` would digest to `nativeId` (mirrors schedulerBindingOrdinal). */
+function workflowRefDigestsToNativeId(ref, nativeId) {
+    for (let ordinal = 0; ordinal < 4096; ordinal += 1) {
+        if (digestBindingId("workflow", ref, ordinal) === nativeId)
+            return true;
+    }
+    return false;
+}
 function digestBindingId(kind, ref, ordinal) {
     const prefix = kind === "workflow" ? "wf" : "task";
     const digest = createHash("sha256")

package/dist/tasks/scheduler-sync-preview.js

@@ -0,0 +1,45 @@
+// 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/.
+/**
+ * Project a set of scheduler sync operations into a preview report. Pure:
+ * no I/O, no backend calls. Accepts a bare operation array (not the whole
+ * `SchedulerSyncPlan`) so a future `task prune` can build a preview from
+ * its own remove-only operation set without needing a full sync plan.
+ */
+export function renderSchedulerPlanPreview(backend, operations, unchanged = [], failures = []) {
+    const adds = [];
+    const updates = [];
+    const removes = [];
+    for (const operation of operations) {
+        if (operation.kind === "remove") {
+            removes.push({
+                id: operation.id,
+                kind: "remove",
+                nativeId: operation.nativeId,
+                ...(operation.ownerBundlePath !== undefined ? { ownerBundlePath: operation.ownerBundlePath } : {}),
+                ...(operation.reason !== undefined ? { reason: operation.reason } : {}),
+            });
+        }
+        else if (operation.kind === "install") {
+            adds.push({ id: operation.binding.id, kind: "install" });
+        }
+        else {
+            updates.push({ id: operation.binding.id, kind: "update" });
+        }
+    }
+    return Object.freeze({
+        backend,
+        dryRun: true,
+        adds: Object.freeze(adds),
+        updates: Object.freeze(updates),
+        removes: Object.freeze(removes),
+        unchanged: Object.freeze([...unchanged]),
+        hasRemovals: removes.length > 0,
+        failures: Object.freeze([...failures]),
+    });
+}
+/** Convenience wrapper for the common case: previewing a whole {@link SchedulerSyncPlan}. */
+export function renderSchedulerSyncPlanPreview(backend, plan) {
+    return renderSchedulerPlanPreview(backend, plan.operations, plan.unchanged, plan.failures);
+}

package/dist/tasks/scheduler-sync.js

@@ -17,7 +17,7 @@ import { WorkflowSourceCollisionError, WorkflowSourceNameError, WorkflowSourceRe
 import { compileWorkflowSource } from "../workflows/source-ir/compile.js";
 import { prepareTaskV3Execution } from "./prepare/prepare.js";
 import { parseSchedule } from "./schedule.js";
-import { assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "./scheduler-binding.js";
+import { assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeArtifactOwner, schedulerNativeBindingId, } from "./scheduler-binding.js";
 import { parseTaskSource } from "./source/parse-task-source.js";
 import { projectTaskSourceV4 } from "./source/project-v4.js";
 import { taskSourceErrorDetail } from "./source-v3.js";
@@ -47,6 +47,7 @@ export async function prepareSchedulerSyncSourceSet(input) {
         desired: compiled.desired,
         sourceSnapshot,
         executableWorkflows: compiled.executableWorkflows,
+        failures: compiled.failures,
     });
 }
 export function finalizeSchedulerSyncPlan(input, prepared) {
@@ -108,34 +109,7 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
         .sort(compareCodePoints);
     for (const id of removed) {
         const current = present.get(id);
-        if (!current?.invocation) {
-            throw nativeArtifactCollision({ nativeId: current?.nativeId ?? schedulerNativeBindingId(id), bindingId: id }, { nativeId: current?.nativeId ?? schedulerNativeBindingId(id) });
-        }
-        const nativeId = exactInstalledNativeId(id, current, inspection.artifacts);
-        const artifact = inspection.artifacts.find((candidate) => candidate.nativeId === nativeId && candidate.bindingId === id);
-        const priorFingerprint = current.signature ?? artifact?.fingerprint;
-        if (!artifact || priorFingerprint === undefined) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} has no exact native fingerprint; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        const logicalSource = installedLogicalSource(current.invocation, coherentInput);
-        const ordinal = schedulerBindingOrdinal(id, logicalSource, current.invocation);
-        if (ordinal === undefined) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} cannot be attributed to an exact schedule ordinal; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        operations.push(Object.freeze({
-            kind: "remove",
-            id,
-            nativeId,
-            expected: freezeRemovalExpectation({
-                state: "present",
-                bindingId: id,
-                nativeId,
-                logicalSource,
-                ordinal,
-                invocation: current.invocation,
-                fingerprint: priorFingerprint,
-            }),
-        }));
+        operations.push(buildSchedulerRemoveOperation(id, current, inspection.artifacts, coherentInput));
     }
     return Object.freeze({
         desired,
@@ -145,6 +119,49 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
         unchanged: Object.freeze(unchanged),
         operations: Object.freeze(operations),
         sourceSnapshot: prepared.sourceSnapshot,
+        failures: prepared.failures,
+    });
+}
+/**
+ * Build the exact removal operation for one installed binding: same
+ * exact-native-fingerprint / ordinal-attribution safety checks
+ * `finalizeSchedulerSyncPlan`'s remove loop always applied, factored out so
+ * `akm task prune` (#851) can build removal operations for entries
+ * `belongsToBundle` structurally can't see (unresolvable ownership) without
+ * re-deriving — or weakening — this logic. Throws the same `UsageError`s a
+ * sync removal would on an inexact match; callers computing prune candidates
+ * should only pass entries they've already independently confirmed are safe
+ * to remove.
+ */
+export function buildSchedulerRemoveOperation(id, current, artifacts, input) {
+    if (!current?.invocation) {
+        throw nativeArtifactCollision({ nativeId: current?.nativeId ?? schedulerNativeBindingId(id), bindingId: id }, { nativeId: current?.nativeId ?? schedulerNativeBindingId(id) });
+    }
+    const nativeId = exactInstalledNativeId(id, current, artifacts);
+    const artifact = artifacts.find((candidate) => candidate.nativeId === nativeId && candidate.bindingId === id);
+    const priorFingerprint = current.signature ?? artifact?.fingerprint;
+    if (!artifact || priorFingerprint === undefined) {
+        throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} has no exact native fingerprint; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    const logicalSource = installedLogicalSource(current.invocation, input);
+    const ordinal = schedulerBindingOrdinal(id, logicalSource, current.invocation);
+    if (ordinal === undefined) {
+        throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} cannot be attributed to an exact schedule ordinal; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    return Object.freeze({
+        kind: "remove",
+        id,
+        nativeId,
+        expected: freezeRemovalExpectation({
+            state: "present",
+            bindingId: id,
+            nativeId,
+            logicalSource,
+            ordinal,
+            invocation: current.invocation,
+            fingerprint: priorFingerprint,
+        }),
+        ...(current.ownerBundlePath !== undefined ? { ownerBundlePath: current.ownerBundlePath } : {}),
     });
 }
 function exactInstalledNativeId(logicalId, current, artifacts) {
@@ -189,10 +206,17 @@ export function assertSchedulerNativeArtifactOwnership(desired, installed) {
         const wanted = desiredByKey.get(key);
         if (!wanted)
             continue;
-        if (artifact.nativeId !== schedulerBindingNativeId(wanted) ||
-            artifact.bindingId !== wanted.id ||
-            artifact.invocation === undefined ||
-            !sameInvocation(artifact.invocation, wanted.invocation)) {
+        // Re-derive ownership from the artifact's own invocation content (not the
+        // caller-supplied `bindingId` label) so a proven owner whose invocation
+        // no longer matches the desired shape is an UPDATE, not a refusal — that
+        // reconciliation happens below in finalizeSchedulerSyncPlan. An artifact
+        // whose invocation content does not actually prove it belongs to
+        // `wanted` (unproven, malformed, or a different logical owner) is still
+        // a genuine collision.
+        const provenBindingId = artifact.invocation !== undefined
+            ? schedulerNativeArtifactOwner(artifact.nativeId, artifact.invocation)?.logicalId
+            : undefined;
+        if (artifact.nativeId !== schedulerBindingNativeId(wanted) || provenBindingId !== wanted.id) {
             throw nativeArtifactCollision(desiredArtifact(wanted), artifact);
         }
     }
@@ -251,12 +275,17 @@ async function compileDesiredSourceSet(input, collector) {
     const failures = [];
     await compileTaskSources(input, collector, bindings, failures);
     await compileWorkflowSources(input, collector, bindings, executableWorkflows, failures);
-    if (failures.length > 0) {
-        throw new UsageError(`Scheduler sync rejected the desired source set before mutation:\n${failures.map((failure) => `- ${failure}`).join("\n")}`, "TASK_SOURCE_INVALID");
-    }
+    // Degrade, don't reject (#867): one source that fails to parse/prepare no
+    // longer poisons the whole desired set — it is dropped from `desired` and
+    // reported here instead, so every OTHER task/workflow still reconciles.
+    // Genuinely cross-cutting integrity violations (duplicate ids, native
+    // artifact ownership conflicts, an incoherent backend inspection) are
+    // asserted separately in `finalizeSchedulerSyncPlan` and still hard-fail
+    // the whole sync — this only relaxes the per-source parse/prepare gate.
     return Object.freeze({
         desired: Object.freeze(bindings),
         executableWorkflows: Object.freeze(executableWorkflows.sort((left, right) => compareCodePoints(left.ref, right.ref))),
+        failures: Object.freeze(failures.sort((left, right) => compareCodePoints(left.path, right.path))),
     });
 }
 async function compileTaskSources(input, collector, out, failures) {
@@ -268,6 +297,7 @@ async function compileTaskSources(input, collector, out, failures) {
         const relative = guarded.relativePath;
         const conceptId = relative.slice(0, -4);
         const id = input.adapterId === "akm-task" ? conceptId : path.basename(sourcePath, ".yml");
+        const qualifiedRefForFailure = makeBundleRef(input.bundleName, conceptId);
         try {
             const physicalIdentity = guarded.physicalIdentity;
             const priorOwner = physicalOwners.get(physicalIdentity);
@@ -355,7 +385,7 @@ async function compileTaskSources(input, collector, out, failures) {
             }
         }
         catch (cause) {
-            failures.push(taskFailure(sourcePath, cause));
+            failures.push(taskFailure(sourcePath, qualifiedRefForFailure, cause));
         }
     }
 }
@@ -364,6 +394,8 @@ async function compileWorkflowSources(input, collector, out, evidence, failures)
         return;
     const lookups = enumerateWorkflowLookups(input, collector, failures);
     for (const [canonicalName, sources] of lookups) {
+        const failurePath = sources[0]?.sourcePath ?? canonicalName;
+        const failureRef = makeBundleRef(input.bundleName, input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName);
         try {
             if (sources.length > 1) {
                 throw new WorkflowSourceCollisionError(input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));
@@ -426,7 +458,7 @@ async function compileWorkflowSources(input, collector, out, evidence, failures)
             }
         }
         catch (cause) {
-            failures.push(errorMessage(cause));
+            failures.push(workflowFailure(failurePath, failureRef, cause));
         }
     }
 }
@@ -455,7 +487,7 @@ function enumerateWorkflowLookups(input, collector, failures) {
         const stem = authoredName.slice(0, -extension.length).toLowerCase();
         const nestedSuffix = WORKFLOW_EXTENSIONS.find((suffix) => stem.endsWith(suffix));
         if (nestedSuffix) {
-            failures.push(errorMessage(new WorkflowSourceNameError(guarded.relativePath, nestedSuffix)));
+            failures.push(workflowFailure(sourcePath, undefined, new WorkflowSourceNameError(guarded.relativePath, nestedSuffix)));
             continue;
         }
         const canonicalName = canonicalizeWorkflowName(authoredName);
@@ -528,9 +560,13 @@ function assertUniqueInstalledIds(installed) {
         seen.add(binding.id);
     }
 }
-function taskFailure(file, cause) {
+function taskFailure(file, ref, cause) {
     const detail = taskSourceErrorDetail(cause);
-    return detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
+    const reason = detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
+    return Object.freeze({ path: file, ref, reason });
+}
+function workflowFailure(file, ref, cause) {
+    return Object.freeze({ path: file, ...(ref ? { ref } : {}), reason: errorMessage(cause) });
 }
 function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);

package/dist/tasks/source/bounded-document.js

@@ -392,7 +392,7 @@ export function assertBoundedTaskYamlDocument(document, options) {
  * P4 (docs/plans/specs/p4-deletions-closeout.md §3.2) deleted task v3
  * acceptance from `src` entirely — `parseTaskV3Yaml` and its `"task v3
  * source"` label no longer exist here (the grammar survives only in the
- * vendored, frozen `scripts/akm-migrate/migrate/task-source-v3-frozen.ts`
+ * vendored, frozen `src/tasks/source/task-source-v3-frozen.ts`
  * copy, which does not call this function). The two live `src` callers
  * today: `parseTaskSourceV4`'s standalone YAML-string entry
  * (`task-source-v4.ts:790`) passes `sourceLabel: "task source v4"`; the

package/dist/tasks/source/parse-task-source.js

@@ -7,14 +7,17 @@
  *
  * Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
  * `root.version`, and either dispatches into `parseTaskSourceV4Document` or
- * fails closed — no second parse, no re-serialization, no synthetic document
- * (the P1b §4.3 invariant this phase carries forward).
+ * routes through the in-memory read shim below — no second parse of the v4
+ * grammar itself, no re-serialization back to disk, no synthetic document
+ * (the P1b §4.3 invariant this phase carries forward: the shim adds a pure
+ * bytes-in/bytes-out detour, never a disk write).
  *
  * The terminal routing table:
  *
  *   | root `version`        | outcome                                                        |
  *   |------------------------|-----------------------------------------------------------------|
  *   | `4`                    | `parseTaskSourceV4Document` — the new grammar (row B-13)        |
+ *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) — the shim removes friction for the deterministic case, it never hides a real problem |
  *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) |
  *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
  *
@@ -24,17 +27,28 @@
  * message that would send the user to the migrator for a document that was
  * never task v2 or v3 in the first place.
  *
- * task v2 and task v3 sources are no longer read by `src` at all — the only
- * surviving reader is the frozen, vendored copy in
- * `scripts/akm-migrate/migrate/task-source-v3-frozen.ts`, reachable only
- * through `akm migrate apply` / `akm-migrate`. The front end's own
- * pre-version failures (source not a string, source too large, YAML
- * parse/warning/expansion) render with the label `task source` (row B-17,
- * closing the "task v3 source" label wart P2a's §3.4 recorded).
+ * task v2 and task v3 sources are no longer read as their own standing
+ * grammar anywhere else in `src` — the only readers of that grammar are the
+ * pure, byte-producing planners (`./task-to-v3.ts`, `./task-to-v4.ts`, and
+ * the frozen v3 reader `./task-source-v3-frozen.ts`), reached either through
+ * this shim (bytes in, bytes out, never touches disk) or through
+ * `akm migrate apply` / `akm-migrate` (`scripts/akm-migrate`, which
+ * additionally rewrites the file on disk once the user asks for that).
+ * Policy: a deterministic byte transform is the tool's job, not the user's —
+ * upgrading past a schema bump must not silently break a scheduled task, so
+ * v2/v3 files keep reading successfully at the cost of a one-line
+ * deprecation warning, and `akm migrate apply` remains available to rewrite
+ * the file and silence it. The front end's own pre-version failures (source
+ * not a string, source too large, YAML parse/warning/expansion) render with
+ * the label `task source` (row B-17, closing the "task v3 source" label
+ * wart P2a's §3.4 recorded).
  */
 import { UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
 import { readBoundedTaskSourceYaml } from "./bounded-document.js";
-import { parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION } from "./task-source-v4.js";
+import { parseTaskSourceV4, parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION, } from "./task-source-v4.js";
+import { planTaskToV3File } from "./task-to-v3.js";
+import { planTaskToV4File } from "./task-to-v4.js";
 /** Read the root `version` field without over-accepting non-number values (e.g. the string `"4"`). */
 export function peekTaskSourceVersion(root) {
     if (root === null || typeof root !== "object" || Array.isArray(root))
@@ -43,12 +57,64 @@ export function peekTaskSourceVersion(root) {
     return typeof value === "number" ? value : undefined;
 }
 const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+function unsupportedVersionError(filePath, version) {
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
+}
+/**
+ * Plan the SAME bytes already in hand through the pure v3->v4 (and, for v2,
+ * chained v2->v3->v4) migration planner(s) — never touches disk, never
+ * writes the file, never re-reads it from disk. Returns the produced v4
+ * YAML text, or `undefined` when the deterministic conversion cannot
+ * proceed (an unmigratable v2/v3 shape) — the caller falls back to the same
+ * hard error this gate threw before the shim existed.
+ */
+function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
+    const bytes = Buffer.from(yaml, "utf8");
+    // `writable`/`onDiskWritable` gate the DISK apply path's "don't touch a
+    // read-only file" check inside the planners; this shim never writes
+    // anything to disk, so that check does not apply here and must not block
+    // an otherwise-legal read of a task file that happens to be read-only.
+    const baseInput = {
+        filePath,
+        bytes,
+        mode: 0o644,
+        writable: true,
+        onDiskWritable: true,
+        ...(workspaceRoot ? { containmentRoot: workspaceRoot } : {}),
+    };
+    let v3Bytes;
+    if (version === 3) {
+        v3Bytes = bytes;
+    }
+    else {
+        const v3Outcome = planTaskToV3File(baseInput);
+        if (v3Outcome.status !== "changed")
+            return undefined;
+        v3Bytes = v3Outcome.after;
+    }
+    const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
+    if (v4Outcome.status !== "changed")
+        return undefined;
+    return v4Outcome.after.toString("utf8");
+}
 /** Parse task source YAML, routing per the terminal table above. */
 export function parseTaskSource(input) {
     const { root, lineAt } = readBoundedTaskSourceYaml(input, { sourceLabel: "task source" });
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
-        throw new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${input.filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
+        if (version === 2 || version === 3) {
+            const v4Yaml = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+            if (v4Yaml !== undefined) {
+                const v4 = parseTaskSourceV4({
+                    yaml: v4Yaml,
+                    filePath: input.filePath,
+                    ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
+                });
+                warn(`akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
+                return Object.freeze({ version: 4, v4 });
+            }
+        }
+        throw unsupportedVersionError(input.filePath, version);
     }
     const documentOptions = {
         filePath: input.filePath,