monday-cli 0.6.0 → 0.7.1

package/dist/commands/item/update.js

@@ -55,6 +55,8 @@ import { executeItemMutation } from '../../api/item-mutation-execute.js';
 import { executeFileColumnSet, fileColumnSetOutputSchema, preCheckM38FileDispatch, } from '../../api/file-column-set.js';
 import { precheckLocalFile } from '../../utils/file-source.js';
 import { invalidateBoard } from '../../api/cache.js';
+import { dispatchSequential, } from '../../api/partial-success-mutation.js';
+import { dispatchParallel } from '../../api/parallel-dispatch.js';
 import { parseSetRawExpression, } from '../../api/raw-write.js';
 import { splitSetExpression } from '../../api/set-expression.js';
 import { buildResolutionContexts } from '../../api/resolution-context.js';
@@ -75,11 +77,15 @@ import { MIN_CONCURRENCY, MAX_CONCURRENCY, } from '../../api/parallel-dispatch.j
 /**
  * Output envelope union — projected-item for the JSON translator
  * path (text / status / dropdown / date / people / etc.) +
- * file-dispatch envelope for the v0.6-M38 friendly `--set
- * <file-col>=<path>` path (single-item shape only; bulk file
- * dispatch rejects per D5). Agents discriminate on the `operation`
- * field: present (`'add_file_to_column'`) → file dispatch shape;
- * absent → projected-item shape.
+ * file-dispatch envelope for the friendly `--set <file-col>=<path>`
+ * path. The file-dispatch shape ships across v0.6-M38 (single-item
+ * — `operation: 'add_file_to_column'`) and v0.7-M42 (bulk —
+ * `operation: 'item_update_bulk_file_set'`; the per-item fan-out's
+ * `data.results[i].asset` slots wrap M31's `Asset` projection). The
+ * union below admits only the single-item shape because the bulk
+ * variant is emitted via its own `bulkFileSetDataSchema` at the
+ * `runItemUpdateBulkFileDispatch` helper; agents discriminate on
+ * `operation` (present + literal value identifies the variant).
  */
 export const itemUpdateOutputSchema = z.union([
     projectedItemSchema,
@@ -281,6 +287,7 @@ export const itemUpdateCommand = {
                     apiVersion,
                     ctx,
                     programOpts: program.opts(),
+                    multipart,
                 });
                 return;
             }
