fix(spec,lint): patch round 1 — cross-lane fixtures, lint alias tolerance, comment truths

- service-automation tests: the input-schema and parallel-branch doubles
  register under a type of their own (probe_step), never the builtin script,
  whose contract now refuses their undeclared keys at the flow parse.
- lint: validateStackExpressions keeps its declared pre-conversion tolerance
  for a script node's functionName alias; every other undeclared script key
  is still refused there (pinned).
- spec comments: the FlowSchema header and the node-config-refused-by-contract
  docblock say which arm judges key membership.
- changeset: @objectstack/lint patch.

Claude-Session: https://claude.ai/code/session_01RPo7FUd6bSnAfkWMAKi848
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21982-flow-script-subflow-config-undeclared-keys-refused.md

@@ -1,5 +1,6 @@
 ---
 '@objectstack/spec': minor
+'@objectstack/lint': patch
 ---
 
 A `script` or `subflow` flow node whose `config` carries a key its executor contract does not declare is refused at parse, with a location, in the contract's own words: a `script` `bogusKey`, a `subflow` `timeoutMs` written inside `config`, and the like no longer pass the build doors and registration and then fail every run.
@@ -34,6 +35,8 @@ Clause-②: no (narrowing)
 
 **Who is affected, measured.** At `15ec50e528`, every `script` and `subflow` node authored in this repository's examples, platform objects, apps, scaffolding templates, skills and docs (8 nodes: 6 `script`, 2 `subflow`) carries only declared keys, and so does every one in hotcrm at `c9678036d9` (5 `subflow`, no `script`). The Studio flow designer at the pinned objectui `a58626c88d` writes only declared keys for both types (its `timeoutMs` field writes the node, not `config`), and seeds a new node with an empty `config`. Deployed metadata, and other repositories, were not measured. Where such a node already sits in a stored flow, the whole flow is refused at registration: at boot it is skipped with a warn naming it, its trigger not armed, while the flows beside it register.
 
+**`@objectstack/lint`.** `validateStackExpressions` keeps the pre-conversion tolerance it declares: on a raw source, a `script` node's `functionName` alias stays the callable check's to read, not an undeclared-key error, while every other undeclared `script` key is refused there as at the build doors.
+
 ### The kit
 
 - **The refusal.** The key half of the executor-contract arm of `flowNodeConfigRefusals` in `automation/flow-node-config-refusals.ts`, judged for the builtins in the spec's schemaless class (`SCHEMALESS_NODE_CONFIG_SCHEMAS`) that have an executor contract; no new code joins `FLOW_SLOT_REFUSAL_CODES`, and `getBuiltinNodeConfigContracts()` keeps its 13 entries.

packages/lint/src/validate-expressions.test.ts

@@ -4535,6 +4535,21 @@ describe('node config an executor requires (#20316)', () => {
     expect(found.map((i) => i.where)).toEqual(["flow 'config_flow' · node 'n' (script) callable"]);
     expect(errorsOf(stackWith({ type: 'script', config: { functionName: 'recalc_totals' } }))).toHaveLength(0);
   });
