monday-cli 0.3.0 → 0.4.0

package/dist/api/partial-success-bulk.d.ts

@@ -3,18 +3,20 @@
  * `item update --continue-on-error` flag (`cli-design.md` §6.4
  * "Bulk per-item partial-success" sub-section).
  *
- * **What this module owns.** A thin wrapper around
- * {@link dispatchSequential} from
- * `src/api/partial-success-mutation.ts` that drives the matched-
+ * **What this module owns.** A thin wrapper around the selected
+ * per-target dispatcher — {@link dispatchSequential} from
+ * `src/api/partial-success-mutation.ts` (default / M25 path) OR
+ * {@link dispatchParallel} from `src/api/parallel-dispatch.ts`
+ * (v0.4-M30 `--concurrency > 1` path) — that drives the matched-
  * item-ID list through one wire call per item, capturing per-
  * item failures into the result records rather than aborting
  * the loop. The wrapper sits BETWEEN the bulk command-action
  * orchestrator (`src/commands/item/update.ts:runBulk`) and the
- * shared `dispatchSequential` helper — the action body owns the
- * matched-item-walk + column-resolution pre-pass + confirmation
- * gate, then hands the resolved `SelectedMutation` + matched-
- * item IDs to this wrapper, which fans them out + projects the
- * partial-success envelope's `data.results[]` records.
+ * shared dispatcher — the action body owns the matched-item-
+ * walk + column-resolution pre-pass + confirmation gate, then
+ * hands the resolved `SelectedMutation` + matched-item IDs to
+ * this wrapper, which fans them out + projects the partial-
+ * success envelope's `data.results[]` records.
  *
  * **Why a separate module rather than folding into update.ts.**
  * Three reasons:
@@ -65,16 +67,31 @@
  * 3-consumer trigger: single-item + fail-fast bulk + M25
  * partial-success bulk).
  *
- * **Per-item dispatch wiring.** Runtime body loops
- * {@link dispatchSequential} over `matchedItemIds` with
- * id-field `'item_id'`. The per-item dispatch callback fires
- * one `executeItemMutation` call. Successes populate
- * `results[i].item` with the `ProjectedItem` via a side-map
- * fold; failures land in `results[i].error: {code, message}`
- * via `dispatchSequential`'s built-in error decoration.
- * `internal_error` codes re-throw as whole-call (M14 round-2
- * F1 precedent — schema-drift in the response MUST NOT be
- * papered over as a per-item failure).
+ * **v0.4-M30 extension.** Adds the `concurrency` input slot +
+ * the routing branch to {@link dispatchParallel} (new module
+ * `src/api/parallel-dispatch.ts` — runtime body landed at M30
+ * IMPL). When the caller passes `concurrency > 1`, the runtime
+ * fans out per-target dispatches via a bounded async-pool;
+ * absent or `concurrency === 1` preserves the M25 sequential
+ * path verbatim. The per-target dispatch closure is hoisted to
+ * a named local so both routes share the same
+ * `executeItemMutation` + `foldAndRemap` body — keeps the
+ * R-NEW-28 6-axis behavioral-equivalence audit straightforward.
+ * The M30 IMPL also threads an optional `signal?: AbortSignal`
+ * through both dispatchers (axis-6 scheduler short-circuit).
+ *
+ * **Per-item dispatch wiring.** Runtime body routes between
+ * {@link dispatchSequential} (default — `concurrency` absent /
+ * `=== 1`) and {@link dispatchParallel} (v0.4-M30 —
+ * `concurrency > 1`) over `matchedItemIds` with id-field
+ * `'item_id'`. The per-target dispatch callback (shared between
+ * routes verbatim) fires one `executeItemMutation` call.
+ * Successes populate `results[i].item` with the `ProjectedItem`
+ * via a side-map fold; failures land in
+ * `results[i].error: {code, message}` via the dispatcher's
+ * built-in error decoration. `internal_error` codes re-throw
+ * as whole-call (M14 round-2 F1 precedent — schema-drift in
+ * the response MUST NOT be papered over as a per-item failure).
  *
  * **`data.summary.failed_count` invariant.** The action body
  * derives `failed_count` from the result records
@@ -103,13 +120,15 @@ import type { EnvelopeSource } from './source-aggregator.js';
  * The `item` slot on success records is the §6.2 `ProjectedItem`
  * shape (same projection single-item `item update` emits as
  * `data`). The `error` slot on failure records carries
