@unbrained/pm-cli 2026.7.15 → 2026.7.17

package/dist/cli/commands/update-many.js

@@ -4,7 +4,7 @@
  * Implements the pm update many command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="66fd8f1d-25f8-55fc-85ea-ea3000479f01")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="19acba6b-a459-52ce-b267-6f1d0db63265")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../../core/checkpoint/mutation-checkpoint.js";
 import { toItemRecord } from "../../core/item/item-record.js";
@@ -25,7 +25,7 @@ import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { resolveAuthor } from "../../core/shared/author.js";
 import { hasListFilters } from "./list-filter-shared.js";
-import { runList } from "./list.js";
+import { runList, } from "./list.js";
 import { runRestore } from "./restore.js";
 import { runUpdate } from "./update.js";
 const UPDATE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
@@ -213,7 +213,8 @@ const UNSET_FIELD_ALIASES = {
     "type-options": "type_options",
     tags: "tags",
 };
-function sanitizeUpdateOptionsForSummary(options) {
+/** Removes execution-only options from the mutation summary persisted in checkpoints. */
+const sanitizeUpdateOptionsForSummary = (options) => {
     const summary = {};
     for (const [key, value] of Object.entries(options)) {
         if (NON_MUTATION_UPDATE_OPTION_KEYS.has(key)) {
@@ -225,46 +226,61 @@ function sanitizeUpdateOptionsForSummary(options) {
         summary[key] = value;
     }
     return summary;
-}
-function hasAnyUpdateMutationInput(options) {
+};
+/** Reports whether an update-many request contains at least one mutation input. */
+const hasAnyUpdateMutationInput = (options) => {
     return Object.keys(sanitizeUpdateOptionsForSummary(options)).length > 0;
-}
-function toComparablePreviewValue(optionKey, value) {
+};
+/** Trims string preview values while preserving non-string inputs. */
+const trimPreviewValue = (value) => typeof value === "string" ? value.trim() : value;
+/** Converts integer-like preview values to their storage representation. */
+const normalizeIntegerPreviewValue = (value) => {
+    const trimmed = String(value).trim();
+    const parsed = Number(trimmed);
+    return Number.isInteger(parsed) ? parsed : trimmed;
+};
+/** Converts finite numeric preview values to their storage representation. */
+const normalizeNumericPreviewValue = (value) => {
+    const trimmed = String(value).trim();
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : trimmed;
+};
+/** Converts supported regression tokens to their boolean storage representation. */
+const normalizeRegressionPreviewValue = (value) => {
+    const normalized = String(value).trim().toLowerCase();
+    const parsed = new Map([
+        ["true", true],
+        ["1", true],
+        ["false", false],
+        ["0", false],
+    ]).get(normalized);
+    return parsed ?? trimPreviewValue(value);
+};
+const PREVIEW_VALUE_NORMALIZERS = {
+    priority: normalizeIntegerPreviewValue,
+    estimatedMinutes: normalizeNumericPreviewValue,
+    order: normalizeNumericPreviewValue,
+    rank: normalizeNumericPreviewValue,
+    regression: normalizeRegressionPreviewValue,
+};
+/** Normalizes a CLI mutation value to the storage-shaped value used by previews. */
+const toComparablePreviewValue = (optionKey, value) => {
     if (value === undefined) {
         return undefined;
     }
-    if (optionKey === "priority") {
-        const parsed = Number(String(value).trim());
-        return Number.isInteger(parsed) ? parsed : String(value).trim();
-    }
-    if (optionKey === "estimatedMinutes" ||
-        optionKey === "order" ||
-        optionKey === "rank") {
-        const parsed = Number(String(value).trim());
-        return Number.isFinite(parsed) ? parsed : String(value).trim();
-    }
-    if (optionKey === "regression") {
-        const normalized = String(value).trim().toLowerCase();
-        if (normalized === "true" || normalized === "1") {
-            return true;
-        }
-        if (normalized === "false" || normalized === "0") {
-            return false;
-        }
-    }
-    if (typeof value === "string") {
-        return value.trim();
-    }
-    return value;
-}
-function normalizeUnsetField(rawField) {
+    return (PREVIEW_VALUE_NORMALIZERS[optionKey] ?? trimPreviewValue)(value);
+};
+/** Resolves user-facing unset aliases to stored metadata keys. */
+const normalizeUnsetField = (rawField) => {
     const normalized = rawField.trim().toLowerCase().replaceAll("-", "_");
     return UNSET_FIELD_ALIASES[normalized] ?? normalized;
-}
-function areValuesEqual(left, right) {
+};
+/** Compares preview values using the canonical stable serialization contract. */
+const areValuesEqual = (left, right) => {
     return stableValueEquals(left, right);
-}
-function normalizeCollectionBeforeValue(field, value) {
+};
+/** Supplies the storage-shaped empty value for an absent collection field. */
+const normalizeCollectionBeforeValue = (field, value) => {
     if (value !== undefined) {
         return value;
     }
@@ -272,8 +288,9 @@ function normalizeCollectionBeforeValue(field, value) {
         return {};
     }
     return [];
-}
-function collectionValueCount(field, value) {
+};
+/** Counts entries in list and type-option collection values. */
+const collectionValueCount = (field, value) => {
     if (Array.isArray(value)) {
         return value.length;
     }
@@ -281,67 +298,83 @@ function collectionValueCount(field, value) {
         return Object.keys(value).length;
     }
     return 0;
-}
-function buildCollectionMutationPlans(row, update) {
+};
+/** Resolves the dominant collection mutation using apply-path precedence. */
+const resolveCollectionMutationOperation = (params) => {
+    if (params.replace) {
+        return "replace";
+    }
+    if (params.clear) {
+        return "clear_or_reset";
+    }
+    return params.removeCount > 0 ? "merge_remove" : "append";
+};
+/** Reads an optional definition key without indexing through undefined. */
+const readOptionalUpdateValue = (update, key) => (key === undefined ? undefined : update[key]);
+/** Counts array-shaped mutation inputs while treating other shapes as empty. */
+const updateArrayValueCount = (value) => Array.isArray(value) ? value.length : 0;
+/** Builds one collection plan when its definition has an active mutation. */
+const buildCollectionMutationPlan = (definition, row, update) => {
+    const addValues = update[definition.addKey];
+    const removeValues = readOptionalUpdateValue(update, definition.removeKey);
+    const addCount = updateArrayValueCount(addValues);
+    const removeCount = updateArrayValueCount(removeValues);
+    const clear = update[definition.clearKey] === true;
+    const replace = readOptionalUpdateValue(update, definition.replaceKey) === true;
+    if (![clear, replace, addCount > 0, removeCount > 0].includes(true)) {
+        return undefined;
+    }
+    const before = normalizeCollectionBeforeValue(definition.field, row[definition.field]);
+    return {
+        field: definition.field,
+        before,
+        after: {
+            operation: resolveCollectionMutationOperation({
+                replace,
+                clear,
+                removeCount,
+            }),
+            clear,
+            replace,
+            add_count: addCount,
+            remove_count: removeCount,
+            before_count: collectionValueCount(definition.field, before),
+        },
+    };
+};
+/** Builds collection mutation previews for every active collection option. */
+const buildCollectionMutationPlans = (row, update) => {
     const changes = [];
     for (const definition of COLLECTION_MUTATION_PLAN_DEFINITIONS) {
-        const addValues = update[definition.addKey];
-        const removeValues = definition.removeKey
-            ? update[definition.removeKey]
-            : undefined;
-        const addCount = Array.isArray(addValues) ? addValues.length : 0;
-        const removeCount = Array.isArray(removeValues) ? removeValues.length : 0;
-        const clear = update[definition.clearKey] === true;
-        const replace = definition.replaceKey
-            ? update[definition.replaceKey] === true
-            : false;
-        if (!clear && !replace && addCount === 0 && removeCount === 0) {
-            continue;
+        const plan = buildCollectionMutationPlan(definition, row, update);
+        if (plan !== undefined) {
+            changes.push(plan);
         }
-        const before = normalizeCollectionBeforeValue(definition.field, row[definition.field]);
-        const beforeCount = collectionValueCount(definition.field, before);
-        const operation = replace
-            ? "replace"
-            : clear
-                ? "clear_or_reset"
-                : removeCount > 0
-                    ? "merge_remove"
-                    : "append";
-        changes.push({
-            field: definition.field,
-            before,
-            after: {
-                operation,
-                clear,
-                replace,
-                add_count: addCount,
-                remove_count: removeCount,
-                before_count: beforeCount,
-            },
-        });
     }
     return changes;
-}
-function normalizeExistingTags(value) {
+};
+/** Keeps only string tags from an existing storage value. */
+const normalizeExistingTags = (value) => {
     if (!Array.isArray(value)) {
         return [];
     }
     return value.filter((tag) => typeof tag === "string");
-}
+};
 // Tags support three mutation modes that compose: --tags replaces, --add-tags
 // extends, --remove-tags prunes. Replicate runUpdate's resolution order so the
 // dry-run preview and the apply-mode actionable detection both account for
 // additive/subtractive tag mutations (a --add-tags-only update must NOT be
 // treated as a no-op skip).
-function buildTagMutationPlan(row, update) {
-    const hasReplace = update.tags !== undefined;
-    const hasAdd = Array.isArray(update.addTags) && update.addTags.length > 0;
-    const hasRemove = Array.isArray(update.removeTags) && update.removeTags.length > 0;
-    if (!hasReplace && !hasAdd && !hasRemove) {
+const buildTagMutationPlan = (row, update) => {
+    if (![
+        update.tags !== undefined,
+        updateArrayValueCount(update.addTags) > 0,
+        updateArrayValueCount(update.removeTags) > 0,
+    ].includes(true)) {
         return undefined;
     }
     const existing = normalizeExistingTags(row.tags);
-    const baseTags = hasReplace ? parseTags(update.tags) : existing;
+    const baseTags = update.tags === undefined ? existing : parseTags(update.tags);
     const withAdditions = mergeAdditiveTags(baseTags, update.addTags);
     const after = applyTagRemovals(withAdditions, update.removeTags)
         .slice()
@@ -351,64 +384,60 @@ function buildTagMutationPlan(row, update) {
         return undefined;
     }
     return { field: "tags", before: existing, after };
-}
-function buildPlannedItemDiff(item, update = {}, runtimeFieldRegistry) {
-    const safeUpdate = update;
-    const row = toItemRecord(item);
-    const changes = [];
-    const tagPlan = buildTagMutationPlan(row, safeUpdate);
-    if (tagPlan) {
-        changes.push(tagPlan);
-    }
+};
+/** Adds changed scalar options to a planned item diff. */
+const appendScalarMutationPlans = (changes, row, update) => {
     for (const [optionKey, itemKey] of Object.entries(UPDATE_OPTION_TO_ITEM_KEY)) {
-        const candidate = safeUpdate[optionKey];
+        const candidate = update[optionKey];
         if (candidate === undefined) {
             continue;
         }
         const before = row[itemKey];
         const after = toComparablePreviewValue(optionKey, candidate);
-        if (areValuesEqual(before, after)) {
-            continue;
+        if (!areValuesEqual(before, after)) {
+            changes.push({ field: itemKey, before, after });
         }
-        changes.push({
-            field: itemKey,
-            before,
-            after,
-        });
     }
-    changes.push(...buildCollectionMutationPlans(row, safeUpdate));
-    const runtimeFieldUpdates = collectRuntimeUpdateFieldValues(safeUpdate, runtimeFieldRegistry, ["update_many"]);
-    for (const [fieldKey, fieldValue] of Object.entries(runtimeFieldUpdates)) {
-        const before = row[fieldKey];
-        if (areValuesEqual(before, fieldValue)) {
-            continue;
+};
+/** Adds changed runtime-schema fields to a planned item diff. */
+const appendRuntimeFieldMutationPlans = (changes, row, update, runtimeFieldRegistry) => {
+    const runtimeFieldUpdates = collectRuntimeUpdateFieldValues(update, runtimeFieldRegistry, ["update_many"]);
+    for (const [field, after] of Object.entries(runtimeFieldUpdates)) {
+        const before = row[field];
+        if (!areValuesEqual(before, after)) {
+            changes.push({ field, before, after });
         }
-        changes.push({
-            field: fieldKey,
-            before,
-            after: fieldValue,
-        });
     }
-    if (safeUpdate.unset && safeUpdate.unset.length > 0) {
-        for (const rawUnsetField of safeUpdate.unset) {
-            const field = normalizeUnsetField(rawUnsetField);
-            const before = row[field];
-            if (before === undefined) {
-                continue;
-            }
-            changes.push({
-                field,
-                before,
-                after: null,
-            });
+};
+/** Adds present fields requested through unset options to a planned item diff. */
+const appendUnsetMutationPlans = (changes, row, unset) => {
+    for (const rawUnsetField of unset ?? []) {
+        const field = normalizeUnsetField(rawUnsetField);
+        const before = row[field];
+        if (before !== undefined) {
+            changes.push({ field, before, after: null });
         }
     }
+};
+/** Builds the complete storage-shaped mutation preview for one item. */
+const buildPlannedItemDiff = (item, runtimeFieldRegistry, update = {}) => {
+    const row = toItemRecord(item);
+    const changes = [];
+    const tagPlan = buildTagMutationPlan(row, update);
+    if (tagPlan) {
+        changes.push(tagPlan);
+    }
+    appendScalarMutationPlans(changes, row, update);
+    changes.push(...buildCollectionMutationPlans(row, update));
+    appendRuntimeFieldMutationPlans(changes, row, update, runtimeFieldRegistry);
+    appendUnsetMutationPlans(changes, row, update.unset);
     return {
         id: item.id,
         changes,
     };
-}
-function normalizeStatusFilter(value, statusRegistry) {
+};
+/** Normalizes an optional list status against the runtime schema. */
+const normalizeStatusFilter = (value, statusRegistry) => {
     if (value === undefined) {
         return undefined;
     }
@@ -418,44 +447,55 @@ function normalizeStatusFilter(value, statusRegistry) {
         throw new PmCliError(`Invalid --filter-status value "${value}". Allowed: ${allowedStatuses.join(", ")}`, EXIT_CODE.USAGE);
     }
     return normalized;
-}
-function rejectBlankIdsFilter(list) {
+};
+/** Rejects an explicitly blank bulk ID filter before loading the corpus. */
+const rejectBlankIdsFilter = (list) => {
     if (list?.ids != null && String(list.ids).trim().length === 0) {
         throw new PmCliError("--ids requires at least one non-empty item ID", EXIT_CODE.USAGE);
     }
-}
-// GH-256: validate planned scalar enum/format fields up front so a `--dry-run`
-// preview rejects globally-invalid values exactly as apply would (true
-// preview==apply parity), and so apply itself fails fast before creating an
-// orphan checkpoint. Only VALUE/ENUM/FORMAT correctness is checked here — these
-// are invalid regardless of the matched item. Per-item governance and
-// workflow-transition rules stay in the apply path (runUpdate). Each field is
-// validated only when the caller actually provided it, reusing the exact same
-// resolvers and error messages runUpdate raises so single/bulk/dry-run stay
-// consistent.
-function assertPlannedUpdateValuesValid(update, settings, statusRegistry, pmRoot) {
-    if (update.priority !== undefined) {
-        resolvePriority(update.priority);
-    }
-    if (update.type !== undefined) {
+};
+const PLANNED_UPDATE_VALIDATORS = [
+    ({ update }) => {
+        if (update.priority !== undefined) {
+            resolvePriority(update.priority);
+        }
+    },
+    ({ update, settings, pmRoot }) => {
+        if (update.type === undefined) {
+            return;
+        }
         const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
         if (!resolveTypeName(update.type, typeRegistry)) {
             throw new PmCliError(buildInvalidTypeError(update.type, typeRegistry.types, resolveItemTypesFilePath(pmRoot, settings.schema)), EXIT_CODE.USAGE);
         }
+    },
+    ({ update, statusRegistry }) => {
+        if (update.status !== undefined &&
+            !normalizeStatusInput(update.status, statusRegistry)) {
+            const allowedStatuses = statusRegistry.definitions.map((definition) => definition.id);
+            throw new PmCliError(`Invalid --status value "${update.status}". Allowed: ${allowedStatuses.join(", ")}`, EXIT_CODE.USAGE);
+        }
+    },
+    ({ update }) => {
+        if (update.deadline !== undefined) {
+            resolveIsoOrRelative(update.deadline, new Date(), "deadline");
+        }
+    },
+    ({ update }) => {
+        if (update.estimatedMinutes !== undefined) {
+            parseOptionalNonNegativeInteger(update.estimatedMinutes, "estimated-minutes");
+        }
+    },
+];
+/** Validates globally invalid mutation values before preview or checkpoint work. */
+const assertPlannedUpdateValuesValid = (update, settings, statusRegistry, pmRoot) => {
+    const context = { update, settings, statusRegistry, pmRoot };
+    for (const validate of PLANNED_UPDATE_VALIDATORS) {
+        validate(context);
     }
-    if (update.status !== undefined &&
-        !normalizeStatusInput(update.status, statusRegistry)) {
-        const allowedStatuses = statusRegistry.definitions.map((definition) => definition.id);
-        throw new PmCliError(`Invalid --status value "${update.status}". Allowed: ${allowedStatuses.join(", ")}`, EXIT_CODE.USAGE);
-    }
-    if (update.deadline !== undefined) {
-        resolveIsoOrRelative(update.deadline, new Date(), "deadline");
-    }
-    if (update.estimatedMinutes !== undefined) {
-        parseOptionalNonNegativeInteger(update.estimatedMinutes, "estimated-minutes");
-    }
-}
-async function runUpdateManyRollback(params) {
+};
+/** Restores every item captured by an update-many checkpoint. */
+const runUpdateManyRollback = async (params) => {
     const checkpoint = await loadMutationCheckpoint(params.pmRoot, UPDATE_MANY_CHECKPOINT_SUBDIR, params.rollbackId, UPDATE_MANY_CHECKPOINT_SCHEMA_VERSION);
     const restoreMessage = params.options.update?.message ??
         `Rollback update-many checkpoint ${checkpoint.id}`;
@@ -480,8 +520,9 @@ async function runUpdateManyRollback(params) {
         rows: rollback.rows,
         ids: rollback.restored_ids,
     };
-}
-async function writeUpdateManyCheckpoint(params) {
+};
+/** Persists an apply checkpoint and returns its user-facing descriptor. */
+const writeUpdateManyCheckpoint = async (params) => {
     const checkpointPayload = {
         schema_version: UPDATE_MANY_CHECKPOINT_SCHEMA_VERSION,
         id: params.checkpointId,
@@ -499,108 +540,103 @@ async function writeUpdateManyCheckpoint(params) {
         path: checkpointPath,
         rollback_command: `pm update-many --rollback ${params.checkpointId}`,
     };
-}
-/** Implements run update many for the public runtime surface of this module. */
-export async function runUpdateMany(options, global) {
+};
+/** Loads tracker settings and runtime registries for update-many execution. */
+const loadUpdateManyRuntimeContext = async (global) => {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const settings = await readSettings(pmRoot);
-    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
-    const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    const dryRun = options.dryRun === true;
-    const rollbackId = typeof options.rollback === "string" ? options.rollback : undefined;
-    const updateSummary = sanitizeUpdateOptionsForSummary(options.update);
-    rejectBlankIdsFilter(options.list);
-    if (rollbackId) {
-        if (dryRun) {
-            throw new PmCliError("--dry-run cannot be combined with --rollback", EXIT_CODE.USAGE);
-        }
-        if (hasListFilters(options.list, options.status)) {
-            throw new PmCliError("Rollback mode does not accept filter options", EXIT_CODE.USAGE);
-        }
-        if (Object.keys(updateSummary).length > 0) {
-            throw new PmCliError("Rollback mode does not accept update mutation flags", EXIT_CODE.USAGE);
-        }
-        return runUpdateManyRollback({ pmRoot, rollbackId, options, global });
-    }
-    if (!hasAnyUpdateMutationInput(options.update)) {
-        throw new PmCliError(`No update-many mutation flags provided. Add at least one mutation flag (for example: ${UPDATE_MANY_MUTATION_FLAG_GUIDANCE}).`, EXIT_CODE.USAGE);
-    }
-    // GH-256: validate planned scalar values before listing/checkpointing so
-    // dry-run previews and apply both reject globally-invalid enum/format input.
-    assertPlannedUpdateValuesValid(options.update, settings, statusRegistry, pmRoot);
-    const statusFilter = normalizeStatusFilter(options.status, statusRegistry);
-    const listed = await runList(statusFilter, { ...options.list, includeBody: true }, global);
-    const planned = listed.items.map((item) => buildPlannedItemDiff(item, options.update, runtimeFieldRegistry));
-    const actionable = planned.filter((row) => row.changes.length > 0);
-    if (dryRun) {
-        return {
-            mode: "dry_run",
-            matched_count: listed.items.length,
-            dry_run: true,
-            filters: listed.filters,
-            planned_update_options: updateSummary,
-            item_plans: planned,
-            ids: [],
-        };
-    }
-    if (actionable.length === 0) {
-        return {
-            mode: "apply",
-            matched_count: listed.items.length,
-            dry_run: false,
-            filters: listed.filters,
-            planned_update_options: updateSummary,
-            updated_count: 0,
-            skipped_count: listed.items.length,
-            failed_count: 0,
-            rows: planned.map((row) => ({
-                id: row.id,
-                status: "skipped",
-            })),
-            ids: [],
-        };
-    }
-    const nowValue = nowIso();
-    const checkpointId = createCheckpointId(UPDATE_MANY_CHECKPOINT_SUBDIR, nowValue);
-    const checkpointEnabled = options.checkpoint !== false;
-    const checkpointItems = listed.items
-        .filter((item) => actionable.some((candidate) => candidate.id === item.id))
-        .map((item) => ({
-        id: item.id,
-        target_updated_at: item.updated_at,
-    }));
-    let checkpointInfo;
-    if (checkpointEnabled) {
-        checkpointInfo = await writeUpdateManyCheckpoint({
-            pmRoot,
-            checkpointId,
-            nowValue,
-            options,
-            statusFilter,
-            filters: listed.filters,
-            updateSummary,
-            checkpointItems,
-        });
-    }
-    const applyRows = [];
+    return {
+        pmRoot,
+        settings,
+        statusRegistry: resolveRuntimeStatusRegistry(settings.schema),
+        runtimeFieldRegistry: resolveRuntimeFieldRegistry(settings.schema),
+    };
+};
+/** Validates rollback exclusivity before restoring a checkpoint. */
+const runRequestedUpdateManyRollback = (params) => {
+    if (params.options.dryRun === true) {
+        throw new PmCliError("--dry-run cannot be combined with --rollback", EXIT_CODE.USAGE);
+    }
+    if (hasListFilters(params.options.list, params.options.status)) {
+        throw new PmCliError("Rollback mode does not accept filter options", EXIT_CODE.USAGE);
+    }
+    if (Object.keys(params.updateSummary).length > 0) {
+        throw new PmCliError("Rollback mode does not accept update mutation flags", EXIT_CODE.USAGE);
+    }
+    return runUpdateManyRollback({
+        pmRoot: params.runtime.pmRoot,
+        rollbackId: params.rollbackId,
+        options: params.options,
+        global: params.global,
+    });
+};
+/** Loads complete matching rows and derives their mutation previews. */
+const buildUpdateManyPlan = async (params) => {
+    const statusFilter = normalizeStatusFilter(params.options.status, params.runtime.statusRegistry);
+    const listed = await runList(statusFilter, {
+        ...params.options.list,
+        compact: undefined,
+        brief: undefined,
+        fields: undefined,
+        includeBody: true,
+        full: true,
+    }, params.global);
+    const planned = listed.items.map((item) => buildPlannedItemDiff(item, params.runtime.runtimeFieldRegistry, params.options.update));
+    return {
+        listed,
+        planned,
+        actionable: planned.filter((row) => row.changes.length > 0),
+        updateSummary: params.updateSummary,
+        statusFilter,
+    };
+};
+/** Builds the non-mutating preview response for a prepared update-many plan. */
+const buildUpdateManyDryRunResult = (plan) => ({
+    mode: "dry_run",
+    matched_count: plan.listed.items.length,
+    dry_run: true,
+    filters: plan.listed.filters,
+    planned_update_options: plan.updateSummary,
+    item_plans: plan.planned,
+    ids: [],
+});
+/** Builds the apply response for a plan whose rows are all already current. */
+const buildUpdateManyNoopResult = (plan) => ({
+    mode: "apply",
+    matched_count: plan.listed.items.length,
+    dry_run: false,
+    filters: plan.listed.filters,
+    planned_update_options: plan.updateSummary,
+    updated_count: 0,
+    skipped_count: plan.listed.items.length,
+    failed_count: 0,
+    rows: plan.planned.map((row) => ({
+        id: row.id,
+        status: "skipped",
+    })),
+    ids: [],
+});
+/** Applies planned item updates independently while preserving per-row failures. */
+const applyUpdateManyRows = async (params) => {
+    const rows = [];
     const updatedIds = [];
-    const updateMessage = options.update.message ?? `update-many apply ${checkpointId}`;
-    const actionableById = new Set(actionable.map((row) => row.id));
-    for (const item of listed.items) {
+    const updateMessage = params.options.update.message ?? `update-many apply ${params.checkpointId}`;
+    const actionableById = new Set(params.actionable.map((row) => row.id));
+    for (const item of params.items) {
         if (!actionableById.has(item.id)) {
-            applyRows.push({ id: item.id, status: "skipped" });
+            rows.push({ id: item.id, status: "skipped" });
             continue;
         }
         try {
             const result = await runUpdate(item.id, {
-                ...options.update,
+                ...params.options.update,
                 message: updateMessage,
                 runtimeFieldCommands: ["update_many"],
-            }, global);
-            applyRows.push({
+            }, params.global);
+            rows.push({
                 id: item.id,
                 status: "updated",
                 changed_fields: result.changed_fields,
@@ -609,30 +645,90 @@ export async function runUpdateMany(options, global) {
             updatedIds.push(item.id);
         }
         catch (error) {
-            applyRows.push({
+            rows.push({
                 id: item.id,
                 status: "failed",
                 error: toErrorMessage(error),
             });
         }
     }
-    const updatedCount = applyRows.filter((row) => row.status === "updated").length;
-    const skippedCount = applyRows.filter((row) => row.status === "skipped").length;
-    const failedCount = applyRows.filter((row) => row.status === "failed").length;
+    return { rows, updatedIds };
+};
+/** Applies a prepared plan, checkpointing actionable rows when requested. */
+const applyUpdateManyPlan = async (params) => {
+    if (params.plan.actionable.length === 0) {
+        return buildUpdateManyNoopResult(params.plan);
+    }
+    const nowValue = nowIso();
+    const checkpointId = createCheckpointId(UPDATE_MANY_CHECKPOINT_SUBDIR, nowValue);
+    const actionableById = new Set(params.plan.actionable.map((row) => row.id));
+    const checkpointItems = params.plan.listed.items
+        .filter((item) => actionableById.has(item.id))
+        .map((item) => ({ id: item.id, target_updated_at: item.updated_at }));
+    const checkpointInfo = params.options.checkpoint === false
+        ? undefined
+        : await writeUpdateManyCheckpoint({
+            pmRoot: params.runtime.pmRoot,
+            checkpointId,
+            nowValue,
+            options: params.options,
+            statusFilter: params.plan.statusFilter,
+            filters: params.plan.listed.filters,
+            updateSummary: params.plan.updateSummary,
+            checkpointItems,
+        });
+    const applied = await applyUpdateManyRows({
+        items: params.plan.listed.items,
+        actionable: params.plan.actionable,
+        options: params.options,
+        global: params.global,
+        checkpointId,
+    });
+    /** Counts apply rows with one terminal status. */
+    const countStatus = (status) => applied.rows.filter((row) => row.status === status).length;
     return {
         mode: "apply",
-        matched_count: listed.items.length,
+        matched_count: params.plan.listed.items.length,
         dry_run: false,
-        filters: listed.filters,
-        planned_update_options: updateSummary,
+        filters: params.plan.listed.filters,
+        planned_update_options: params.plan.updateSummary,
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        updated_count: updatedCount,
-        skipped_count: skippedCount,
-        failed_count: failedCount,
-        rows: applyRows,
-        ids: updatedIds,
+        updated_count: countStatus("updated"),
+        skipped_count: countStatus("skipped"),
+        failed_count: countStatus("failed"),
+        rows: applied.rows,
+        ids: applied.updatedIds,
     };
-}
+};
+/** Implements run update many for the public runtime surface of this module. */
+export const runUpdateMany = async (options, global) => {
+    const runtime = await loadUpdateManyRuntimeContext(global);
+    const rollbackId = typeof options.rollback === "string" ? options.rollback : undefined;
+    const updateSummary = sanitizeUpdateOptionsForSummary(options.update);
+    rejectBlankIdsFilter(options.list);
+    if (rollbackId !== undefined) {
+        return runRequestedUpdateManyRollback({
+            runtime,
+            rollbackId,
+            options,
+            global,
+            updateSummary,
+        });
+    }
+    if (!hasAnyUpdateMutationInput(options.update)) {
+        throw new PmCliError(`No update-many mutation flags provided. Add at least one mutation flag (for example: ${UPDATE_MANY_MUTATION_FLAG_GUIDANCE}).`, EXIT_CODE.USAGE);
+    }
+    assertPlannedUpdateValuesValid(options.update, runtime.settings, runtime.statusRegistry, runtime.pmRoot);
+    const plan = await buildUpdateManyPlan({
+        options,
+        global,
+        runtime,
+        updateSummary,
+    });
+    return options.dryRun === true
+        ? buildUpdateManyDryRunResult(plan)
+        : applyUpdateManyPlan({ runtime, options, global, plan });
+};
 /** Public contract for test only update many command, shared by SDK and presentation-layer consumers. */
 export const _testOnlyUpdateManyCommand = {
     assertPlannedUpdateValuesValid,
@@ -651,4 +747,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=66fd8f1d-25f8-55fc-85ea-ea3000479f01
+//# debugId=19acba6b-a459-52ce-b267-6f1d0db63265