feat(spec,automation): publish executor-derived config contracts for the schemaless flow nodes (#4278)

The descriptor-schemaless builtins (decision/script/subflow/wait/
connector_action) deliberately publish no configSchema, so their Studio
forms live only in objectui's hand-written FLOW_NODE_CONFIG table — and
nothing reconciled that table against the executors. Publish the
machine-readable half of that reconciliation from spec, written from the
executors, not from any form:

- automation/schemaless-node-config.zod.ts: ScriptConfigSchema /
  SubflowConfigSchema / DecisionConfigSchema (+ DecisionConditionSchema),
  plus SCRIPT_BUILTIN_ACTION_TYPES and SCRIPT_INVOKE_FUNCTION_ACTION_TYPE.
  Contract exports only — no engine path parses node config with them.
  wait / connector_action need no new schema: their contracts are the
  existing FlowNodeSchema sibling blocks.
- The script executor now builds its dispatch set from the published
  constant, so the designer's options, the dispatch set, and the "not a
  built-in action" failure message cannot disagree. New pins: every
  published action type runs the built-in branch, the failure message
  names exactly the published set, and the Zod accepts the canonical
  authoring shapes.
- subflow's undeclared `flow` alias graduates into the ADR-0087 D2
  conversion layer (flow-node-subflow-flow-alias, protocol 17, live
  window) and the bare `cfg.flowName ?? cfg.flow` executor fallback is
  deleted (PD #12 — the map.flow path). Proved at the registerFlow seam.

objectui's flow-node-config.spec-reconciliation test is the other half:
it compares the hand-written form groups against these exports, closing
the cross-repo seam #4278 documented (script offered three broken
options and could not author the function path that works).

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

Author: claude

.changeset/schemaless-node-config-contracts.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": patch
+---
+
+feat(spec,automation): publish executor-derived config contracts for the schemaless flow nodes (#4278)
+
+The five descriptor-schemaless builtins (`decision` / `script` / `subflow` /
+`wait` / `connector_action`) deliberately publish no `configSchema`, so their
+Studio form lives only in objectui's hand-written `FLOW_NODE_CONFIG` table —
+and nothing reconciled that table against the executors. `script` had drifted:
+the form offered an `outputVariables` key nothing reads, two `actionType`
+options (`sms` / `notification`) that fail every run, a no-op default (`code`),
+and could not author the `function` / `inputs` / `outputVariable` path that
+works.
+
+New in `@objectstack/spec/automation` (contract exports only — no engine path
+parses node config with them):
+
+- `ScriptConfigSchema` / `SubflowConfigSchema` / `DecisionConfigSchema` (+
+  `DecisionConditionSchema`) — written from the executors in
+  `service-automation`, the machine-readable half of the cross-repo
+  reconciliation objectui's `flow-node-config` test now performs. `wait` and
+  `connector_action` need no new schema — their contracts are the existing
+  `FlowNodeSchema` sibling blocks (`waitEventConfig` / `connectorConfig`).
+- `SCRIPT_BUILTIN_ACTION_TYPES` (`['email', 'slack']`) and
+  `SCRIPT_INVOKE_FUNCTION_ACTION_TYPE` (`'invoke_function'`) — the `script`
+  executor now builds its dispatch set from the published constant, so the
+  designer's options, the dispatch set, and the "not a built-in action"
+  failure message can no longer disagree.
+
+Undeclared-alias graduation in the same change (Prime Directive #12, the
+`map.flow` path): the `subflow` executor's bare `cfg.flowName ?? cfg.flow`
+fallback is deleted, replaced by the ADR-0087 D2 conversion
+`flow-node-subflow-flow-alias` — a stored `subflow` node authored with
+`config.flow` is rewritten to the canonical `config.flowName` at load
+(including the `AutomationEngine.registerFlow` rehydration seam). FROM
+`config.flow` TO `config.flowName`; one-line fix for hand-maintained sources:
+rename the key.

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

@@ -65,9 +65,19 @@ reason instead of pretending a shape.
 
 - `decision` / `script` / `subflow` / `wait` / `connector_action` — the
 
-deliberately-schemaless class (config-schemas.test.ts); their contracts
+descriptor-schemaless class (config-schemas.test.ts). `wait` and
 
-live elsewhere (edges, sibling blocks, conditional forms).
+`connector_action` keep their contracts in FlowNodeSchema's sibling
+
+blocks (`waitEventConfig` / `connectorConfig`); the other three publish
+
+executor-derived config contracts in `schemaless-node-config.zod.ts`
+
+(#4278) — separate from this module because they must NOT grow into
+
+descriptor `configSchema`s (the forms they describe stay hand-written in
+
+objectui, reconciled by a test there).
 
 <Callout type="info">
 **Source:** `packages/spec/src/automation/builtin-node-config.zod.ts`

content/docs/references/automation/index.mdx

@@ -15,6 +15,7 @@ This section contains all protocol schemas for the automation layer of ObjectSta
   <Card href="/docs/references/automation/flow" title="Flow" description="Source: packages/spec/src/automation/flow.zod.ts" />
   <Card href="/docs/references/automation/io-node-config" title="Io Node Config" description="Source: packages/spec/src/automation/io-node-config.zod.ts" />
   <Card href="/docs/references/automation/node-executor" title="Node Executor" description="Source: packages/spec/src/automation/node-executor.zod.ts" />
+  <Card href="/docs/references/automation/schemaless-node-config" title="Schemaless Node Config" description="Source: packages/spec/src/automation/schemaless-node-config.zod.ts" />
   <Card href="/docs/references/automation/state-machine" title="State Machine" description="Source: packages/spec/src/automation/state-machine.zod.ts" />
   <Card href="/docs/references/automation/sync" title="Sync" description="Source: packages/spec/src/automation/sync.zod.ts" />
   <Card href="/docs/references/automation/time-relative-trigger" title="Time Relative Trigger" description="Source: packages/spec/src/automation/time-relative-trigger.zod.ts" />

content/docs/references/automation/meta.json

@@ -21,6 +21,7 @@
     "job",
     "---More---",
     "builtin-node-config",
-    "io-node-config"
+    "io-node-config",
+    "schemaless-node-config"
   ]
 }

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

@@ -0,0 +1,147 @@
+---
+title: Schemaless Node Config
+description: Schemaless Node Config protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
+
+@module automation/schemaless-node-config
+
+Config contracts for the **descriptor-schemaless** builtins whose designer
+
+form lives ONLY in objectui's hand-written `FLOW_NODE_CONFIG` table —
+
+`script`, `subflow` and `decision` (#4278).
+
+## Why these nodes publish no descriptor `configSchema` — and still need this
+
+`config-schemas.test.ts` in `service-automation` pins the schemaless class
+
+with each member's reason: `decision`'s virtual Target column is derived from
+
+the out-edges, `script`'s form switches on `actionType`, `subflow` carries a
+
+top-level `timeoutMs` — a published partial schema would DROP those editors
+
+(the #4210 `connector_action` incident). So the Studio form for these types
+
+is objectui's hand-written group, and until #4278 **nothing reconciled that
+
+hand-written table against the executors**: `script`'s form offered an
+
+`outputVariables` key nothing reads, two `actionType` options that fail every
+
+run, a no-op default — and could not author the `function`/`inputs`/
+
+`outputVariable` path that works.
+
+These schemas are the machine-readable half of that reconciliation. They are
+
+**written from the executors** (`service-automation/builtin/screen-nodes.ts`
+
+for `script`, `subflow-node.ts`, `logic-nodes.ts` for `decision`), not from
+
+any form, and objectui's `flow-node-config` reconciliation test compares its
+
+hand-written key sets against them — the same bidirectional ledger the
+
+descriptor-schema'd builtins get from `builtin-node-form-zod-ledger.test.ts`,
+
+carried across the repo seam by the `@objectstack/spec` dependency objectui
+
+already has.
+
+`wait` and `connector_action` — the other two schemaless members — need no
+
+entry here: their contracts are the spec-structured sibling blocks on
+
+`FlowNodeSchema` (`waitEventConfig` / `connectorConfig`), which the
+
+same objectui test reconciles directly.
+
+## What these schemas are (and are not) wired to
+
+Contract exports only — like `builtin-node-config.zod.ts`, no engine path
+
+`parse()`s a node config with them today, so registering a flow behaves
+
+exactly as before.
+
+Undeclared aliases are NOT part of these contracts: `subflow`'s historical
+
+`flow` spelling graduated into the ADR-0087 D2 conversion
+
+`flow-node-subflow-flow-alias` (the `map.flow` path), so the executor only
+
+ever sees `flowName`.
+
+<Callout type="info">
+**Source:** `packages/spec/src/automation/schemaless-node-config.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { DecisionCondition, DecisionConfig, ScriptConfig, SubflowConfig } from '@objectstack/spec/automation';
+import type { DecisionCondition, DecisionConfig, ScriptConfig, SubflowConfig } from '@objectstack/spec/automation';
+
+// Validate data
+const result = DecisionCondition.parse(data);
+```
+
+---
+
+## DecisionCondition
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **label** | `string` | ✅ | Branch label; the winning branch resumes down the out-edge with this label ('true' expression = default/else path) |
+| **expression** | `string` | ✅ | Bare CEL predicate deciding this branch |
+
+
+---
+
+## DecisionConfig
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **conditions** | `{ label: string; expression: string }[]` | optional | Ordered decision branches (first true expression wins; omit to branch purely on edge conditions) |
+
+
+---
+
+## ScriptConfig
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **actionType** | `string` | optional | How this step runs: a built-in side effect ('email' \| 'slack'), the 'invoke_function' marker, or shorthand for a registered-function name |
+| **function** | `string` | optional | Registered function to call (defineStack(`{ functions }`)); takes precedence over actionType |
+| **inputs** | `Record<string, any>` | optional | Inputs passed to the function (values interpolate `{token}` templates) |
+| **outputVariable** | `string` | optional | Flow variable the function's return value is bound to |
+| **template** | `string` | optional | Built-in side effects only: message template id |
+| **recipients** | `string[]` | optional | Built-in side effects only: recipients (user ids, field refs, or addresses) |
+| **variables** | `Record<string, any>` | optional | Built-in side effects only: values injected into the template |
+| **script** | `string` | optional | Inline JS source — recognized but not executed by the built-in runtime; use a registered function via `function` instead |
+
+
+---
+
+## SubflowConfig
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **flowName** | `string` | ✅ | Flow invoked as this step (it may pause — approval / screen / wait) |
+| **input** | `Record<string, any>` | optional | Values passed to the subflow's input variables (interpolate `{token}` templates) |
+| **outputVariable** | `string` | optional | Parent flow variable the subflow's output is bound to |
+
+
+---
+

docs/protocol-upgrade-guide.md

@@ -157,6 +157,7 @@ One flow key changes WITHOUT a lossless target: `errorHandling.maxRetries` (#424
 | `flow-node-wait-event-config-lift` | `flow.node.wait.waitEventConfig` | wait flow-node loose config keys → the declared `waitEventConfig` block: 'eventType', 'timerDuration'/'duration' → 'timerDuration', 'signalName'/'signal' → 'signalName', 'timeoutMs' (#4045) | live — protocol 17 loader accepts the old shape |
 | `flow-node-connector-config-lift` | `flow.node.connector_action.connectorConfig` | connector_action flow-node loose config keys 'connectorId' / 'actionId' / 'input' → the declared `connectorConfig` block (#4045) | live — protocol 17 loader accepts the old shape |
 | `flow-node-map-flow-alias` | `flow.node.map.config.flowName` | map flow-node config key 'flow' → 'flowName' (#4045 — undeclared executor fallback graduation) | live — protocol 17 loader accepts the old shape |
+| `flow-node-subflow-flow-alias` | `flow.node.subflow.config.flowName` | subflow flow-node config key 'flow' → 'flowName' (#4278 — undeclared executor fallback graduation) | live — protocol 17 loader accepts the old shape |
 | `flow-node-script-config-aliases` | `flow.node.script.config` | script flow-node config keys 'functionName' → 'function', 'input' → 'inputs' (#3796) | live — protocol 17 loader accepts the old shape |
 | `permission-rls-priority-removed` | `permission.rowLevelSecurity.priority` | RLS-policy key 'priority' removed (#3896 audit — policies OR-combine, so the promised conflict-resolution semantics cannot exist; dropping it changes no outcome) | retired — `migrate meta` only |
 | `tool-inert-authoring-keys-removed` | `tool.category / tool.permissions / tool.active / tool.builtIn` | tool keys 'category'/'permissions'/'active'/'builtIn' removed (#3896 close-out — authorable and inert; permissions gated nothing, active:false withdrew nothing) | retired — `migrate meta` only |

packages/services/service-automation/src/builtin/config-schemas.test.ts

@@ -17,6 +17,12 @@
  * and `connector_action` (top-level `connectorConfig` block, #4045) — a
  * partial schema would drop those editors, and a schema rooted at `config`
  * would actively re-route sibling-block authoring to keys nothing reads.
+ *
+ * Schemaless ≠ contractless (#4278): `script` / `subflow` / `decision` publish
+ * executor-derived config Zods in spec `automation/schemaless-node-config.zod.ts`
+ * (wait / connector_action keep theirs as FlowNodeSchema sibling blocks), and
+ * objectui reconciles its hand-written form groups against those exports. The
+ * descriptors below still publish NO configSchema — that is what this file pins.
  */
 
 import { describe, it, expect } from 'vitest';

packages/services/service-automation/src/builtin/screen-nodes.test.ts

@@ -1,6 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeEach } from 'vitest';
+import {
+    SCRIPT_BUILTIN_ACTION_TYPES,
+    SCRIPT_INVOKE_FUNCTION_ACTION_TYPE,
+    ScriptConfigSchema,
+} from '@objectstack/spec/automation';
 import { AutomationEngine, type FlowFunctionHandler } from '../engine.js';
 import { registerScreenNodes } from './screen-nodes.js';
 
@@ -155,6 +160,65 @@ it('canonicalizes a stored `functionName` key to `function` at load (#1870 DX, #
     });
 });
 
+/**
+ * #4278 — the script node's contract is the spec-published one. The designer
+ * form for `script` is objectui's hand-written group (this node deliberately
+ * publishes no descriptor configSchema — config-schemas.test.ts), so the only
+ * machine-readable statement of what it accepts is
+ * `SCRIPT_BUILTIN_ACTION_TYPES` / `ScriptConfigSchema` in
+ * `@objectstack/spec/automation`. These pins are the objectstack half of the
+ * cross-repo reconciliation: the executor dispatches exactly the published
+ * built-in set (it now builds its dispatch set FROM the constant), and its
+ * failure message names that same set — objectui's side reconciles its form
+ * options and key set against the same exports.
+ */
+describe('script contract ↔ spec-published constants (#4278)', () => {
+    let engine: AutomationEngine;
+
+    beforeEach(() => {
+        engine = new AutomationEngine(createTestLogger());
+        registerScreenNodes(engine, createCtx());
+    });
+
+    it.each([...SCRIPT_BUILTIN_ACTION_TYPES])(
+        "every published built-in actionType runs the built-in branch: '%s'",
+        async (actionType) => {
+            engine.registerFlow('script_flow', scriptFlow({ actionType, template: 't', recipients: ['a'] }));
+            const result = await engine.execute('script_flow', {} as any);
+            expect(result.success).toBe(true);
+        },
+    );
+
+    it('an actionType outside the published set fails naming exactly that set (the #4278 sms repro)', async () => {
+        // The old objectui form offered 'sms' / 'notification'; neither is in
+        // the published set, so they resolve as function names and fail. The
+        // error must name the published members — it is the message the #4278
+        // report quoted, and the form's options now come from the same constant.
+        engine.registerFlow('script_flow', scriptFlow({ actionType: 'sms' }));
+        const result = await engine.execute('script_flow', {} as any);
+        expect(result.success).toBe(false);
+        for (const builtin of SCRIPT_BUILTIN_ACTION_TYPES) {
+            expect(result.error).toContain(builtin);
+        }
+        expect(result.error).toMatch(/'sms' is not a built-in action/);
+    });
+
+    it('the published Zod accepts the canonical authoring shapes (contract sanity)', () => {
+        // Function path — the only shape that does real work.
+        expect(ScriptConfigSchema.parse({
+            actionType: SCRIPT_INVOKE_FUNCTION_ACTION_TYPE,
+            function: 'score_lead',
+            inputs: { leadId: '{record.id}' },
+            outputVariable: 'score',
+        })).toMatchObject({ function: 'score_lead' });
+        // Built-in side effect.
+        expect(ScriptConfigSchema.parse({ actionType: 'email', template: 't', recipients: ['a'], variables: { x: 1 } }))
+            .toMatchObject({ actionType: 'email' });
+        // Inline script — recognized (and documented as not executed).
+        expect(ScriptConfigSchema.parse({ script: 'return 1;' })).toMatchObject({ script: 'return 1;' });
+    });
+});
+
 /** A one-`screen`-node flow whose screen node carries `config`. */
 function screenFlow(config: Record<string, unknown>) {
     return {

packages/services/service-automation/src/builtin/screen-nodes.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { PluginContext } from '@objectstack/core';
-import { defineActionDescriptor } from '@objectstack/spec/automation';
+import { defineActionDescriptor, SCRIPT_BUILTIN_ACTION_TYPES } from '@objectstack/spec/automation';
 import type { AutomationEngine } from '../engine.js';
 import { interpolate } from './template.js';
 
@@ -29,9 +29,12 @@ import { interpolate } from './template.js';
 
 /**
  * Built-in `script` side-effect action types with a (logger-backed) handler.
- * Anything else is treated as a registered-function name (#1870).
+ * Anything else is treated as a registered-function name (#1870). The member
+ * list is the spec-published `SCRIPT_BUILTIN_ACTION_TYPES` — the same constant
+ * the designer's `actionType` options reconcile against (#4278), so the form,
+ * this dispatch set, and the failure message below cannot disagree.
  */
-const SCRIPT_BUILTIN_ACTION_TYPES = new Set(['email', 'slack']);
+const SCRIPT_BUILTINS = new Set<string>(SCRIPT_BUILTIN_ACTION_TYPES);
 
 export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext): void {
     // screen — server-side pass-through (input vars already injected by engine).
@@ -206,7 +209,7 @@ export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext
 
         // Built-in side-effect actions keep their logger-backed behavior — but
         // only when an explicit `function` isn't set (that always wins).
-        if (!fnName && actionType && SCRIPT_BUILTIN_ACTION_TYPES.has(actionType)) {
+        if (!fnName && actionType && SCRIPT_BUILTINS.has(actionType)) {
           ctx.logger.info(
             `[Script:${actionType}] template=${String(cfg.template)} ` +
               `recipients=${JSON.stringify(cfg.recipients)} ` +
@@ -255,7 +258,7 @@ export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext
             success: false,
             error:
               `script node '${node.id}': '${target}' is not a built-in action ` +
-              `(${[...SCRIPT_BUILTIN_ACTION_TYPES].join(', ')}) and no function named '${target}' is registered. ` +
+              `(${[...SCRIPT_BUILTINS].join(', ')}) and no function named '${target}' is registered. ` +
               `Register it via \`defineStack({ functions: { '${target}': fn } })\`, or fix the name (#1870).`,
           };
         }

packages/services/service-automation/src/builtin/subflow-node.test.ts

@@ -362,4 +362,23 @@ describe('subflow node executor', () => {
     expect(result.success).toBe(false);
     expect(result.error).toMatch(/depth|recursive/i);
   });
+
+  // #4278 — this proves the CONVERSION, not executor tolerance. The executor
+  // reads only the canonical `flowName` (its bare `cfg.flow` fallback was
+  // deleted with the graduation); a stored flow on the undeclared `flow`
+  // spelling reaches it because `registerFlow` applies
+  // 'flow-node-subflow-flow-alias', which renames it at load.
+  it('accepts the legacy `config.flow` spelling via the conversion layer (#4278)', async () => {
+    engine.registerFlow('parent_flow', parentFlow({
+      flow: 'child_flow',
+      input: { msg: '{greeting}' },
+      outputVariable: 'subResult',
+    }));
+
+    const result = await engine.execute('parent_flow', { params: { greeting: 'hi' } });
+
+    expect(result.success).toBe(true);
+    expect(ran).toEqual(['child']);
+    expect(captured).toEqual([{ result: 'CHILD_DONE' }]);
+  });
 });