- * `{code, message}` populated from
- * `dispatchSequential`'s per-target error decoration.
+ * `{code, message}` populated from the selected dispatcher's
+ * per-target error decoration (`dispatchSequential` or
+ * `dispatchParallel` — same shape per the R-NEW-28 axis-1
+ * equivalence).
  *
- * `z.discriminatedUnion` would be the natural shape but
- * `dispatchSequential`'s result records carry a dynamic
- * id-field key (`{item_id: ..., ok, error?}`) — modelling that
- * as a per-record union complicates the schema and downstream
+ * `z.discriminatedUnion` would be the natural shape but the
+ * dispatchers' result records carry a dynamic id-field key
+ * (`{item_id: ..., ok, error?}`) — modelling that as a
+ * per-record union complicates the schema and downstream
  * consumers' type-narrowing. The flatter shape below carries
  * `item` + `error` as optionals; the action body's projection
  * + the wrapper's per-item dispatch enforce the
@@ -234,7 +253,9 @@ export type PartialSuccessBulkUpdateData = z.infer<typeof partialSuccessBulkUpda
  * applies — a stale-cache `validation_failed` remaps to the
  * stable `column_archived` code agents key off (cli-design
  * §6.5). The wrapper's per-item dispatch callback fires
- * `foldAndRemap` BEFORE throwing into `dispatchSequential` so
+ * `foldAndRemap` BEFORE throwing into the selected dispatcher
+ * (`dispatchSequential` or `dispatchParallel` — both apply
+ * the same per-target error decoration) so
  * the per-record `error.code` in `data.results[]` matches the
  * shape the fail-fast path would have surfaced as the
  * top-level `error.code`. That requires the same context the