+
+  it('a `script` key its contract does not declare is still refused — only the `functionName` alias is the callable check\'s', () => {
+    const config = { function: 'recalc_totals', bogusKey: 1 };
+    expect(errorsOf(stackWith({ type: 'script', config })).map((i) => [i.where, i.message, i.source])).toEqual([
+      ["flow 'config_flow' · node 'n' (script) config.bogusKey", flowNodeConfigRefusals('script', config)[0].message, ''],
+    ]);
+    // On a raw alias source the judge names `function`, `functionName` and
+    // `bogusKey`; the pass hands the first two to the callable check and
+    // keeps the third.
+    const aliased = { functionName: 'recalc_totals', bogusKey: 1 };
+    expect(flowNodeConfigRefusals('script', aliased).map((r) => r.path).sort()).toEqual(['bogusKey', 'function', 'functionName']);
+    expect(errorsOf(stackWith({ type: 'script', config: aliased })).map((i) => i.where)).toEqual([
+      "flow 'config_flow' · node 'n' (script) config.bogusKey",
+    ]);
+  });
 });
 
 /**

packages/lint/src/validate-expressions.ts

@@ -1714,8 +1714,15 @@ export function runStackExpressionPasses(stack: AnyRec, options: StackExpression
           // #4343): this pass may be handed a pre-conversion source, and that
           // check reads what such a source spells — the `functionName` alias,
           // the retired dispatch keys — and names each, where the judge would
-          // only see `function` absent.
-          .filter((configRefusal) => !(nodeType === 'script' && configRefusal.path === 'function'));
+          // only see `function` absent. Since the judge also refuses a key a
+          // `script`'s contract does not declare (#21982), it would name that
+          // same `functionName` alias undeclared too, so that one refusal is
+          // the callable check's as well: the pass keeps the pre-conversion
+          // tolerance it declares. Every other undeclared key stays refused.
+          .filter((configRefusal) => !(nodeType === 'script' && (
+            configRefusal.path === 'function'
+            || (configRefusal.code === 'node-config-refused-by-contract' && configRefusal.path === 'functionName')
+          )));
         for (const configRefusal of configRefusals) {
           issues.push({
             where: `${at} · node '${node.id}' (${nodeType}) config.${configRefusal.path}`,

packages/services/service-automation/src/engine.test.ts

@@ -2337,8 +2337,11 @@ describe('AutomationEngine - Parallel Branch Execution', () => {
         // sequential engine satisfies just as well.
         const trace: string[] = [];
 
+        // A test double under a type of its own, never the builtin `script`:
+        // `delay` is this double's key, and the `script` contract refuses an
+        // undeclared key at the flow parse that `registerFlow` runs first.
         engine.registerNodeExecutor({
-            type: 'script',
+            type: 'probe_step',
             async execute(node) {
                 trace.push(`enter:${node.id}`);
                 const delay = (node.config as any)?.delay ?? 0;
@@ -2355,8 +2358,8 @@ describe('AutomationEngine - Parallel Branch Execution', () => {
             type: 'autolaunched',
             nodes: [
                 { id: 'start', type: 'start', label: 'Start' },
-                { id: 'branch_a', type: 'script', label: 'Branch A', config: { function: 'noop', delay: 10 } },
-                { id: 'branch_b', type: 'script', label: 'Branch B', config: { function: 'noop', delay: 10 } },
+                { id: 'branch_a', type: 'probe_step', label: 'Branch A', config: { delay: 10 } },
+                { id: 'branch_b', type: 'probe_step', label: 'Branch B', config: { delay: 10 } },
                 { id: 'end', type: 'end', label: 'End' },
             ],
             edges: [
@@ -2442,8 +2445,11 @@ describe('AutomationEngine - Node Input Schema Validation', () => {
     });
 
     it('should fail when parameter type is wrong', async () => {
+        // A test double under a type of its own: `inputSchema` reads TOP-LEVEL
+        // config keys, and the builtin `script` contract refuses an undeclared
+        // `count` at the flow parse before this check could run.
         engine.registerNodeExecutor({
-            type: 'script',
+            type: 'probe_step',
             async execute() {
                 return { success: true };
             },
@@ -2457,9 +2463,9 @@ describe('AutomationEngine - Node Input Schema Validation', () => {
                 { id: 'start', type: 'start', label: 'Start' },
                 {
                     id: 'validated',
-                    type: 'script',
+                    type: 'probe_step',
                     label: 'Validated',
-                    config: { function: 'noop', count: 'not_a_number' },
+                    config: { count: 'not_a_number' },
                     inputSchema: {
                         count: { type: 'number', required: true },
                     },

packages/services/service-automation/src/input-schema-retry-parity.test.ts

@@ -55,8 +55,11 @@ function countingFlowEngine(opts: {
     const engine = new AutomationEngine(createTestLogger());
     const runs = { count: 0 };
 
+    // A test double under a type of its own, never the builtin `script`:
+    // `inputSchema` reads TOP-LEVEL config keys, and the `script` contract
+    // refuses an undeclared key at the flow parse `registerFlow` runs first.
     engine.registerNodeExecutor({
-        type: 'script',
+        type: 'probe_step',
         async execute() {
             runs.count++;
             return opts.executeResult ? opts.executeResult(runs.count) : { success: true };
@@ -72,11 +75,9 @@ function countingFlowEngine(opts: {
             { id: 'start', type: 'start', label: 'Start' },
             {
                 id: 'work',
-                type: 'script' as any,
+                type: 'probe_step',
                 label: 'Work',
-                // `function` is the key the script executor contract requires;
-                // the flow parse refuses a script node without it (#20316).
-                config: { function: 'noop', ...opts.config },
+                config: { ...opts.config },
                 inputSchema: opts.inputSchema,
             },
             { id: 'end', type: 'end', label: 'End' },

packages/spec/src/automation/flow-node-expression-paths.ts

@@ -556,10 +556,13 @@ export interface FlowSlotRefusalParams {
     readonly objectName: string;
   };
   /**
-   * (#21850) A key a WHOLE-judged node contract does not declare, or a value it
-   * refuses, at the key the author wrote — today the `approval` node's, the one
-   * plugin node contract the spec declares. Its message is the contract's own
-   * sentence, inside one naming the node type and the key.
+   * A node's executor contract refuses what the author wrote, at the key they
+   * wrote it: (#21850) a key the WHOLE-judged `approval` contract — the one
+   * plugin node contract the spec declares — does not declare, or a value it
+   * refuses; (#21898) a value a builtin node's executor contract refuses; and
+   * (#21982) a key a `script` or `subflow` executor contract does not declare.
+   * Its message is the contract's own sentence, inside one naming the node type
+   * and the key.
    */
   'node-config-refused-by-contract': { readonly nodeType: string; readonly key: string };
 }

