feat(automation,spec): flow executors parse() their config; undeclared config keys reject at registration (#4277)

Half (a): the 12 contract-carrying builtins (CRUD quartet, screen, map,
notify, http, loop/parallel/try_catch) now parse node.config against their
Zod contracts before executing (builtin/parse-config.ts). A type or
missing-required violation refuses the node as a guard — not routable via
fault edges. Templates stay legal: string slots parse the raw config; http
parses post-interpolation, the shape its executor reads. A legacy
flat-graph loop (no config.body) stays exempt. LoopConfigSchema.collection
widened to string|array — the executor always accepted inline arrays
(map.collection already declared the union), so string-only under-declared.

Half (b): registerFlow now REJECTS config keys the node type's descriptor
configSchema does not declare (tightening the #4059 warning), naming the
path, the declared key set, a did-you-mean, and per-key tombstones
(the UNKNOWN_KEY_GUIDANCE pattern). assignment stays exempt wholesale (its
top-level keys are author variable names); schemaless types and keyValue
maps are unchanged.

Example metadata fixed at the producer (PD #12): two showcase notify nodes
missing the required recipients/title (both already failed at run time),
and app-todo's dead getAll/message/buttons keys plus bare-string select
options.

Closes #4277

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CW8ZP3zUuC7ovSxqnN5o77

Author: claude

.changeset/flow-executors-parse-config.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/service-automation": minor
+"@objectstack/spec": minor
+---
+
+feat(automation,spec): flow executors `parse()` their config, and undeclared config keys reject at registration (#4277)
+
+The #4045 reconciliation left every flat builtin with a Zod config contract that
+nothing enforced, and #4059 left `registerFlow` warning about undeclared keys it
+could not yet safely reject. #4277 installs both halves of the enforcement:
+
+**1. Executors parse their config (execute time).** The 12 contract-carrying
+builtins — `get_record` / `create_record` / `update_record` / `delete_record`,
+`screen`, `map`, `notify`, `http`, `loop` / `parallel` / `try_catch` — now run
+`node.config` through their Zod contract before executing
+(`service-automation/builtin/parse-config.ts`). A type or missing-`required`
+violation refuses the node as a **guard** (`errorClass: 'guard'`, not routable
+via `fault` edges — config is metadata; re-running changes nothing), naming
+every violated path. `{token}` templates stay legal: string-typed slots parse
+the raw template, and `http` — whose executor reads the interpolated config —
+parses POST-interpolation, where a whole-token template has already resolved to
+its value's real type. Exemption: a legacy flat-graph `loop` (no `config.body`)
+predates the ADR-0031 construct and is not parsed.
+
+**2. Undeclared config keys are rejected at `registerFlow` (registration
+time).** The #4059 warning is now an error: a config key the node type's
+descriptor `configSchema` does not declare fails registration, with the exact
+path, the declared key set, a did-you-mean, and — for keys with documented
+history (`screen.visibleIf`, `create_record`/`update_record.fieldValues`) — a
+per-key tombstone (the `UNKNOWN_KEY_GUIDANCE` pattern). Unchanged exemptions:
+`assignment` is exempt wholesale (its top-level keys ARE the author's variable
+names), schemaless types (`decision`/`script`/`wait`/`subflow`/
+`connector_action`) declare nothing so nothing can be undeclared, and keyValue
+maps stop the walk (their keys are author data). Every `registerFlow` call site
+already try/catches per flow, so a bad stored flow is skipped loudly at boot,
+never a crashed kernel.
+
+**Contract fix folded in:** `LoopConfigSchema.collection` is now
+`z.union([z.string().min(1), z.array(z.unknown())])` — the executor has always
+accepted an inline array (shared resolve logic with `map.collection`, which
+already declared the union), so the string-only declaration under-declared what
+it reads.
+
+**Migration.** If a flow stops registering: the error names the undeclared key
+and its path — rename it to the declared key it meant (`visibleIf` →
+`visibleWhen`, `fieldValues` → `fields`), or delete it (an undeclared key was
+never read, so removing it changes no behavior). If an executor of yours
+genuinely reads the key, declare it on the node type's descriptor
+`configSchema`. If a node starts refusing at run time: the refusal names each
+violated path against the contract — fix the value's type or supply the missing
+required key (e.g. `get_record` `limit` must be a number; `screen`
+`fields[].options` entries are `{ value, label }` objects; `notify` requires
+`recipients` + `title`). Retry-policy defaults now come from the contract: a
+`try_catch` `retry` block that omits `retryDelayMs` gets the documented 1000ms
+base delay where the executor historically used 0.

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

@@ -43,15 +43,21 @@ field-item keys `options`/`defaultValue`/`placeholder`, `map.indexVariable`,
 
 ADR-0087 D2 conversion layer like `notify.source` before it.
 
-## What these schemas are (and are not) wired to
+## What these schemas are wired to (#4277)
 
-Contract exports only — no engine path `parse()`s a node config with them
+Live execute-time contracts: each executor `parse()`s its config against
 
-today, so registering a flow behaves exactly as before. Wiring the executors
+its schema before running (`service-automation`'s `parse-config.ts`), so
 
-to parse is deliberately deferred until the #4059 undeclared-key warning has
+type and `required` violations refuse the node as a guard. All of these
 
-measured a release's worth of real metadata (#4045 step 3b).
+parse the RAW stored config — their typed slots are strings (or `unknown`
+
+where values interpolate), so `\{token\}` templates pass and resolve at the
+
+executor's existing interpolation points. Unknown keys are rejected earlier,
+
+at `registerFlow()` (the tightened #4059 check); the parse here strips them.
 
 Deliberately absent:
 

content/docs/references/automation/control-flow.mdx

@@ -107,7 +107,7 @@ const result = FlowRegion.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **collection** | `string` | ✅ | Template/variable resolving to the array to iterate |
+| **collection** | `string \| any[]` | ✅ | Template/variable resolving to the array to iterate (an inline array is accepted) |
 | **iteratorVariable** | `string` | optional | Loop variable holding the current item |
 | **indexVariable** | `string` | optional | Optional loop variable holding the current index |
 | **maxIterations** | `integer` | optional | Hard cap on iterations (clamped to the engine ceiling) |

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

@@ -25,21 +25,31 @@ and a Zod copied from the form would make that reconciliation a tautology —
 
 it would pass by construction and prove nothing (#4045).
 
-## What these schemas are (and are not) wired to
+## What these schemas are wired to (#4277)
 
 Like `LoopConfigSchema` / `ParallelConfigSchema` / `TryCatchConfigSchema`,
 
-these are **contract exports**: no engine path `parse()`s a node config with
+these are **live execute-time contracts**: each executor `parse()`s its
 
-them today, so registering a flow behaves exactly as before. Wiring the
+config against its schema before running (`service-automation`'s
 
-executors to parse — which would finally give node configs the type /
+`parse-config.ts`), so type and `required` violations refuse the node as a
 
-`required` / unknown-key enforcement the descriptor `configSchema` never
+guard (not routable via `fault` edges). `notify` parses the RAW stored
 
-provided — is deliberately deferred until the #4059 undeclared-key warning
+config — its slots are string-typed, so `\{token\}` templates pass and the
 
-has measured a release's worth of real metadata (#4045 step 3b).
+post-interpolation guards still own "resolved to nothing". `http` parses
+
+the INTERPOLATED config, because that is the shape its executor reads —
+
+a `\{token\}` in a typed slot (`timeoutMs`, `durable`) resolves to its real
+
+type first. Unknown keys are the registration layer's job: `registerFlow()`
+
+rejects keys the descriptor `configSchema` does not declare (the tightened
+
+#4059 check), while the parse here strips them.
 
 `connector_action` has no schema here on purpose: its config contract is
 

content/docs/references/automation/node-executor.mdx

@@ -70,7 +70,7 @@ Canonical cross-paradigm action/node descriptor (ADR-0018)
 | **icon** | `string` | optional | Icon id resolved by the designer |
 | **category** | `Enum<'logic' \| 'data' \| 'io' \| 'human' \| 'control' \| 'custom'>` | ✅ | Palette category |
 | **paradigms** | `Enum<'flow' \| 'approval'>[]` | ✅ | Authoring surfaces that may offer this action |
-| **configSchema** | `any` | optional | JSON Schema for the node config (drives the designer form; only declared expression slots are validated) |
+| **configSchema** | `any` | optional | JSON Schema for the node config (drives the designer form; undeclared keys are rejected at registration) |
 | **supportsPause** | `boolean` | ✅ | Supports async pause/resume |
 | **supportsCancellation** | `boolean` | ✅ | Supports cancellation |
 | **supportsRetry** | `boolean` | ✅ | Supports retry on failure |

examples/app-showcase/src/automation/flows/index.ts

@@ -1384,7 +1384,10 @@ export const InquiryPurgeFlow = defineFlow({
       id: 'report',
       type: 'notify',
       label: 'Report cleanup',
-      config: { topic: 'inquiry_purge', message: 'Closed inquiries purged.' },
+      // `recipients` + `title` are the notify contract's required pair — this
+      // node used to omit both, so every purge run FAILED here at execute time
+      // (found when the executors started parsing their config, #4277).
+      config: { topic: 'inquiry_purge', recipients: ['admin@objectos.ai'], title: 'Closed inquiries purged', message: 'Closed inquiries purged.' },
     },
     { id: 'end', type: 'end', label: 'End' },
   ],
@@ -1538,6 +1541,10 @@ export const TaskDueReminderFlow = defineFlow({
       label: 'Remind Owner',
       config: {
         topic: 'task.due_soon',
+        // The contract's required audience — this node used to omit it, so
+        // every sweep run FAILED here ("at least one recipient is required")
+        // and the #1874 demo never delivered (surfaced by #4277's parse).
+        recipients: ['{record.assignee}'],
         channels: ['inbox'],
         severity: 'warning',
         title: 'Task due soon: {record.title}',

examples/app-todo/src/flows/task.flow.ts

@@ -20,7 +20,10 @@ export const TaskReminderFlow: Flow = {
     { id: 'start', type: 'start', label: 'Start (Daily 8 AM)', config: { schedule: '0 8 * * *', objectName: 'todo_task' } },
     {
       id: 'get_upcoming_tasks', type: 'get_record', label: 'Get Tasks Due Tomorrow',
-      config: { objectName: 'todo_task', filter: { due_date: '{tomorrow}', is_completed: false }, outputVariable: 'tasksToRemind', getAll: true },
+      // `limit > 1` is the declared way to make this a LIST read (`find`, not
+      // `findOne`) — the undeclared `getAll` that sat here was never read, so
+      // this sweep silently fetched a single task (#4277 rejects the key now).
+      config: { objectName: 'todo_task', filter: { due_date: '{tomorrow}', is_completed: false }, outputVariable: 'tasksToRemind', limit: 200 },
     },
     {
       id: 'loop_tasks', type: 'loop', label: 'Loop Through Tasks',
@@ -67,10 +70,11 @@ export const OverdueEscalationFlow: Flow = {
     { id: 'start', type: 'start', label: 'Start (Daily 9 AM)', config: { schedule: '0 9 * * *', objectName: 'todo_task' } },
     {
       id: 'get_overdue_tasks', type: 'get_record', label: 'Get Severely Overdue Tasks',
+      // `limit > 1` = LIST read; the undeclared `getAll` was never read (#4277).
       config: {
         objectName: 'todo_task',
         filter: { due_date: { $lt: '{3_days_ago}' }, is_completed: false, is_overdue: true },
-        outputVariable: 'overdueTasks', getAll: true,
+        outputVariable: 'overdueTasks', limit: 200,
       },
     },
     {
@@ -178,11 +182,31 @@ export const QuickAddTaskFlow: Flow = {
     {
       id: 'screen_1', type: 'screen', label: 'Task Details',
       config: {
+        // Select options are `{ value, label }` pairs (the screen contract's
+        // shape — bare strings fail the executor's config parse, #4277).
         fields: [
           { name: 'subject', label: 'Task Subject', type: 'text', required: true },
-          { name: 'priority', label: 'Priority', type: 'select', options: ['low', 'normal', 'high', 'urgent'], defaultValue: 'normal' },
+          {
+            name: 'priority', label: 'Priority', type: 'select', defaultValue: 'normal',
+            options: [
+              { value: 'low', label: 'Low' },
+              { value: 'normal', label: 'Normal' },
+              { value: 'high', label: 'High' },
+              { value: 'urgent', label: 'Urgent' },
+            ],
+          },
           { name: 'dueDate', label: 'Due Date', type: 'date', required: false },
-          { name: 'category', label: 'Category', type: 'select', options: ['personal', 'work', 'shopping', 'health', 'finance', 'other'] },
+          {
+            name: 'category', label: 'Category', type: 'select',
+            options: [
+              { value: 'personal', label: 'Personal' },
+              { value: 'work', label: 'Work' },
+              { value: 'shopping', label: 'Shopping' },
+              { value: 'health', label: 'Health' },
+              { value: 'finance', label: 'Finance' },
+              { value: 'other', label: 'Other' },
+            ],
+          },
         ],
       },
     },
@@ -196,13 +220,14 @@ export const QuickAddTaskFlow: Flow = {
     },
     {
       id: 'success_screen', type: 'screen', label: 'Success',
+      // The screen contract has no `message`/`buttons` keys — nothing ever
+      // read them, so this "success screen" was an invisible pass-through
+      // (#4277 rejects the keys now). `description` + `waitForInput: true`
+      // is the declared way to pause on a message-only confirmation screen.
       config: {
-        message: 'Task "{subject}" created successfully!',
-        buttons: [
-          { label: 'Create Another', action: 'restart' },
-          { label: 'View Task', action: 'navigate', target: '/task/{newTaskId.id}' },
-          { label: 'Done', action: 'finish' },
-        ],
+        title: 'Task Created',
+        description: 'Task "{subject}" created successfully!',
+        waitForInput: true,
       },
     },
     { id: 'end', type: 'end', label: 'End' },