@@ -0,0 +1,18 @@
+---
+'@object-ui/types': minor
+'@object-ui/core': minor
+'@object-ui/data-objectstack': minor
+'@object-ui/plugin-grid': minor
+---
+
+Clause-②: yes
+Metadata-protocol: none
+
+A list bulk action keeps each failed record's id and the server's reason, and a bulk run refreshes the bound list once instead of once per row (objectui#13442).
+
+A 100-row bulk update took about 100 s in the console for about 19 s of server work. `bulkUpdate` read only the server's `succeeded` count, so a partial failure reached the result dialog and the error CSV as one `batch_0: N records failed` entry with no record id or reason. Apps that needed the reason ran `batchSize: 1`, and on that per-row path every write refetched and re-rendered the whole list.
+
+- `DataSource.bulkUpdate` / `bulkDelete` (`@object-ui/types`) may now resolve to a `BulkWriteResult`, `{ succeeded, errors: [{ id, error }] }`, as well as to a plain count. Both new types are exported. An adapter that returns a number keeps working unchanged. A caller that reads the result must now handle both shapes; the bulk executor does.
+- `ObjectStackAdapter.bulkUpdate` / `bulkDelete` (`@object-ui/data-objectstack`) resolve to a `BulkWriteResult` built from the `results[].errors[]` that `updateMany` / `deleteMany` already answer, and the per-id fallback loop keeps each row's reason instead of discarding it. Breaking for direct callers: these two methods used to resolve to a number. Code that calls them directly and reads the result as a count must read `.succeeded`.
+- `executeBulkBatch` (`@object-ui/core`) reports each failure the bulk call names under its own id and reason. Only failures it does not name still fold into one `batch_${offset}` entry. So the result dialog, the error CSV and Retry work per record whatever the `batchSize`, and Undo skips the failed rows.
+- New optional `DataSource.batchMutationEvents(work)`: runs `work` with `onMutation` events held, then delivers them when it settles, one per resource and mutation type. `ObjectStackAdapter` implements it. `useBulkExecutor` (`@object-ui/plugin-grid`) runs each bulk run and each undo inside it, so ListView, ObjectView, kanban, calendar and the console's invalidation bridge refetch once per run, not once per row. The executor's `dataSource` face gains the matching optional member.
@@ -178,6 +178,40 @@ await dataSource.find('users', {
 
 Data-aware plugins may also use optional methods such as `batchTransaction`, `bulkUpdate`, `bulkDelete`, `getView`, or `listViewOverrides` when an adapter supports them. Keep the required CRUD methods implemented first, then add optional capabilities as your UI needs them.
 
+### Bulk writes: per-record results and one refresh per run
+
+`bulkUpdate` and `bulkDelete` resolve to either a plain count or a `BulkWriteResult`: the count plus one `{ id, error }` entry per record the server refused, with the server's reason. An adapter whose server reports per-row outcomes should return the `BulkWriteResult` (the `@object-ui/data-objectstack` adapter does, from the `results[].errors[]` of `updateMany` / `deleteMany`). An adapter that has only a count keeps returning the number. A caller handles both:
+
+```typescript
+import type { DataSource } from '@object-ui/types';
+
+declare const dataSource: DataSource;
+
+const res = await dataSource.bulkUpdate?.('order', ['o1', 'o2', 'o3'], { status: 'closed' });
+if (typeof res === 'number') {
+  console.log(`${res} updated`);
+} else if (res) {
+  console.log(`${res.succeeded} updated`);
+  for (const { id, error } of res.errors) console.warn(`${id}: ${error}`);
+}
+```
+
+The grid's bulk actions read both shapes. A refused record shows up in the result dialog and the error CSV under its own id and reason, and **Retry** works on it, whatever the action's `batchSize`.
+
+Every `create` / `update` / `delete` normally fires one `onMutation` event, and every bound view refetches once per event. A loop that writes many rows (a bulk action on its per-row path, an undo) would refetch the list once per row. Wrap such a loop in the optional `batchMutationEvents(work)`: the events its writes fire are held and delivered when `work` settles, one per touched resource and mutation type, so bound views refresh once. The grid's bulk executor does this when the adapter has the method.
+
+```typescript
+import type { DataSource } from '@object-ui/types';
+
+declare const dataSource: DataSource;
+
+const ids = ['o1', 'o2', 'o3'];
+const write = async () => {
+  for (const id of ids) await dataSource.update('order', id, { status: 'closed' });
+};
+await (dataSource.batchMutationEvents ? dataSource.batchMutationEvents(write) : write());
+```
+
 `listMetadataItems(type)` lists one metadata registry type as `{ name, label }` headers, for the `position-ref` / `permission-ref` field widgets (see the [Fields guide](./fields.md)). An empty array means the registry has no item of that type, so a failed load must **reject**, never resolve `[]`.
 
 ### Cross-object atomic writes (`batchTransaction`)
 
@@ -94,3 +94,93 @@ describe('executeBulkBatch', () => {
     expect(out.errors[0].id).toBe('batch_200');
   });
 });
+
+/**
+ * objectui#13442 — a bulk call that names its failed rows (`BulkWriteResult`,
+ * what `DataSource.bulkUpdate` / `bulkDelete` may resolve to) keeps each one
+ * under its own id and the server's reason. Before, every shortfall became one
+ * `batch_${offset}` entry, so Retry and the error CSV had no record to act on.
+ */
+describe('executeBulkBatch — per-record results from the bulk call (objectui#13442)', () => {
+  const five = { ids: ['r1', 'r2', 'r3', 'r4', 'r5'], originalSize: 5, offset: 0, allowBulk: true, label: 'bulk update' };
+
+  it('reports each failure the call named under its own id, with no aggregate entry', async () => {
+    const bulkCall = vi.fn(async () => ({
+      succeeded: 3,
+      errors: [
+        { id: 'r2', error: 'Discharge date is required' },
+        { id: 'r4', error: 'Record is locked' },
+      ],
+    }));
+    const perRow = vi.fn();
+    const out = await executeBulkBatch(five, { bulkCall, perRow });
+    expect(out).toEqual({
+      succeeded: 3,
+      failed: 2,
+      errors: [
+        { id: 'r2', error: 'Discharge date is required' },
+        { id: 'r4', error: 'Record is locked' },
+      ],
+    });
+    // The server already applied the request: no per-row re-run.
+    expect(perRow).not.toHaveBeenCalled();
+  });
+
+  it('folds only the failures the call did NOT name into the aggregate entry', async () => {
+    const out = await executeBulkBatch(five, {
+      bulkCall: async () => ({ succeeded: 2, errors: [{ id: 'r5', error: 'Denied by sharing rule' }] }),
+      perRow: vi.fn(),
+    });
+    expect(out.succeeded).toBe(2);
+    expect(out.failed).toBe(3);
+    expect(out.errors).toEqual([
+      { id: 'r5', error: 'Denied by sharing rule' },
+      { id: 'batch_0', error: '2 records failed in bulk update' },
+    ]);
+  });
+
+  it('ignores an entry for an id outside the batch, and a repeated id', async () => {
+    const out = await executeBulkBatch(five, {
+      bulkCall: async () => ({
+        succeeded: 3,
+        errors: [
+          { id: 'not_in_batch', error: 'x' },
+          { id: 'r1', error: 'first' },
+          { id: 'r1', error: 'again' },
+        ],
+      }),
+      perRow: vi.fn(),
+    });
+    expect(out.failed).toBe(2);
+    expect(out.errors).toEqual([
+      { id: 'r1', error: 'first' },
+      { id: 'batch_0', error: '1 record failed in bulk update' },
+    ]);
+  });
+
+  it('never lists more entries than the reported shortfall', async () => {
+    const out = await executeBulkBatch(five, {
+      bulkCall: async () => ({
+        succeeded: 4,
+        errors: [
+          { id: 'r2', error: 'a' },
+          { id: 'r3', error: 'b' },
+        ],
+      }),
+      perRow: vi.fn(),
+    });
+    expect(out.failed).toBe(1);
+    expect(out.errors).toEqual([{ id: 'r2', error: 'a' }]);
+  });
+
+  it('a full success reports no entries, and a plain count still works as before', async () => {
+    const full = await executeBulkBatch(five, {
+      bulkCall: async () => ({ succeeded: 5, errors: [] }),
+      perRow: vi.fn(),
+    });
+    expect(full).toEqual({ succeeded: 5, failed: 0, errors: [] });
+
+    const count = await executeBulkBatch(five, { bulkCall: async () => 4, perRow: vi.fn() });
+    expect(count.errors).toEqual([{ id: 'batch_0', error: '1 record failed in bulk update' }]);
+  });
+});
@@ -6,6 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type { BulkWriteResult } from '@object-ui/types';
+
 /**
  * Outcome of a single batch execution. Mirrors the fields callers care
  * about so they can fold these into their own aggregate result.
@@ -25,11 +27,13 @@ export interface BulkBatchOutcome {
 export interface BulkBatchOps {
   /**
    * One server call that mutates every id in the batch with the same
-   * shape. Returns the count of rows the server reports as succeeded.
-   * Throws when the entire request fails (network, 500, auth) — that
-   * signals "fall back to per-row" upstream.
+   * shape. Resolves to the count of rows the server reports as succeeded,
+   * or to a {@link BulkWriteResult} that also names each failed id and the
+   * server's reason (objectui#13442) — what `DataSource.bulkUpdate` /
+   * `bulkDelete` resolve to. Throws when the entire request fails (network,
+   * 500, auth) — that signals "fall back to per-row" upstream.
    */
-  bulkCall?: (ids: string[]) => Promise<number>;
+  bulkCall?: (ids: string[]) => Promise<number | BulkWriteResult>;
   /**
    * Per-row mutation. Called once per id in the batch when bulk is
    * unavailable, when bulk throws, or when the batch is too small for
@@ -73,10 +77,14 @@ export interface BulkBatchInput {
  *
  * Decision tree:
  * 1. `allowBulk` AND `ops.bulkCall` provided → call it.
- *    - returned `n === ids.length` → all good, no per-row pass.
- *    - returned `n < ids.length`   → aggregate error for the shortfall,
- *      no per-row pass (the server already accepted the request; calling
- *      per-row would re-mutate the rows that already succeeded).
+ *    - succeeded `=== ids.length`  → all good, no per-row pass.
+ *    - succeeded `< ids.length`    → the shortfall is reported, with no
+ *      per-row pass (the server already accepted the request; calling
+ *      per-row would re-mutate the rows that already succeeded). Each
+ *      failed row the call named in its `errors` gets its own entry, under
+ *      its own id and the server's reason (objectui#13442), so Retry and the
+ *      error CSV work per record. Only failures it did NOT name — a plain
+ *      count names none — fold into one `batch_${offset}` aggregate entry.
  *    - threw                       → fall through to per-row to recover
  *      actionable per-id error detail for the user.
  * 2. Otherwise → per-row via Promise.allSettled.
@@ -91,25 +99,51 @@ export async function executeBulkBatch(
   const outcome: BulkBatchOutcome = { succeeded: 0, failed: 0, errors: [] };
 
   if (allowBulk && typeof ops.bulkCall === 'function') {
+    let res: number | BulkWriteResult;
     try {
-      const n = await ops.bulkCall(ids);
-      const bulkSucceeded = Math.max(0, Math.min(n, ids.length));
-      outcome.succeeded += bulkSucceeded;
-      const bulkFailed = ids.length - bulkSucceeded;
-      if (bulkFailed > 0) {
-        outcome.failed += bulkFailed;
+      res = await ops.bulkCall(ids);
+    } catch {
+      // Fall through to per-row — gives the user actionable detail.
+      return runPerRow(ids, ops.perRow, outcome);
+    }
+    const reported = typeof res === 'number' ? res : res.succeeded;
+    const bulkSucceeded = Math.max(0, Math.min(reported, ids.length));
+    outcome.succeeded += bulkSucceeded;
+    const bulkFailed = ids.length - bulkSucceeded;
+    if (bulkFailed > 0) {
+      outcome.failed += bulkFailed;
+      // Per-record entries for the failures the call named — one per id,
+      // only ids of THIS batch, and never more than the shortfall, so the
+      // entries always add up to `failed`.
+      const inBatch = new Set(ids);
+      const attributed = new Set<string>();
+      for (const rowError of typeof res === 'number' ? [] : res.errors) {
+        if (attributed.size >= bulkFailed) break;
+        if (!inBatch.has(rowError.id) || attributed.has(rowError.id)) continue;
+        attributed.add(rowError.id);
+        outcome.errors.push({ id: rowError.id, error: rowError.error });
+      }
+      const unattributed = bulkFailed - attributed.size;
+      if (unattributed > 0) {
         outcome.errors.push({
           id: `batch_${offset}`,
-          error: `${bulkFailed} record${bulkFailed === 1 ? '' : 's'} failed in ${label}`,
+          error: `${unattributed} record${unattributed === 1 ? '' : 's'} failed in ${label}`,
         });
       }
-      return outcome;
-    } catch {
-      // Fall through to per-row — gives the user actionable detail.
     }
+    return outcome;
   }
 
-  const settled = await Promise.allSettled(ids.map((id) => ops.perRow(id)));
+  return runPerRow(ids, ops.perRow, outcome);
+}
+
+/** The per-row pass: every id through `perRow`, each failure under its own id. */
+async function runPerRow(
+  ids: string[],
+  perRow: BulkBatchOps['perRow'],
+  outcome: BulkBatchOutcome,
+): Promise<BulkBatchOutcome> {
+  const settled = await Promise.allSettled(ids.map((id) => perRow(id)));
   settled.forEach((res, idx) => {
     if (res.status === 'fulfilled') {
       outcome.succeeded += 1;
 
@@ -1123,6 +1123,9 @@ new ObjectStackAdapter(config: {
 - `update(resource, id, data)` - Update an existing record
 - `delete(resource, id)` - Delete a record
 - `bulk(resource, operation, data)` - Batch operations (create/update/delete)
+- `bulkUpdate(resource, ids, patch)` / `bulkDelete(resource, ids)` - One `updateMany` / `deleteMany` request for many ids (`continueOnError: true`). Resolves to `{ succeeded, errors }`: the server's count plus one `{ id, error }` per refused record, with the server's reason
+- `onMutation(listener)` - Subscribe to create/update/delete events (returns unsubscribe function)
+- `batchMutationEvents(work)` - Run `work` with mutation events held, then deliver them coalesced (one per resource and type) when it settles, so bound views refresh once for a loop of writes
 - `batchTransaction(operations)` - Cross-object atomic batch (master-detail); atomic when the backend advertises `transactionalBatch`, else non-atomic client-side fallback
 - `getObjectSchema(objectName)` - Get schema metadata (cached)
 - `getCacheStats()` - Get cache statistics
 
@@ -27,41 +27,41 @@ function makeDS(stub: { deleteMany?: any; delete?: any }) {
 }
 
 describe('ObjectStackDataSource.bulkDelete', () => {
-  it('returns 0 and skips network when ids is empty', async () => {
+  it('returns a zero result and skips network when ids is empty', async () => {
     const deleteMany = vi.fn();
     const ds = makeDS({ deleteMany });
-    const n = await ds.bulkDelete('sys_notification', []);
-    expect(n).toBe(0);
+    const res = await ds.bulkDelete('sys_notification', []);
+    expect(res).toEqual({ succeeded: 0, errors: [] });
     expect(deleteMany).not.toHaveBeenCalled();
   });
 
   it('issues a single deleteMany call with the id list', async () => {
     const deleteMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0 });
     const ds = makeDS({ deleteMany });
-    const n = await ds.bulkDelete('task', ['a', 'b', 'c']);
-    expect(n).toBe(3);
+    const res = await ds.bulkDelete('task', ['a', 'b', 'c']);
+    expect(res).toEqual({ succeeded: 3, errors: [] });
     expect(deleteMany).toHaveBeenCalledTimes(1);
     const [resource, ids, opts] = deleteMany.mock.calls[0];
     expect(resource).toBe('task');
     expect(ids).toEqual(['a', 'b', 'c']);
     expect(opts).toEqual({ continueOnError: true });
   });
 
-  it('returns ids.length when deleteMany returns void (older clients)', async () => {
+  it('reads every id as deleted when deleteMany returns void (older clients)', async () => {
     const deleteMany = vi.fn().mockResolvedValue(undefined);
     const ds = makeDS({ deleteMany });
-    const n = await ds.bulkDelete('task', ['a', 'b']);
-    expect(n).toBe(2);
+    const res = await ds.bulkDelete('task', ['a', 'b']);
+    expect(res).toEqual({ succeeded: 2, errors: [] });
   });
 
   it('falls back to per-id delete loop when deleteMany is missing', async () => {
     const del = vi.fn(async (_: string, id: string) => {
       if (id === 'b') throw new Error('FK violation');
     });
     const ds = makeDS({ delete: del });
-    const n = await ds.bulkDelete('task', ['a', 'b', 'c']);
-    // continueOnError-emulated: b throws, a + c succeed.
-    expect(n).toBe(2);
+    const res = await ds.bulkDelete('task', ['a', 'b', 'c']);
+    // continueOnError-emulated: b throws, a + c succeed, b keeps its reason.
+    expect(res).toEqual({ succeeded: 2, errors: [{ id: 'b', error: 'FK violation' }] });
     expect(del).toHaveBeenCalledTimes(3);
   });