packages/spec/src/automation/flow.zod.ts

@@ -159,17 +159,24 @@ export const FLOW_PAUSE_CAPABLE_NODE_TYPES: readonly string[] = [
  * note). One type-specific exception to the open slot (#14945): the structural
  * `end` node has no executor and no descriptor, so the flow parse is the ONLY
  * door its config passes through — {@link parseEndNodeConfig} applies
- * {@link EndConfigSchema} to it. Every other type's `config` stays the
- * executor's to close. One VALUE rule reaches into an open `config` at the
- * flow level without closing its key set (#17493): a blank string in a slot
- * the expression ledger declares with the `predicate` role is refused by the
- * `FlowSchema` superRefine — see the block there for its scope. A PRESENCE
- * rule reaches in beside it, still without closing the key set (#20316): a
- * key the node's executor contract requires, left out, and a `decision`
- * branch list the executor cannot read — `flowNodeConfigRefusals`, in the
- * same superRefine — and (#21898) a VALUE rule with it, again without closing
- * the key set: a value a builtin node's executor contract refuses, where the
- * build can know what the run will parse.
+ * {@link EndConfigSchema} to it. For every other type the `config` SHAPE
+ * stays open here (`FlowNodeSchema.config` is a `z.record`) and the executor's
+ * contract is what closes it; the flow level reads into it through one judge,
+ * `flowNodeConfigRefusals`, in the `FlowSchema` superRefine, and never
+ * re-declares a type's shape. A VALUE rule reaches in (#17493): a blank string
+ * in a slot the expression ledger declares with the `predicate` role is
+ * refused — see the block there for its scope. A PRESENCE rule beside it
+ * (#20316): a key the node's executor contract requires, left out, and a
+ * `decision` branch list the executor cannot read. A builtin VALUE rule with
+ * it (#21898): a value a builtin node's executor contract refuses, where the
+ * build can know what the run will parse. And KEY MEMBERSHIP only where the
+ * build is the one door before the run: the declared `approval` contract is
+ * judged whole (#21850), and a key a `script` or `subflow` executor contract
+ * does not declare is refused (#21982) — those two descriptors publish no
+ * `configSchema` for registration's undeclared-key walk to read. Every other
+ * builtin's undeclared key is judged at `registerFlow` against its descriptor,
+ * and so is a plugin type's whose contract the spec does not declare; the
+ * flow parse does not judge those keys.
  */
 
 /**