@@ -283,15 +304,39 @@ export interface RunPartialSuccessBulkUpdateInputs {
     readonly env: NodeJS.ProcessEnv;
     readonly noCache: boolean;
     readonly resolutionSource: 'live' | 'cache' | 'mixed';
+    /**
+     * v0.4-M30 `--concurrency <N>` argv slot (cli-design §9.3 +
+     * §6.4 "Bulk per-item partial-success — Parallel dispatch").
+     * `undefined` or `1` routes through `dispatchSequential`
+     * (byte-equivalent to the v0.3-M25 path); `> 1` routes
+     * through {@link dispatchParallel} (bounded async-pool).
+     * Action layer's argv parser pins the value to
+     * `[MIN_CONCURRENCY, MAX_CONCURRENCY]` (1..32) before reaching
+     * this helper.
+     */
+    readonly concurrency: number | undefined;
+    /**
+     * v0.4-M30 SIGINT / abort threading. When the runner aborts
+     * `ctx.signal`, both dispatchers check `signal.aborted` at the
+     * iteration / worker-loop boundary and re-throw the signal's
+     * reason whole-call (mirrors {@link dispatchParallel} axis-6).
+     * In-flight wire calls abort via the existing
+     * `MondayClient.signal` configured at construction time
+     * (the client threads its signal into every fetch). Optional
+     * — omitting it preserves v0.3-M25 behaviour exactly for
+     * callers that don't need cooperative abort.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * Result returned by {@link runPartialSuccessBulkUpdate} to the
  * action layer.
  *
  * - `results` — the array of per-item records the helper built
- *   via `dispatchSequential` + the per-item projection
- *   callback. Direct mirror of `data.results[]` in the §6.4
- *   envelope. **Mutable array** so the action layer can pass
+ *   via the selected dispatcher (`dispatchSequential` or
+ *   `dispatchParallel`) + the per-item projection callback.
+ *   Direct mirror of `data.results[]` in the §6.4 envelope.
+ *   **Mutable array** so the action layer can pass
  *   it directly to `partialSuccessBulkUpdateDataSchema.parse`
  *   (zod's `z.array(...)` infers a mutable array — wrapping
  *   `readonly` would force a spread at the call site).
@@ -326,19 +371,24 @@ export declare const PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE: EnvelopeSource;
 /**
  * Drives the per-item dispatch loop under `--continue-on-error`.
  *
- * Implementation (M25 impl `78889df` refactor + this commit):
+ * Implementation (M25 impl `78889df` refactor + this commit;
+ * extended at v0.4-M30 pre-flight with the `concurrency` routing
+ * branch):
  *
- *   1. Loop {@link dispatchSequential} over `matchedItemIds`
- *      with id-field `'item_id'`.
+ *   1. Loop {@link dispatchSequential} (default / M25 path) OR
+ *      {@link dispatchParallel} (v0.4-M30 `--concurrency > 1`
+ *      path; runtime body landed at M30 IMPL) over
+ *      `matchedItemIds` with id-field `'item_id'`.
  *   2. Per-item dispatch callback fires
  *      {@link executeItemMutation} against the resolved
  *      `SelectedMutation`. On a {@link MondayCliError} catch,
  *      run {@link foldAndRemap} with `resolverWarnings` +
  *      `remapColumnIds` + `env` + `noCache` + `resolutionSource`
- *      from the inputs BEFORE re-throwing into
- *      `dispatchSequential`. This makes the per-record
- *      `error.code` in `data.results[]` carry the SAME stable
- *      code (`column_archived` after a stale-cache
+ *      from the inputs BEFORE re-throwing into the selected
+ *      dispatcher (`dispatchSequential` or `dispatchParallel`).
+ *      This makes the per-record `error.code` in
+ *      `data.results[]` carry the SAME stable code
+ *      (`column_archived` after a stale-cache
  *      `validation_failed` remap) that the v0.1 fail-fast
  *      path would have surfaced at the top level — Codex
  *      round-1 P1-1 contract requirement (cli-design §6.5
@@ -346,52 +396,60 @@ export declare const PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE: EnvelopeSource;
  *      fail-modes).
  *   3. On success, capture the `ProjectedItem` into a side
  *      map keyed by `item_id`.
- *   4. After the loop, walk the `dispatchSequential` results
- *      and fold the per-item `ProjectedItem` from the side
+ *   4. After the loop, walk the result rows (from whichever
+ *      dispatcher fired — `dispatchSequential` by default;
+ *      {@link dispatchParallel} when `concurrency > 1`) and
+ *      fold the per-item `ProjectedItem` from the side
  *      map into each `results[i].item` slot via
  *      {@link foldPartialSuccessBulkResult}. Failure records
  *      already carry `error: {code, message}` (with the
- *      foldAndRemap-applied code) via
- *      `dispatchSequential`'s built-in error decoration.
+ *      foldAndRemap-applied code) via the dispatcher's built-in
+ *      error decoration (both routes share the same per-target
+ *      error capture contract).
  *   5. Return `{results}` — the action layer folds the
  *      constant `'live'` dispatch source via
  *      `sourceAgg.record(PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE,
  *      null)` and emits the envelope.
  *
  * **`internal_error` re-throw escape hatch.** Per M14 round-2
- * F1 / round-3 F1, `dispatchSequential` re-throws
- * `internal_error` so schema-drift in the response surfaces
- * as whole-call (top-level `ok: false`) rather than per-record
- * — papering over `internal_error` would hide the malformed-
- * response signal agents need to know about. The M25 wrapper
- * inherits this behaviour by NOT wrapping the
- * `dispatchSequential` re-throw — `foldAndRemap` only ever
- * runs against {@link MondayCliError} instances, and it
- * NEVER converts a non-internal_error into internal_error,
- * so the re-throw path through dispatchSequential remains
- * the canonical schema-drift surface.
+ * F1 / round-3 F1, both dispatchers re-throw `internal_error`
+ * whole-call so schema-drift in the response surfaces as
+ * top-level `ok: false` rather than per-record — papering over
+ * `internal_error` would hide the malformed-response signal
+ * agents need to know about. The wrapper inherits this
+ * behaviour by NOT wrapping the dispatcher's re-throw —
+ * `foldAndRemap` only ever runs against {@link MondayCliError}
+ * instances, and it NEVER converts a non-internal_error into
+ * internal_error, so the re-throw path through the selected
+ * dispatcher remains the canonical schema-drift surface (axis
+ * 2 of the R-NEW-28 6-axis equivalence — identical between
+ * `dispatchSequential` and `dispatchParallel`).
  *
  * **Non-`MondayCliError` re-throw.** Programmer-bug exceptions
  * (TypeError, RangeError, etc.) raised by the executor or by
- * `foldAndRemap`'s refresh probe propagate through
- * `dispatchSequential`'s non-CliError re-throw branch unchanged,
- * surfacing as whole-call `internal_error` via the runner's
- * catch-all (mirrors M14's pattern at
- * `users-fan-out-mutation.ts` and the documented behaviour at
- * `partial-success-mutation.ts:93`).
+ * `foldAndRemap`'s refresh probe propagate through the selected
+ * dispatcher's non-CliError re-throw branch unchanged, surfacing
+ * as whole-call `internal_error` via the runner's catch-all
+ * (mirrors M14's pattern at `users-fan-out-mutation.ts` and the
+ * documented behaviour at `partial-success-mutation.ts` —
+ * R-NEW-28 axis 3, also identical across both routes).
  */
 export declare const runPartialSuccessBulkUpdate: (inputs: RunPartialSuccessBulkUpdateInputs) => Promise<RunPartialSuccessBulkUpdateResult>;
 /**
- * Pure helper — folds a `dispatchSequential` result row + a
- * `ProjectedItem` side-map entry into the partial-success-bulk
- * per-item record shape this module emits to the action layer.
+ * Pure helper — folds a per-target result row produced by the
+ * selected dispatcher (`dispatchSequential` or
+ * `dispatchParallel`) + a `ProjectedItem` side-map entry into
+ * the partial-success-bulk per-item record shape this module
+ * emits to the action layer. Both dispatchers populate the row
+ * with the same `{item_id, ok, error?}` shape (axis 1 of the
+ * R-NEW-28 6-axis equivalence) so the fold is route-agnostic.
  *
  * The helper is **shipped as a real implementation** (not a
  * stub) so the pre-flight Codex review can verify the
  * projection shape against the contract pinned in cli-design
  * §6.4 inline. M25 implementation reuses the helper unchanged.
  *
- * `record` is the row produced by `dispatchSequential` with
+ * `record` is the row produced by the selected dispatcher with
  * id-field `'item_id'` — carries `{item_id, ok, error?}` per
  * the partial-success contract. `projectedItem` is the
  * `ProjectedItem` the per-item dispatch callback captured on

package/dist/api/partial-success-bulk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"partial-success-bulk.d.ts","sourceRoot":"","sources":["../../src/api/partial-success-bulk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU/C,CAAC;AAEH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,oCAAoC,CAC5C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAS7C,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,kCAAkC,CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,EAAE,8BAA8B,EAAE,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,EAAE,cAAuB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,2BAA2B,GACtC,QAAQ,iCAAiC,KACxC,OAAO,CAAC,iCAAiC,CAgF3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,4BAA4B,GACvC,QAAQ,oBAAoB,EAC5B,eAAe,aAAa,GAAG,SAAS,KACvC,8BA4DF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,GAAI,qCAI5C;IACD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,8BAA8B,EAAE,CAAC;CAC7D,KAAG,4BAA4B,CAAC,SAAS,CAuBzC,CAAC"}
+{"version":3,"file":"partial-success-bulk.d.ts","sourceRoot":"","sources":["../../src/api/partial-success-bulk.ts"],"names":[],"mappings":"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"}

package/dist/api/partial-success-bulk.js

@@ -3,18 +3,20 @@
  * `item update --continue-on-error` flag (`cli-design.md` §6.4
  * "Bulk per-item partial-success" sub-section).
  *
- * **What this module owns.** A thin wrapper around
- * {@link dispatchSequential} from
- * `src/api/partial-success-mutation.ts` that drives the matched-
+ * **What this module owns.** A thin wrapper around the selected
+ * per-target dispatcher — {@link dispatchSequential} from
+ * `src/api/partial-success-mutation.ts` (default / M25 path) OR
+ * {@link dispatchParallel} from `src/api/parallel-dispatch.ts`
+ * (v0.4-M30 `--concurrency > 1` path) — that drives the matched-
  * item-ID list through one wire call per item, capturing per-
  * item failures into the result records rather than aborting
  * the loop. The wrapper sits BETWEEN the bulk command-action
  * orchestrator (`src/commands/item/update.ts:runBulk`) and the
- * shared `dispatchSequential` helper — the action body owns the
- * matched-item-walk + column-resolution pre-pass + confirmation
- * gate, then hands the resolved `SelectedMutation` + matched-
- * item IDs to this wrapper, which fans them out + projects the
- * partial-success envelope's `data.results[]` records.
+ * shared dispatcher — the action body owns the matched-item-
+ * walk + column-resolution pre-pass + confirmation gate, then
+ * hands the resolved `SelectedMutation` + matched-item IDs to
+ * this wrapper, which fans them out + projects the partial-
+ * success envelope's `data.results[]` records.
  *
  * **Why a separate module rather than folding into update.ts.**
  * Three reasons:
@@ -65,16 +67,31 @@
  * 3-consumer trigger: single-item + fail-fast bulk + M25
  * partial-success bulk).
  *
- * **Per-item dispatch wiring.** Runtime body loops
- * {@link dispatchSequential} over `matchedItemIds` with
- * id-field `'item_id'`. The per-item dispatch callback fires
- * one `executeItemMutation` call. Successes populate
- * `results[i].item` with the `ProjectedItem` via a side-map
- * fold; failures land in `results[i].error: {code, message}`
- * via `dispatchSequential`'s built-in error decoration.
- * `internal_error` codes re-throw as whole-call (M14 round-2
- * F1 precedent — schema-drift in the response MUST NOT be
- * papered over as a per-item failure).
+ * **v0.4-M30 extension.** Adds the `concurrency` input slot +
+ * the routing branch to {@link dispatchParallel} (new module
+ * `src/api/parallel-dispatch.ts` — runtime body landed at M30
+ * IMPL). When the caller passes `concurrency > 1`, the runtime
+ * fans out per-target dispatches via a bounded async-pool;
+ * absent or `concurrency === 1` preserves the M25 sequential
+ * path verbatim. The per-target dispatch closure is hoisted to
+ * a named local so both routes share the same
+ * `executeItemMutation` + `foldAndRemap` body — keeps the
+ * R-NEW-28 6-axis behavioral-equivalence audit straightforward.
+ * The M30 IMPL also threads an optional `signal?: AbortSignal`
+ * through both dispatchers (axis-6 scheduler short-circuit).
+ *
+ * **Per-item dispatch wiring.** Runtime body routes between
+ * {@link dispatchSequential} (default — `concurrency` absent /
+ * `=== 1`) and {@link dispatchParallel} (v0.4-M30 —
+ * `concurrency > 1`) over `matchedItemIds` with id-field
+ * `'item_id'`. The per-target dispatch callback (shared between
+ * routes verbatim) fires one `executeItemMutation` call.
+ * Successes populate `results[i].item` with the `ProjectedItem`
+ * via a side-map fold; failures land in
+ * `results[i].error: {code, message}` via the dispatcher's
+ * built-in error decoration. `internal_error` codes re-throw
+ * as whole-call (M14 round-2 F1 precedent — schema-drift in
+ * the response MUST NOT be papered over as a per-item failure).
  *
  * **`data.summary.failed_count` invariant.** The action body
  * derives `failed_count` from the result records
@@ -90,6 +107,7 @@ import { z } from 'zod';
 import { ApiError, MondayCliError } from '../utils/errors.js';
 import { projectedItemSchema } from './item-projection.js';
 import { dispatchSequential, } from './partial-success-mutation.js';
+import { dispatchParallel } from './parallel-dispatch.js';
 import { executeItemMutation } from './item-mutation-execute.js';
 import { foldAndRemap } from './resolver-error-fold.js';
 /**
@@ -102,13 +120,15 @@ import { foldAndRemap } from './resolver-error-fold.js';
  * The `item` slot on success records is the §6.2 `ProjectedItem`
  * shape (same projection single-item `item update` emits as
  * `data`). The `error` slot on failure records carries
- * `{code, message}` populated from
- * `dispatchSequential`'s per-target error decoration.
+ * `{code, message}` populated from the selected dispatcher's
+ * per-target error decoration (`dispatchSequential` or
+ * `dispatchParallel` — same shape per the R-NEW-28 axis-1
+ * equivalence).
  *
- * `z.discriminatedUnion` would be the natural shape but
- * `dispatchSequential`'s result records carry a dynamic
- * id-field key (`{item_id: ..., ok, error?}`) — modelling that
- * as a per-record union complicates the schema and downstream
+ * `z.discriminatedUnion` would be the natural shape but the
+ * dispatchers' result records carry a dynamic id-field key
+ * (`{item_id: ..., ok, error?}`) — modelling that as a
+ * per-record union complicates the schema and downstream
  * consumers' type-narrowing. The flatter shape below carries
  * `item` + `error` as optionals; the action body's projection
  * + the wrapper's per-item dispatch enforce the
@@ -160,19 +180,24 @@ export const PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE = 'live';
 /**
  * Drives the per-item dispatch loop under `--continue-on-error`.
  *
- * Implementation (M25 impl `78889df` refactor + this commit):
+ * Implementation (M25 impl `78889df` refactor + this commit;
+ * extended at v0.4-M30 pre-flight with the `concurrency` routing
+ * branch):
  *
- *   1. Loop {@link dispatchSequential} over `matchedItemIds`
- *      with id-field `'item_id'`.
+ *   1. Loop {@link dispatchSequential} (default / M25 path) OR
+ *      {@link dispatchParallel} (v0.4-M30 `--concurrency > 1`
+ *      path; runtime body landed at M30 IMPL) over
+ *      `matchedItemIds` with id-field `'item_id'`.
  *   2. Per-item dispatch callback fires
  *      {@link executeItemMutation} against the resolved
  *      `SelectedMutation`. On a {@link MondayCliError} catch,
  *      run {@link foldAndRemap} with `resolverWarnings` +
  *      `remapColumnIds` + `env` + `noCache` + `resolutionSource`
- *      from the inputs BEFORE re-throwing into
- *      `dispatchSequential`. This makes the per-record
- *      `error.code` in `data.results[]` carry the SAME stable
- *      code (`column_archived` after a stale-cache
+ *      from the inputs BEFORE re-throwing into the selected
+ *      dispatcher (`dispatchSequential` or `dispatchParallel`).
+ *      This makes the per-record `error.code` in
+ *      `data.results[]` carry the SAME stable code
+ *      (`column_archived` after a stale-cache
  *      `validation_failed` remap) that the v0.1 fail-fast
  *      path would have surfaced at the top level — Codex
  *      round-1 P1-1 contract requirement (cli-design §6.5
@@ -180,44 +205,57 @@ export const PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE = 'live';
  *      fail-modes).
  *   3. On success, capture the `ProjectedItem` into a side
  *      map keyed by `item_id`.
- *   4. After the loop, walk the `dispatchSequential` results
- *      and fold the per-item `ProjectedItem` from the side
+ *   4. After the loop, walk the result rows (from whichever
+ *      dispatcher fired — `dispatchSequential` by default;
+ *      {@link dispatchParallel} when `concurrency > 1`) and
+ *      fold the per-item `ProjectedItem` from the side
  *      map into each `results[i].item` slot via
  *      {@link foldPartialSuccessBulkResult}. Failure records
  *      already carry `error: {code, message}` (with the
- *      foldAndRemap-applied code) via
- *      `dispatchSequential`'s built-in error decoration.
+ *      foldAndRemap-applied code) via the dispatcher's built-in
+ *      error decoration (both routes share the same per-target
+ *      error capture contract).
  *   5. Return `{results}` — the action layer folds the
  *      constant `'live'` dispatch source via
  *      `sourceAgg.record(PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE,
  *      null)` and emits the envelope.
  *
  * **`internal_error` re-throw escape hatch.** Per M14 round-2
- * F1 / round-3 F1, `dispatchSequential` re-throws
- * `internal_error` so schema-drift in the response surfaces
- * as whole-call (top-level `ok: false`) rather than per-record
- * — papering over `internal_error` would hide the malformed-
- * response signal agents need to know about. The M25 wrapper
- * inherits this behaviour by NOT wrapping the
- * `dispatchSequential` re-throw — `foldAndRemap` only ever
- * runs against {@link MondayCliError} instances, and it
- * NEVER converts a non-internal_error into internal_error,
- * so the re-throw path through dispatchSequential remains
- * the canonical schema-drift surface.
+ * F1 / round-3 F1, both dispatchers re-throw `internal_error`
+ * whole-call so schema-drift in the response surfaces as
+ * top-level `ok: false` rather than per-record — papering over
+ * `internal_error` would hide the malformed-response signal
+ * agents need to know about. The wrapper inherits this
+ * behaviour by NOT wrapping the dispatcher's re-throw —
+ * `foldAndRemap` only ever runs against {@link MondayCliError}
+ * instances, and it NEVER converts a non-internal_error into
+ * internal_error, so the re-throw path through the selected
+ * dispatcher remains the canonical schema-drift surface (axis
+ * 2 of the R-NEW-28 6-axis equivalence — identical between
+ * `dispatchSequential` and `dispatchParallel`).
  *
  * **Non-`MondayCliError` re-throw.** Programmer-bug exceptions
  * (TypeError, RangeError, etc.) raised by the executor or by
- * `foldAndRemap`'s refresh probe propagate through
- * `dispatchSequential`'s non-CliError re-throw branch unchanged,
- * surfacing as whole-call `internal_error` via the runner's
- * catch-all (mirrors M14's pattern at
- * `users-fan-out-mutation.ts` and the documented behaviour at
- * `partial-success-mutation.ts:93`).
+ * `foldAndRemap`'s refresh probe propagate through the selected
+ * dispatcher's non-CliError re-throw branch unchanged, surfacing
+ * as whole-call `internal_error` via the runner's catch-all
+ * (mirrors M14's pattern at `users-fan-out-mutation.ts` and the
+ * documented behaviour at `partial-success-mutation.ts` —
+ * R-NEW-28 axis 3, also identical across both routes).
  */
 export const runPartialSuccessBulkUpdate = async (inputs) => {
-    const { client, boardId, matchedItemIds, mutation, createLabelsIfMissing, resolverWarnings, remapColumnIds, env, noCache, resolutionSource, } = inputs;
+    const { client, boardId, matchedItemIds, mutation, createLabelsIfMissing, resolverWarnings, remapColumnIds, env, noCache, resolutionSource, concurrency, signal, } = inputs;
     const projectedById = new Map();
-    const dispatchResults = await dispatchSequential(matchedItemIds, 'item_id', async ({ targetId }) => {
+    // Per-target dispatch closure shared between the sequential
+    // (v0.3-M25 default) and parallel (v0.4-M30 `--concurrency > 1`)
+    // routes. Both dispatch helpers contract on the same
+    // {@link DispatchOneTargetInputs}-shaped callback so the closure
+    // body is byte-equivalent across routes — only the OUTER call
+    // (dispatchSequential vs dispatchParallel) changes. This keeps the
+    // R-NEW-28 6-axis behavioral-equivalence audit straightforward:
+    // every per-target outcome (success projection capture; `MondayCliError`
+    // foldAndRemap + re-throw; non-CliError re-throw) is shared verbatim.
+    const perTargetDispatch = async ({ targetId }) => {
         try {
             const result = await executeItemMutation(client, {
                 mutation,
@@ -238,9 +276,9 @@ export const runPartialSuccessBulkUpdate = async (inputs) => {
                 // even though the v0.1 path surfaces `column_archived`
                 // for the same root cause (cli-design §6.5 stable-
                 // code rule). foldAndRemap NEVER converts a non-
-                // internal_error into internal_error, so
-                // dispatchSequential's internal_error re-throw escape
-                // hatch (M14 round-2 F1) stays intact.
+                // internal_error into internal_error, so the selected
+                // dispatcher's internal_error re-throw escape hatch
+                // (M14 round-2 F1) stays intact across both routes.
                 const remapped = await foldAndRemap({
                     err,
                     warnings: resolverWarnings,
@@ -254,18 +292,33 @@ export const runPartialSuccessBulkUpdate = async (inputs) => {
                 throw remapped;
             }
             // Non-MondayCliError — programmer bug. Re-throw through
-            // dispatchSequential's non-CliError branch so the runner's
-            // catch-all surfaces it as internal_error (whole-call,
-            // not per-record). Mirrors users-fan-out-mutation.ts
-            // and is the documented dispatchSequential contract.
+            // dispatchSequential / dispatchParallel's non-CliError branch
+            // so the runner's catch-all surfaces it as internal_error
+            // (whole-call, not per-record). Mirrors users-fan-out-mutation.ts
+            // and is the documented partial-success contract.
             throw err;
         }
-    });
+    };
+    // v0.4-M30 routing: `--concurrency <N>` with N > 1 routes through
+    // {@link dispatchParallel} (bounded async-pool); absent / N === 1
+    // routes through the unchanged {@link dispatchSequential} path.
+    // Both dispatchers thread the optional `signal` so SIGINT-aware
+    // callers see consistent cooperative abort semantics across routes
+    // (R-NEW-28 axis 6).
+    let dispatchResults;
+    if (concurrency !== undefined && concurrency > 1) {
+        dispatchResults = await dispatchParallel(matchedItemIds, 'item_id', perTargetDispatch, concurrency, signal);
+    }
+    else {
+        dispatchResults = await dispatchSequential(matchedItemIds, 'item_id', perTargetDispatch, signal);
+    }
     const results = dispatchResults.map((row) => {
         // Side-map lookup requires the item_id string from the row;
         // foldPartialSuccessBulkResult also enforces the same
         // invariant + throws internal_error if the id-field is
-        // missing or non-string (dispatchSequential contract).
+        // missing or non-string (both dispatchers populate the
+        // id-field slot for every result row per the partial-
+        // success contract).
         const itemIdSlot = row.item_id;
         const projected = typeof itemIdSlot === 'string'
             ? projectedById.get(itemIdSlot)
@@ -275,16 +328,20 @@ export const runPartialSuccessBulkUpdate = async (inputs) => {
     return { results };
 };
 /**
- * Pure helper — folds a `dispatchSequential` result row + a
- * `ProjectedItem` side-map entry into the partial-success-bulk
- * per-item record shape this module emits to the action layer.
+ * Pure helper — folds a per-target result row produced by the
+ * selected dispatcher (`dispatchSequential` or
+ * `dispatchParallel`) + a `ProjectedItem` side-map entry into
+ * the partial-success-bulk per-item record shape this module
+ * emits to the action layer. Both dispatchers populate the row
+ * with the same `{item_id, ok, error?}` shape (axis 1 of the
+ * R-NEW-28 6-axis equivalence) so the fold is route-agnostic.
  *
  * The helper is **shipped as a real implementation** (not a
  * stub) so the pre-flight Codex review can verify the
  * projection shape against the contract pinned in cli-design
  * §6.4 inline. M25 implementation reuses the helper unchanged.
  *
- * `record` is the row produced by `dispatchSequential` with
+ * `record` is the row produced by the selected dispatcher with
  * id-field `'item_id'` — carries `{item_id, ok, error?}` per
  * the partial-success contract. `projectedItem` is the
  * `ProjectedItem` the per-item dispatch callback captured on
@@ -297,16 +354,17 @@ export const runPartialSuccessBulkUpdate = async (inputs) => {
  * records never carry `item`.
  */
 export const foldPartialSuccessBulkResult = (record, projectedItem) => {
-    // Dot-access: `dispatchSequential` builds the record with
-    // the dynamic id-field key (`'item_id'`) carrying the target
-    // ID. The dot-access narrows the unknown index-signature
-    // value to a string via the runtime guard below; the helper
-    // throws `internal_error` if the shape doesn't match (which
-    // would be a programmer bug — `dispatchSequential`'s contract
-    // is to populate the id-field slot for every result row).
+    // Dot-access: the selected dispatcher (`dispatchSequential` or
+    // `dispatchParallel`) builds the record with the dynamic
+    // id-field key (`'item_id'`) carrying the target ID. The
+    // dot-access narrows the unknown index-signature value to a
+    // string via the runtime guard below; the helper throws
+    // `internal_error` if the shape doesn't match (which would be
+    // a programmer bug — both dispatchers contract on populating
+    // the id-field slot for every result row).
     const itemIdSlot = record.item_id;
     if (typeof itemIdSlot !== 'string' || itemIdSlot.length === 0) {
-        throw new ApiError('internal_error', 'partial-success bulk result row is missing the `item_id` field — dispatchSequential contract violation.', {
+        throw new ApiError('internal_error', 'partial-success bulk result row is missing the `item_id` field — dispatcher contract violation.', {
             details: {
                 record_keys: Object.keys(record),
             },
@@ -326,11 +384,11 @@ export const foldPartialSuccessBulkResult = (record, projectedItem) => {
             item: projectedItem,
         };
     }
-    // Failure path — `dispatchSequential` populates `error` on
-    // every non-`ok` row; the schema's `.optional()` declarations
-    // narrow defensively here.
+    // Failure path — both dispatchers populate `error` on every
+    // non-`ok` row (R-NEW-28 axis 1); the schema's `.optional()`
+    // declarations narrow defensively here.
     if (record.error === undefined) {
-        throw new ApiError('internal_error', `partial-success bulk result row for item_id ${itemIdSlot} reported ok: false but no error payload was captured — dispatchSequential contract violation.`, {
+        throw new ApiError('internal_error', `partial-success bulk result row for item_id ${itemIdSlot} reported ok: false but no error payload was captured — dispatcher contract violation.`, {
             details: {
                 item_id: itemIdSlot,
             },