feat(spec,automation): declare bulk intent on update_record / delete_record (#5393) (#5485)

`UpdateRecordConfigSchema` / `DeleteRecordConfigSchema` are strictObjects and
neither declared any spelling of bulk intent, while the CRUD executors never
passed `options.multi`. The data engine accepts a write only when `where.id` is
a scalar or `options.multi` is truthy and throws otherwise, so a predicate
update/delete was unreachable from any flow in any app — while the node
descriptors advertised "Delete records matching a filter." Declared != enforced
(PD #10); #5225's showcase sweep flow was the site it surfaced at.

Adds `multi` (boolean, default false) to both config contracts and wires the
executors to forward it as `options.multi`. One name for one concept (PD #12):
`multi` is the engine's own word for it, so the concept is greppable from node
config to driver call. The engine's rejection path is untouched — refusing an
undeclared predicate write IS the contract.

- spec: `multi` on both schemas, with `bulk`/`all`/`multiple` prescriptions and
  a wrong-layer answer for `options: { multi: true }` (edit distance reaches
  `multi` from none of them); the same curation is copied to the registration
  door in service-automation's engine, per #4001's finding that detection
  generalizes for free while prose does not.
- descriptors: `multi` declared on both designer forms, so the form<->Zod
  ledger reconciles and the key is authorable in Studio, not only by hand.
- tests: `crud-bulk-intent.test.ts`, whose delete double opens with
  `assertEngineDeleteDispatch` from @objectstack/objectql — the producer's own
  predicate — so it cannot accept a call the real engine refuses. That is the
  #5197 blind spot closed for this file: `run-summary.test.ts`'s zero-parameter
  `async delete() { return false }` accepts predicate deletes AND is invisible
  to check-engine-double-contract's arity test. Needed a devDependency on
  @objectstack/objectql (acyclic — objectql's closure does not contain
  service-automation); the eight service-automation baseline entries citing
  that missing dep as their blocker are updated to say so.


Claude-Session: https://claude.ai/code/session_018fxLGQdatPbBUvCgiVxg6D

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/flow-crud-bulk-intent.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": minor
+---
+
+feat(spec,automation): `update_record` / `delete_record` can declare bulk intent with `multi` (#5393)
+
+A flow could not express "write every row this filter matches" — at all, from
+any app. `UpdateRecordConfigSchema` / `DeleteRecordConfigSchema` are
+`strictObject`s and neither declared any spelling of bulk intent (`multi`,
+`bulk`, `all` and `options.multi` were each rejected as an unrecognized key),
+and the CRUD executors never passed `options.multi` to the data engine. The
+engine accepts a write only when `where.id` is a **scalar** or `options.multi`
+is truthy, and throws otherwise — so a predicate `update_record` /
+`delete_record` was unreachable, while the node descriptors advertised
+`Delete Records` / "Delete records matching a filter." Declared ≠ enforced
+(Prime Directive #10); the symptom was #5225's showcase sweep flow, which had
+never deleted a record.
+
+**New authorable key — `multi` (boolean, default `false`), on `update_record`
+and `delete_record`.** One name for one concept (PD #12): `multi` is what the
+data engine has always called it (`EngineUpdateOptions.multi` /
+`EngineDeleteOptions.multi`), so the word is the same from node config to
+driver call and greps end to end.
+
+```ts
+// before — refused by the engine at run time, with no authoring-time signal
+{ type: 'delete_record', config: { objectName: 'lead', filter: { stage: 'stale' } } }
+
+// after — the declaration makes the intent explicit and the write reachable
+{ type: 'delete_record', config: { objectName: 'lead', filter: { stage: 'stale' }, multi: true } }
+```
+
+- **Absent or `false`** — unchanged behaviour. The executor forwards
+  `multi: false`, so the write must name one row by scalar `id`; anything else
+  (a predicate, or `id: { $in: [...] }`) is refused by the engine with
+  `Delete requires an ID or options.multi=true`. **That refusal is the
+  contract**, not a defect to route around: it is what keeps an undeclared
+  unbounded write from happening by accident.
+- **`true`** — the executor forwards `options.multi: true`, the write lands on
+  `driver.updateMany` / `deleteMany`, and the step's `acted` metric reports the
+  affected row count.
+
+Additive and backward compatible: no existing flow changes behaviour, and every
+by-id write keeps working untouched.
+
+Two guards are unchanged and worth stating explicitly. The #3810
+erased-condition guard still refuses a node whose authored filter condition
+interpolated to nothing, `multi` or not — bulk intent says "many rows are
+fine", never "a condition may vanish". And `multi: true` with **no** `filter`
+is the whole object, by declaration: write the constraint you mean.
+
+Wrong spellings are answered by name rather than by edit distance (which
+reaches `multi` from none of them): `bulk` / `all` / `multiple` get the
+prescription, and `options: { multi: true }` is called out as the engine's
+options bag written at the node's altitude.

content/docs/references/automation/builtin-node-config.mdx

@@ -158,6 +158,7 @@ const result = CreateRecordConfigSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **objectName** | `string` | ✅ | Object to delete from |
 | **filter** | `Record<string, any>` | optional | Field/value pairs identifying the record(s) to delete |
+| **multi** | `boolean` | optional | Declare bulk intent: delete every row the filter matches (default false — a predicate delete without it is refused by the engine) |
 
 
 ---
@@ -240,6 +241,7 @@ const result = CreateRecordConfigSchema.parse(data);
 | **objectName** | `string` | ✅ | Object to update |
 | **filter** | `Record<string, any>` | optional | Field/value pairs identifying the record(s) to update |
 | **fields** | `Record<string, any>` | optional | Field values to write |
+| **multi** | `boolean` | optional | Declare bulk intent: update every row the filter matches (default false — a predicate update without it is refused by the engine) |
 
 
 ---

packages/services/service-automation/package.json

@@ -23,6 +23,7 @@
     "@objectstack/spec": "workspace:*"
   },
   "devDependencies": {
+    "@objectstack/objectql": "workspace:*",
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"