@@ -605,7 +612,7 @@ const bulkLiveDataSchema = z.object({
  * `--concurrency` flag is the future extension point.
  */
 const runBulk = async (inputs) => {
-    const { parsed, client, globalFlags, apiVersion, ctx, programOpts } = inputs;
+    const { parsed, client, globalFlags, apiVersion, ctx, programOpts, multipart } = inputs;
     /* c8 ignore next 6 — defensive: validateInputShape guarantees
        parsed.board is non-undefined when shape is bulk; the type
        guard exists for TS. */
@@ -630,18 +637,37 @@ const runBulk = async (inputs) => {
         env: ctx.env,
         noCache: globalFlags.noCache,
     });
-    // 1.5) v0.6-M38 D5 closure — bulk file-set REJECTS at the
-    //      column-resolution boundary, BEFORE the items_page walker
-    //      + confirmation gate. The pre-check resolves setEntries
-    //      against the now-warm metadata cache and runs
-    //      `enforceSingleFileColumnSet({callShape: 'item_update_bulk'})`
-    //      which throws `'file_set_on_bulk_unsupported'` whenever
-    //      any setEntry is a `file`-typed column. `--set-raw
-    //      <file-col>=<json>` stays at `translateRawColumnValue`'s
-    //      D3 permanent rejection (the pre-check only inspects
-    //      setEntries; the standard path's `translateRawColumnValue`
-    //      handles --set-raw rejection unchanged).
+    // 1.5) File-column dispatch pre-check at the column-resolution
+    //      boundary, BEFORE the items_page walker + confirmation
+    //      gate. The pre-check resolves setEntries against the now-
+    //      warm metadata cache and runs
+    //      `enforceSingleFileColumnSet({callShape: 'item_update_bulk'})`:
+    //
+    //        - Multi-file `--set` → throws `'multi_file_set_unsupported'`
+    //          (universal rule; single-column-per-wire-call).
+    //        - File `--set` + value `--set` / `--set-raw` / `--name`
+    //          → throws `'mixed_file_and_value_sets'` (universal rule;
+    //          mixing forces non-atomic multi-leg dispatch).
+    //        - Clean single file `--set` → returns
+    //          `kind: 'file_bulk'` (v0.7-M42 D5 carve-out fold;
+    //          action body branches into the per-item multipart
+    //          fan-out helper `runItemUpdateBulkFileDispatch` —
+    //          shipped at v0.7-M42 IMPL).
+    //        - No file `--set` → returns `kind: 'json'` (standard
+    //          JSON-translator path continues).
+    //
+    //      At v0.6-M38 the `'item_update_bulk'` callShape rejected
+    //      ALL bulk file `--set` paths with
+    //      `'file_set_on_bulk_unsupported'`; v0.7-M42 pre-flight
+    //      contract diff (`160330b`) carved that out per D5 fold,
+    //      and IMPL (`22df2fa` + R1 fix-up `968b154`) shipped the
+    //      runtime body. `--set-raw <file-col>=<json>` stays at
+    //      `translateRawColumnValue`'s D3 permanent rejection (the
+    //      pre-check only inspects setEntries; the standard path's
+    //      `translateRawColumnValue` handles --set-raw rejection
+    //      unchanged).
     let m38Warnings = [];
+    let m38FileBulk;
     if (setEntries.length > 0) {
         const m38 = await preCheckM38FileDispatch({
             client,
@@ -653,13 +679,20 @@ const runBulk = async (inputs) => {
             env: ctx.env,
             noCache: globalFlags.noCache,
         });
-        // Round-2 P3-1 fix: capture pre-check warnings to thread
-        // them into the final envelope. The bulk `'item_update_bulk'`
-        // callShape throws on any file entry, so reaching this point
-        // means `m38.kind === 'json'`. Pre-check resolution warnings
-        // (column_token_collision / stale_cache_refreshed) survive
-        // even though downstream cache hits suppress re-emission.
+        // Round-2 P3-1 fix carry-forward: capture pre-check warnings
+        // to thread them into the final envelope. Pre-check resolution
+        // warnings (column_token_collision / stale_cache_refreshed)
+        // survive even though downstream cache hits suppress
+        // re-emission.
         m38Warnings = m38.warnings;
+        if (m38.kind === 'file_bulk') {
+            // v0.7-M42 D5 carve-out fold. Hold the file_bulk slot for
+            // the items_page-walked dispatch leg below; the items_page
+            // walker still runs (collects target item IDs) + the
+            // confirmation gate still applies + the dispatch loop fans
+            // `executeFileColumnSet` across matched items.
+            m38FileBulk = m38;
+        }
     }
     const onColumnNotFound = meta.source === 'cache'
         ? async () => {
@@ -781,6 +814,40 @@ const runBulk = async (inputs) => {
     // fail-fast invariant. (See step 0 above — moving the parse there
     // means a malformed --set / --set-raw doesn't pay for the metadata
     // load + items_page walk first.)
+    // v0.7-M42 D5 carve-out fold — bulk file `--set` dispatch leg.
+    // When the pre-check returned `kind: 'file_bulk'`, branch into
+    // the per-item multipart fan-out helper here. The branch fires
+    // AFTER the items_page walker + confirmation gate (so an agent
+    // sees the matched-count via `confirmation_required` before
+    // the bulk file dispatch fans out) and BEFORE the JSON
+    // translator path's `resolveAndTranslate` call (which has
+    // nothing to translate when every `--set` is a file column).
+    //
+    // The helper runs single upfront `precheckLocalFile` + per-item
+    // `executeFileColumnSet` (fail-fast vs `--continue-on-error`
+    // per `parsed.continueOnError`; sequential vs parallel per
+    // `parsed.concurrency`) + post-dispatch `invalidateBoard` +
+    // envelope emit (`operation: 'item_update_bulk_file_set'`).
+    if (m38FileBulk !== undefined) {
+        await runItemUpdateBulkFileDispatch({
+            parsed,
+            client,
+            multipart,
+            ctx,
+            programOpts,
+            apiVersion,
+            boardId,
+            matchedItemIds,
+            m38: m38FileBulk,
+            metaSource: meta.source,
+            metaCacheAgeSeconds: meta.cacheAgeSeconds,
+            filterWarnings: filterResult.warnings,
+            retries: globalFlags.retry,
+            isDryRun: globalFlags.dryRun,
+            noCache: globalFlags.noCache,
+        });
+        return;
+    }
     const { dateResolution, peopleResolution, tagResolution, relationResolution } = buildResolutionContexts({ client, ctx, globalFlags });
     // 5) Dry-run path: per-item planChanges. Column resolution is
     //    cached after the first call; per-item state read fires per
@@ -806,12 +873,12 @@ const runBulk = async (inputs) => {
             cacheAgeSeconds: meta.cacheAgeSeconds,
         });
         for (const itemId of matchedItemIds) {
-            // v0.6-M38 D5 file-set rejection already fired at the pre-check
-            // above (step 1.5) — bulk file-set never reaches this loop body
-            // since `preCheckM38FileDispatch({callShape: 'item_update_bulk'})`
-            // throws `'file_set_on_bulk_unsupported'` before items_page
-            // walks. `--set-raw <file-col>=<json>` still rejects normally
-            // via `translateRawColumnValue`'s D3 permanent rejection.
+            // v0.7-M42 IMPL: clean bulk file `--set` paths branched into
+            // `runItemUpdateBulkFileDispatch` above (the `m38FileBulk !==
+            // undefined` arm) and returned before reaching this loop, so
+            // this dry-run body only ever sees JSON-shaped paths.
+            // `--set-raw <file-col>=<json>` still rejects normally via
+            // `translateRawColumnValue`'s D3 permanent rejection.
             let result;
             try {
                 result = await planChanges({
@@ -1211,4 +1278,605 @@ const runItemUpdateSingleFileDispatch = async (inputs) => {
         resolvedIds: { [inputs.m38.token]: inputs.m38.columnId },
     });
 };
+// ============================================================
+// v0.7-M42 bulk file `--set` carve-out fold (D5 closure from
+// v0.6-M38). Per-item multipart fan-out over the `--where`-resolved
+// item-id set, reusing v0.4-M31's `executeFileColumnSet` runtime
+// body verbatim under v0.4-M30's `dispatchParallel` /
+// `dispatchSequential` selector for `--concurrency` semantics.
+//
+// **Status: runtime body shipped at v0.7-M42 IMPL.** The pre-flight
+// contract diff (commit `160330b`) shipped the argv + pre-check +
+// items_page + confirmation-gate surface plus the per-item dispatch
+// stub that threw `internal_error` with `details.reason:
+// 'm42_preflight_stub'`; IMPL replaces the stub with the runtime
+// body below. The `'m42_preflight_stub'` literal is RESERVED across
+// the codebase (regression-guarded by an integration test that
+// asserts the literal does not appear in stdout/stderr); a
+// historical `'file_set_on_bulk_unsupported'` literal stays
+// reserved alongside it.
+//
+// **D-list closures (v0.7-plan §3 M42 entry):**
+//
+//   - **D1 — `--concurrency` semantics for file dispatch.** Reuse
+//     v0.4-M30's `dispatchParallel` over a shared
+//     `MultipartTransport`. Each parallel worker constructs its
+//     own `MultipartTransportRequest` per call; the transport
+//     itself is connection-pool-shared per-token. Closes by
+//     inheritance from M30 (concurrency probe pinned at
+//     `scripts/probe/m30-concurrency.report.txt`) + M31 (multipart
+//     wire pinned at `scripts/probe/m31-asset-upload.report.txt`).
+//     No new probe required.
+//
+//   - **D2 — Per-item asset slot in envelope.** Per-item
+//     `data.results[i].asset: { id, name, ... }` echo on success
+//     (mirrors M31's `itemUploadOutputSchema`'s `asset` slot);
+//     per-item failure surfaces as
+//     `data.results[i].error: { code, message }` per M25
+//     partial-success. Aggregate `data.summary.{matched_count,
+//     applied_count, failed_count, board_id, column_id, filename,
+//     file_size_bytes}` extends M25's
+//     `partialSuccessBulkUpdateDataSchema` with file-dispatch slots
+//     so an agent reading the envelope sees which file was
+//     dispatched + where.
+//
+//   - **D3 — Per-item file pre-check timing.** Single upfront
+//     `precheckLocalFile` call BEFORE the per-item dispatch loop —
+//     the bulk shape has ONE file path (the value of the file
+//     `--set`) shared across N matched items. A failed pre-check
+//     surfaces upfront as `usage_error` with `details.reason:
+//     'file_not_readable'` / `'file_empty'` (mirrors M31 single-
+//     item shape) — this is whole-call-abort regardless of
+//     `--continue-on-error`, per cli-design §5.8's "pre-checks
+//     MUST fire BEFORE any wire round-trip" atomicity discipline.
+//     The `--continue-on-error` flag partitions ONLY the wire-
+//     dispatch failures (per-item `add_file_to_column` rejections
+//     from Monday), never the local file pre-check.
+//
+//   - **D4 — ERROR_CODES delta.** Zero. Registry stays at 29.
+//     Per-item dispatch failures route through the existing
+//     `m25-shaped` per-record `error: { code, message }` shape
+//     under `--continue-on-error`, or through the v0.1 fail-fast
+//     decoration (`details.applied_to` + `applied_count` +
+//     `failed_at_item` + `matched_count`) on the default path;
+//     no new top-level code surfaces.
+//
+// **R-class watch-items.**
+//
+//   - R-v0.6-NEW-1 (file pre-check + Blob-construction helper) —
+//     `precheckLocalFile` consumer count goes 3 → 4 at IMPL (M31
+//     item upload + M31 update upload + M38 item set / item update
+//     single + M42 bulk item update). Already-shipped helper
+//     scales cleanly to consumer 4; graduation candidate at the
+//     5th consumer (v0.7-M43 create-time fold likely tips it).
+//   - R-v0.6-NEW-2 (`details.reason` discriminator pattern) — 4
+//     instances at v0.6-M38; M42 IMPL adds zero new reasons (per
+//     D4 zero-delta closure — the existing `'file_not_readable'`
+//     / `'file_empty'` / `'multi_file_set_unsupported'` /
+//     `'mixed_file_and_value_sets'` reasons cover every M42
+//     rejection shape).
+//   - R-NEW-76 (parseArgv-BEFORE-c8) — applied at pre-flight; the
+//     c8-ignore boundary dropped at IMPL (runtime body fully
+//     covered).
+//   - R-NEW-72 (post-fix-up cross-doc grep) — apply at every
+//     Codex IMPL fix-up round that flips a contract surface.
+//
+// **Future lift candidate.** The fail-fast error-decoration block
+// (`if (err.code === 'usage_error') { throw new UsageError(...) } else
+// { throw new ApiError(...) }`) is byte-equivalent across this
+// helper and the JSON-bulk action body (R-NEW-58 2-consumer
+// trigger). Lift candidate fires at the 3rd consumer (M43 create-
+// time fold may add one if its rollback / orphan-warn shape
+// re-uses the same decoration).
+// ============================================================
+/**
+ * Per-item dispatch result for v0.7-M42 bulk file `--set` carve-out
+ * fold. Mirrors the M25 `partialSuccessBulkUpdateResultSchema` shape
+ * with the file-dispatch's `asset` slot replacing the JSON path's
+ * `item` projection:
+ *
+ *   - Success: `{ item_id, ok: true, asset: { id, name, ... } }`
+ *   - Failure: `{ item_id, ok: false, error: { code, message } }`
+ *
+ * Schema landed at the v0.7-M42 pre-flight contract diff
+ * (`160330b`); runtime body shipped at v0.7-M42 IMPL (`22df2fa`)
+ * + R1 fix-up (`968b154`).
+ */
+export const bulkFileSetResultSchema = z.object({
+    item_id: z.string().min(1),
+    ok: z.boolean(),
+    asset: z
+        .object({
+        id: z.string().min(1),
+        name: z.string().min(1),
+    })
+        .loose()
+        .optional(),
+    error: z
+        .object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+    })
+        .optional(),
+});
+/**
+ * Output `data` shape for the v0.7-M42 bulk file `--set` envelope.
+ * Mirrors M25's `partialSuccessBulkUpdateDataSchema` structure —
+ * `operation: 'item_update_bulk_file_set'` literal discriminator
+ * + `summary.{matched_count, applied_count, failed_count,
+ * board_id}` aggregate slots + per-item `results[]` array.
+ *
+ * Invariant: `matched_count === applied_count + failed_count` for
+ * every emitted envelope (mirrors M25's invariant).
+ */
+export const bulkFileSetDataSchema = z.object({
+    operation: z.literal('item_update_bulk_file_set'),
+    summary: z.object({
+        matched_count: z.number().int().nonnegative(),
+        applied_count: z.number().int().nonnegative(),
+        failed_count: z.number().int().nonnegative(),
+        board_id: z.string().min(1),
+        column_id: z.string().min(1),
+        filename: z.string().min(1),
+        file_size_bytes: z.number().int().nonnegative(),
+    }),
+    results: z.array(bulkFileSetResultSchema),
+});
+/**
+ * Bulk file `--set` per-item dispatch helper (v0.7-M42 D5 carve-out
+ * fold).
+ *
+ * **Status: runtime body shipped at v0.7-M42 IMPL.** argv parse,
+ * shape validation, board-metadata load, pre-check (which returned
+ * `kind: 'file_bulk'` for callers reaching this helper), items_page
+ * walk, and the confirmation gate run upstream — this helper takes
+ * the resolved file-column dispatch slot + matched item-IDs and
+ * fans the multipart wire across them under the partial-success vs
+ * fail-fast contract.
+ *
+ * **Execution shape:**
+ *
+ *   1. Single upfront `precheckLocalFile(inputs.m38.rawValue)` —
+ *      one file path shared across all matched items. Failure
+ *      surfaces as `usage_error` (`file_not_readable` /
+ *      `file_empty`) whole-call-abort regardless of
+ *      `--continue-on-error` per D3 + cli-design §5.8 atomicity
+ *      discipline (pre-checks MUST fire BEFORE any wire round-trip).
+ *   2. Dry-run branch — emits the D4-shaped envelope with one
+ *      `add_file_to_column` planned_change per matched item-ID
+ *      (no file bytes loaded; no multipart wire). Unlike M38
+ *      single-item which pins `source: 'none'` (its dry-run is
+ *      pure-local), bulk dry-run carries the upstream legs'
+ *      aggregated `source` (metadata load + items_page walk —
+ *      `mixed` when metadata was cache-served, `live` otherwise);
+ *      reaching this branch already paid for those wire legs.
+ *   3. Live dispatch — two shapes per `parsed.continueOnError`:
+ *      - **Fail-fast (default)** — sequential loop over matched
+ *        items (no `--concurrency` per M30 D2 closure:
+ *        `--concurrency requires --continue-on-error`); first
+ *        per-item failure aborts whole-call with the v0.1-shaped
+ *        `details.applied_to` / `applied_count` / `failed_at_item`
+ *        / `matched_count` decoration so agents see how many
+ *        items applied before the failure.
+ *      - **`--continue-on-error`** — routes through
+ *        {@link dispatchSequential} (concurrency `undefined`/`1`)
+ *        or {@link dispatchParallel} (concurrency `> 1`) over a
+ *        shared {@link MultipartTransport}; per-item failures
+ *        land as `data.results[i].error: {code, message}` records,
+ *        successes carry `data.results[i].asset` via a side-map
+ *        fold keyed by `item_id`. `internal_error` re-throws
+ *        whole-call via the shared dispatchers' escape hatch
+ *        (M14 round-2 F1 precedent) so schema drift surfaces as
+ *        top-level `ok: false` rather than per-record.
+ *   4. Cache invalidation — single `invalidateBoard(boardId, env)`
+ *      after the dispatch loop completes (mirrors M38's single-
+ *      leg invalidate timing; one board covers every matched
+ *      item's mutated `asset` slot).
+ *   5. Envelope emit — `data: BulkFileSetData` with the
+ *      `operation: 'item_update_bulk_file_set'` literal
+ *      discriminator + per-item `results[]` + aggregate
+ *      `summary.{matched_count, applied_count, failed_count,
+ *      board_id, column_id, filename, file_size_bytes}`. Warnings
+ *      threaded as `dedupeWarnings([...filterWarnings,
+ *      ...m38.warnings])` (mirrors the JSON-bulk path); source
+ *      derives from `metaSource` (cache-served metadata + live
+ *      wire calls → `mixed`).
+ */
+export const runItemUpdateBulkFileDispatch = async (inputs) => {
+    // 1) Single upfront pre-check (D3 closure). Whole-call abort
+    //    regardless of `--continue-on-error` per cli-design §5.8 —
+    //    the local file pre-check is shared across N matched items,
+    //    so failure aborts the whole call before any multipart wire
+    //    leg fires. `precheckLocalFile` throws `usage_error` with
+    //    `details.reason: 'file_not_readable'` / `'file_empty'`
+    //    (M31 single-item discriminators reused per D4 zero-delta
+    //    closure).
+    const precheck = await precheckLocalFile(inputs.m38.rawValue);
+    // Combined warnings list threaded into every envelope emit below.
+    // Mirrors the JSON-bulk `dedupeWarnings(filter ∪ m38)` pattern at
+    // the action body; key is `code+message+token` so a pre-check
+    // `stale_cache_refreshed` plus a filter-time `stale_cache_refreshed`
+    // for the SAME token collapse to one entry.
+    const combinedWarnings = dedupeWarnings([
+        ...inputs.filterWarnings,
+        ...inputs.m38.warnings,
+    ]);
+    // Source/cache-age aggregator. Seeded with the metadata leg, then
+    // folds the M38 pre-check leg + a synthetic 'live' leg representing
+    // the items_page walker (always live, fired upstream before this
+    // helper). On dry-run the dispatch leg never fires; on live the
+    // dispatch leg adds another 'live' record (idempotent under
+    // `mergeSource` since 'live' + 'live' = 'live'). Codex IMPL R1
+    // P2-1 fix — pre-fix the helper dropped `inputs.m38.source` +
+    // `inputs.m38.cacheAgeSeconds`, so a cache-served file-column
+    // resolution after a live metadata fetch surfaced `'live'`
+    // instead of `'mixed'`. Mirrors the JSON-bulk path's
+    // SourceAggregator pattern at runBulk's dry-run + live legs.
+    const sourceAgg = new SourceAggregator({
+        source: inputs.metaSource,
+        cacheAgeSeconds: inputs.metaCacheAgeSeconds,
+    });
+    if (inputs.m38.source !== undefined) {
+        sourceAgg.record(inputs.m38.source, inputs.m38.cacheAgeSeconds);
+    }
+    // items_page walker always fires live before reaching the helper
+    // (the empty-match short-circuit is the only path that skips it,
+    // and that path emits the envelope upstream — this helper never
+    // sees matchedItemIds.length === 0). Record one synthetic 'live'
+    // leg so the aggregate reflects the wire round-trip cost the
+    // caller already paid.
+    sourceAgg.record('live', null);
+    // 2) Dry-run branch — D4-shaped envelope. One
+    //    `add_file_to_column` planned_change per matched item-ID;
+    //    no file bytes loaded, no multipart wire round-trip. Unlike
+    //    the M38 single-item dry-run (which pins `source: 'none'`
+    //    because its dry-run is pure-local), bulk dry-run carries
+    //    the aggregated upstream `source` — metadata load + items_page
+    //    walk + M38 pre-check already paid for wire legs to reach
+    //    here.
+    if (inputs.isDryRun) {
+        const plannedChanges = inputs.matchedItemIds.map((itemId) => ({
+            operation: 'add_file_to_column',
+            item_id: itemId,
+            column_id: inputs.m38.columnId,
+            file_path: inputs.m38.rawValue,
+            filename: precheck.filename,
+            file_size_bytes: precheck.fileSizeBytes,
+        }));
+        const dryRunAgg = sourceAgg.result();
+        emitDryRun({
+            ctx: inputs.ctx,
+            programOpts: inputs.programOpts,
+            plannedChanges,
+            source: dryRunAgg.source,
+            cacheAgeSeconds: dryRunAgg.cacheAgeSeconds,
+            warnings: combinedWarnings,
+            apiVersion: inputs.apiVersion,
+        });
+        return;
+    }
+    // 3) Live dispatch. Build the shared `FileColumnSetEntry` once —
+    //    every per-item leg uses the SAME local file (one path × N
+    //    items), so `buildBlobFromPath` (inside `executeFileColumnSet`)
+    //    re-reads the bytes per leg rather than sharing one Blob
+    //    instance. Re-reading per-leg is the simpler shape; a future
+    //    optimisation could memoise the bytes if profiling motivates
+    //    it (~bytes × N reads vs ~bytes × 1 read + held in memory).
+    const entry = {
+        columnId: inputs.m38.columnId,
+        columnType: 'file',
+        rawValue: inputs.m38.rawValue,
+        filePath: precheck.filePath,
+        filename: precheck.filename,
+        fileSizeBytes: precheck.fileSizeBytes,
+    };
+    // Live dispatch is always 'live' — fold one more leg into the
+    // aggregator. Idempotent if metadata + pre-check were also live
+    // ('live' + 'live' = 'live'); promotes 'cache' to 'mixed' when
+    // metadata/pre-check served from cache.
+    sourceAgg.record('live', null);
+    const liveAgg = sourceAgg.result();
+    // resolved_ids slot — pre-check returned the resolved column ID
+    // for the file token; echo it into the envelope's
+    // `meta.resolved_ids` so agents can confirm token-to-ID resolution
+    // (mirrors the M38 single-item envelope at `runItemUpdateSingleFileDispatch`).
+    const resolvedIds = { [inputs.m38.token]: inputs.m38.columnId };
+    // Resolution source for foldAndRemap — defaults to 'live' when
+    // pre-check didn't record one (no resolveColumnWithRefresh leg
+    // fired; the only path that's possible is the no-setEntries
+    // shortcut, which doesn't reach this helper). The remap probe
+    // refreshes board metadata + re-checks the file column's
+    // `archived` flag when a Monday-side `validation_failed`
+    // surfaces against cache-served file-column resolution. Codex
+    // IMPL R1 P1-1 fix.
+    const remapSource = inputs.m38.source ?? 'live';
+    // Discriminator for the dispatch shape: fail-fast (default,
+    // applied to the v0.1 fail-fast bulk path's `applied_to` decoration)
+    // vs `--continue-on-error` (partial-success per-record envelope).
+    // M30 D2 closure pins `--concurrency requires --continue-on-error`,
+    // so fail-fast bulk file dispatch is always sequential N=1.
+    const continueOnError = inputs.parsed.continueOnError === true;
+    if (!continueOnError) {
+        // Fail-fast bulk file dispatch. Sequential loop; first per-item
+        // failure aborts whole-call. Track applied (item_id, asset)
+        // pairs so the failure decoration can echo `applied_to` (matches
+        // the JSON-bulk fail-fast pattern at runBulk's main loop).
+        const appliedAssets = [];
+        for (const itemId of inputs.matchedItemIds) {
+            try {
+                const result = await executeFileColumnSet({
+                    client: inputs.client,
+                    multipart: inputs.multipart,
+                    itemId,
+                    entry,
+                    signal: inputs.ctx.signal,
+                    retries: inputs.retries,
+                });
+                appliedAssets.push({ itemId, asset: result.asset });
+            }
+            catch (err) {
+                if (err instanceof MondayCliError) {
+                    // Codex IMPL R1 P2-2 fix: if any prior item applied
+                    // successfully, the board's asset state already mutated
+                    // wire-side — invalidate the cache BEFORE re-throwing the
+                    // fail-fast error so a follow-up read doesn't serve stale
+                    // metadata. Mirrors the M38 single-item invalidate-on-
+                    // success pattern; the JSON-bulk fail-fast path has the
+                    // same gap (unchanged by this commit — separate lift
+                    // candidate per the future-lift-candidate note in the
+                    // module docstring).
+                    if (appliedAssets.length > 0) {
+                        await invalidateBoard(inputs.boardId, inputs.ctx.env);
+                    }
+                    // Codex IMPL R1 P1-1 fix: apply `foldAndRemap` BEFORE
+                    // building the decoration so per-item failures inherit
+                    // the SAME `validation_failed` → `column_archived`
+                    // stale-cache remap the JSON-bulk fail-fast path applies
+                    // (cli-design §6.5 stable-code rule). Without this, an
+                    // archived file column surfaces `validation_failed` on
+                    // file-bulk dispatch but `column_archived` on JSON-bulk
+                    // dispatch — agents keying on the stable code see
+                    // inconsistent outcomes for the same root cause.
+                    const remapped = await foldAndRemap({
+                        err,
+                        warnings: inputs.m38.warnings,
+                        client: inputs.client,
+                        boardId: inputs.boardId,
+                        columnIds: [inputs.m38.columnId],
+                        env: inputs.ctx.env,
+                        noCache: inputs.noCache,
+                        resolutionSource: remapSource,
+                    });
+                    // Same decoration shape as the JSON-bulk fail-fast path
+                    // (lines ~1334-1361 above). Preserves the existing error
+                    // class' fields and grafts `applied_count` / `applied_to`
+                    // / `failed_at_item` / `matched_count` onto `details`.
+                    const existing = remapped.details ?? {};
+                    const decoration = {
+                        ...existing,
+                        applied_count: appliedAssets.length,
+                        applied_to: appliedAssets.map((a) => a.itemId),
+                        failed_at_item: itemId,
+                        matched_count: inputs.matchedItemIds.length,
+                    };
+                    if (remapped.code === 'usage_error') {
+                        throw new UsageError(remapped.message, {
+                            ...(remapped.cause === undefined
+                                ? {}
+                                : { cause: remapped.cause }),
+                            details: decoration,
+                        });
+                    }
+                    throw new ApiError(remapped.code, remapped.message, {
+                        ...(remapped.cause === undefined
+                            ? {}
+                            : { cause: remapped.cause }),
+                        ...(remapped.httpStatus === undefined
+                            ? {}
+                            : { httpStatus: remapped.httpStatus }),
+                        ...(remapped.mondayCode === undefined
+                            ? {}
+                            : { mondayCode: remapped.mondayCode }),
+                        ...(remapped.requestId === undefined
+                            ? {}
+                            : { requestId: remapped.requestId }),
+                        retryable: remapped.retryable,
+                        ...(remapped.retryAfterSeconds === undefined
+                            ? {}
+                            : { retryAfterSeconds: remapped.retryAfterSeconds }),
+                        details: decoration,
+                    });
+                }
+                // Non-CliError programmer bug — re-throw to the runner's
+                // catch-all (surfaces as `internal_error` whole-call;
+                // mirrors the JSON-bulk fail-fast path). The partial-
+                // success invalidate above doesn't fire for this branch
+                // because non-CliError throws indicate broken contract,
+                // not partial-mutation state worth preserving.
+                throw err;
+            }
+        }
+        // Every item applied — single board-cache invalidate before emit
+        // (mirrors M38 single-leg invalidate timing).
+        await invalidateBoard(inputs.boardId, inputs.ctx.env);
+        const results = appliedAssets.map(({ itemId, asset }) => ({
+            item_id: itemId,
+            ok: true,
+            asset,
+        }));
+        const data = {
+            operation: 'item_update_bulk_file_set',
+            summary: {
+                matched_count: inputs.matchedItemIds.length,
+                applied_count: appliedAssets.length,
+                failed_count: 0,
+                board_id: inputs.boardId,
+                column_id: inputs.m38.columnId,
+                filename: precheck.filename,
+                file_size_bytes: precheck.fileSizeBytes,
+            },
+            results,
+        };
+        emitMutation({
+            ctx: inputs.ctx,
+            data,
+            schema: bulkFileSetDataSchema,
+            programOpts: inputs.programOpts,
+            warnings: combinedWarnings,
+            source: liveAgg.source,
+            cacheAgeSeconds: liveAgg.cacheAgeSeconds,
+            apiVersion: inputs.apiVersion,
+            resolvedIds,
+        });
+        return;
+    }
+    // `--continue-on-error` path. Per-item failures land as per-record
+    // `error: {code, message}` slots; the envelope is `ok: true`
+    // regardless of how many items failed (universal partial-success
+    // rule per cli-design §6.4). `internal_error` re-throws whole-call
+    // via the shared dispatcher's escape hatch — schema drift in the
+    // multipart response surfaces as top-level `ok: false`, not
+    // papered over as a per-record slot.
+    const assetById = new Map();
+    const perTargetDispatch = async ({ targetId, }) => {
+        try {
+            const result = await executeFileColumnSet({
+                client: inputs.client,
+                multipart: inputs.multipart,
+                itemId: targetId,
+                entry,
+                signal: inputs.ctx.signal,
+                retries: inputs.retries,
+            });
+            assetById.set(targetId, result.asset);
+        }
+        catch (err) {
+            if (err instanceof MondayCliError) {
+                // Codex IMPL R1 P1-1 fix: apply `foldAndRemap` BEFORE
+                // re-throwing into the shared dispatcher so per-record
+                // `error.code` carries the SAME `column_archived` stable
+                // code the JSON-bulk partial-success path emits. Mirrors
+                // `runPartialSuccessBulkUpdate`'s perTargetDispatch
+                // closure (src/api/partial-success-bulk.ts:431-475).
+                // `foldAndRemap` NEVER converts a non-`internal_error`
+                // into `internal_error`, so the dispatcher's
+                // `internal_error` re-throw escape hatch (M14 round-2 F1)
+                // stays intact: schema drift still surfaces as top-level
+                // `ok: false` rather than papered over as a per-record
+                // slot.
+                const remapped = await foldAndRemap({
+                    err,
+                    warnings: inputs.m38.warnings,
+                    client: inputs.client,
+                    boardId: inputs.boardId,
+                    columnIds: [inputs.m38.columnId],
+                    env: inputs.ctx.env,
+                    noCache: inputs.noCache,
+                    resolutionSource: remapSource,
+                });
+                throw remapped;
+            }
+            // Non-CliError — programmer bug. Re-throw through
+            // dispatchSequential / dispatchParallel's non-CliError
+            // branch so the runner's catch-all surfaces as
+            // internal_error (whole-call, not per-record).
+            throw err;
+        }
+    };
+    // Routing — `--concurrency > 1` routes through dispatchParallel
+    // (bounded async-pool); absent / `=== 1` routes through
+    // dispatchSequential. Both dispatchers thread the optional
+    // `signal` so SIGINT-aware callers see consistent cooperative-
+    // abort semantics (R-NEW-28 axis 6 — identical between routes).
+    let dispatchResults;
+    if (inputs.parsed.concurrency !== undefined &&
+        inputs.parsed.concurrency > 1) {
+        dispatchResults = await dispatchParallel(inputs.matchedItemIds, 'item_id', perTargetDispatch, inputs.parsed.concurrency, inputs.ctx.signal);
+    }
+    else {
+        dispatchResults = await dispatchSequential(inputs.matchedItemIds, 'item_id', perTargetDispatch, inputs.ctx.signal);
+    }
+    // Single post-dispatch invalidate. Fires even when every per-item
+    // dispatch failed (failed_count === matched_count) — wire calls
+    // still fired against Monday, so the metadata cache's view of the
+    // file column's content count may be stale even if the asset
+    // didn't land. Cheap to always fire; expensive if missed.
+    await invalidateBoard(inputs.boardId, inputs.ctx.env);
+    // Fold dispatcher results + side-map assets into the
+    // BulkFileSetResult[] shape. Mirrors `foldPartialSuccessBulkResult`
+    // (`src/api/partial-success-bulk.ts`) but with the file-dispatch's
+    // `asset` slot replacing the JSON path's `item` projection.
+    const results = dispatchResults.map((row) => {
+        const itemIdSlot = row.item_id;
+        /* c8 ignore next 8 — dispatcher contract: every result row
+           carries the id-field slot (populated by the dispatch helper);
+           this guard catches a contract violation that would surface as
+           a programmer bug, not a Monday-side failure. */
+        if (typeof itemIdSlot !== 'string' || itemIdSlot.length === 0) {
+            throw new ApiError('internal_error', 'bulk file dispatch result row is missing the `item_id` field — dispatcher contract violation.', { details: { record_keys: Object.keys(row) } });
+        }
+        if (row.ok) {
+            const asset = assetById.get(itemIdSlot);
+            /* c8 ignore next 8 — side-map invariant: every successful
+               per-target dispatch records the asset; this guard catches a
+               wrapper-layer miss (programmer bug). */
+            if (asset === undefined) {
+                throw new ApiError('internal_error', `bulk file dispatch result row for item_id ${itemIdSlot} reported ok: true but no Asset was captured — wrapper-layer side-map miss.`, { details: { item_id: itemIdSlot } });
+            }
+            return { item_id: itemIdSlot, ok: true, asset };
+        }
+        /* c8 ignore next 8 — dispatcher contract: every `ok: false` row
+           carries the `error` slot (populated by the shared dispatcher's
+           per-target error decoration). */
+        if (row.error === undefined) {
+            throw new ApiError('internal_error', `bulk file dispatch result row for item_id ${itemIdSlot} reported ok: false but no error payload was captured — dispatcher contract violation.`, { details: { item_id: itemIdSlot } });
+        }
+        return {
+            item_id: itemIdSlot,
+            ok: false,
+            error: { code: row.error.code, message: row.error.message },
+        };
+    });
+    const appliedCount = results.filter((r) => r.ok).length;
+    const failedCount = results.filter((r) => !r.ok).length;
+    /* c8 ignore next 11 — invariant: every matched item produces
+       exactly one result row (success or failure) under both
+       dispatchers; mismatch would indicate a programmer bug in the
+       dispatcher or the fold. Mirrors `buildPartialSuccessBulkSummary`'s
+       defensive check. */
+    if (appliedCount + failedCount !== inputs.matchedItemIds.length) {
+        throw new ApiError('internal_error', `bulk file dispatch summary invariant violated — matched_count (${String(inputs.matchedItemIds.length)}) !== applied_count (${String(appliedCount)}) + failed_count (${String(failedCount)}).`, {
+            details: {
+                matched_count: inputs.matchedItemIds.length,
+                applied_count: appliedCount,
+                failed_count: failedCount,
+                board_id: inputs.boardId,
+            },
+        });
+    }
+    const data = {
+        operation: 'item_update_bulk_file_set',
+        summary: {
+            matched_count: inputs.matchedItemIds.length,
+            applied_count: appliedCount,
+            failed_count: failedCount,
+            board_id: inputs.boardId,
+            column_id: inputs.m38.columnId,
+            filename: precheck.filename,
+            file_size_bytes: precheck.fileSizeBytes,
+        },
+        results,
+    };
+    emitMutation({
+        ctx: inputs.ctx,
+        data,
+        schema: bulkFileSetDataSchema,
+        programOpts: inputs.programOpts,
+        warnings: combinedWarnings,
+        source: liveAgg.source,
+        cacheAgeSeconds: liveAgg.cacheAgeSeconds,
+        apiVersion: inputs.apiVersion,
+        resolvedIds,
+    });
+};
 //# sourceMappingURL=update.js.map