fix(spec): correct three history strings that named the wrong failure

Self-review against the actual behaviour, before the claim shipped. The
`connectorConfig` / `boundaryConfig` / `position` / `inputSchema` prose named a
slip on a REQUIRED key (`connectorID`, `attachedToRef`) as the silent case. It
never was: a required key spelled wrong then reads as MISSING, which zod has
always rejected loudly. Nothing was silent about it.

What `.strip` actually swallowed is the OPTIONAL half — the mapped `input` map
(dispatched as `input ?? {}`: a successful connector call carrying nothing),
BPMN's `cancelActivity: false` (so `interrupting` fell to its `true` default and
a NON-interrupting event cancelled the host anyway), `optional: false` (so
`required` fell to false and `validateNodeInputSchemas` had nothing to require),
a canvas hint beside x/y. I.e. exactly the keys an author adds to CONSTRAIN
behaviour, replaced by a permissive default.

The corrected version is the stronger argument as well as the true one, and
getting it wrong is the failure mode this campaign has already paid for four
times (the withdrawn guidance prescriptions): rejection prose is behaviour, not
documentation. Fixed in the schemas, the module comment, the tests and the
ledger row; a test now pins the required-key case as loud so the distinction
cannot quietly re-blur.

Part of #4001

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

Author: claude

docs/audits/2026-07-unknown-key-strictness-ledger.md

@@ -527,7 +527,7 @@ not verdicts).
 
 | File | Sites | Class | Note |
 |---|---|---|---|
-| `flow.zod.ts` | 11 | authorable | **strict as of #4001** — the four outer authoring shapes at step 1, and **the six nested blocks at batch 11** (`FlowNode.connectorConfig` / `.position` / `.inputSchema` / `.waitEventConfig` / `.boundaryConfig`, `Flow.errorHandling`). The gap between those two dates is this campaign's own finding 17 inside its own file: closing the shells left the gate rejecting `nodee:` at node level while `connectorConfig: { connectorID }` — one capital letter — parsed clean and dispatched against an undefined connector id. Two things stay open and are now pinned in code with the reason, so a later sweep stops rather than "finishes" the file: the node `config` slot (ADR-0018 plugin namespace) and `FlowVersionHistorySchema` (the file's only WIRE shape — emitted on publish, never authored; its `definition` is `FlowSchema`, so the authored half inside a history record is gated anyway) |
+| `flow.zod.ts` | 11 | authorable | **strict as of #4001** — the four outer authoring shapes at step 1, and **the six nested blocks at batch 11** (`FlowNode.connectorConfig` / `.position` / `.inputSchema` / `.waitEventConfig` / `.boundaryConfig`, `Flow.errorHandling`). The gap between those two dates is this campaign's own finding 17 inside its own file: closing the shells left the gate rejecting `nodee:` at node level while `connectorConfig: { connectorId, actionId, params: {…} }` parsed clean and the executor dispatched `input ?? {}` — a successful connector call carrying nothing. Worth recording precisely, because the obvious example is the wrong one: a slip on a REQUIRED key was always loud (it then reads as missing). What `.strip` swallowed here is the OPTIONAL half — the input map, the retry budget, `interrupting: false`, `required: true` — i.e. exactly the keys an author adds to CONSTRAIN behaviour, replaced by a permissive default without a word. Two things stay open and are now pinned in code with the reason, so a later sweep stops rather than "finishes" the file: the node `config` slot (ADR-0018 plugin namespace) and `FlowVersionHistorySchema` (the file's only WIRE shape — emitted on publish, never authored; its `definition` is `FlowSchema`, so the authored half inside a history record is gated anyway) |
 | `etl.zod.ts` | 10 | authorable (p) | authored pipelines — **candidate**. **−12 at #4738**: `sync.zod.ts` (the L1 "Simple Sync" file — `DataSyncConfig`, its `ConflictResolution` enum and satellites, formerly this row's co-candidate) was deleted whole rather than hardened: three-repo zero importers, no parse site, defs unreachable from the metadata-type roots (#4650 gate), so there was no author for strictness to protect (#4535 C13+C15). The integration-side `ConflictResolution` → `ConnectorConflictResolution` rename in the same change is name-only and moves no sites |
 | `execution.zod.ts` | 13 | wire | run-state envelopes — never strict. +5 at #4354 (the run-summary family: step metrics / skip reason / per-node / per-gate / the summary itself) — engine-emitted telemetry read by the Console and by operator queries, nobody authors them, so the `wire` verdict covers them unchanged |
 | `state-machine.zod.ts` | 6 | authorable (p) | **−1 at #4658**: the orphan `EventSchema` (`{ type, schema }`, an XState-style signal declaration nothing referenced — `StateMachineSchema` names event types as `on:` record keys) was deleted rather than converged with `kernel/events/core.zod.ts`'s envelope `EventSchema`, whose key set it did not intersect (#4535 C6). The remaining 6 sites and their verdict are unchanged |

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

@@ -1310,10 +1310,15 @@ describe('unknown keys are rejected, not stripped (#4001)', () => {
   // ── batch 11: the INNER blocks ────────────────────────────────────────────
   //
   // Closing the four outer shells above left six nested authoring blocks on
-  // zod's default `.strip`, so the gate rejected `nodee:` at the node level
-  // while `connectorConfig: { connectorID }` — one capital letter — parsed
-  // clean and dispatched against an undefined connector id. Same defect, one
-  // layer in: a guard put where the author who wrote it was standing.
+  // zod's default `.strip`. Same defect, one layer in — a guard put where the
+  // author who wrote it was standing.
+  //
+  // What those six were actually hiding is worth stating, because it is not the
+  // obvious case: a slip on a REQUIRED key was always loud (the key then reads
+  // as missing). `.strip` swallowed the OPTIONAL half — the mapped input map,
+  // the retry budget, `interrupting: false`, `required: true` — i.e. precisely
+  // the keys an author adds to CONSTRAIN behaviour, silently replaced by a
+  // permissive default.
   describe('the nested authoring blocks (batch 11)', () => {
     const node = (extra: Record<string, unknown>) => ({ id: 'n1', type: 'script', label: 'N', ...extra });
 
@@ -1323,11 +1328,18 @@ describe('unknown keys are rejected, not stripped (#4001)', () => {
       }));
       expect(issue!.message).toContain("connector_action node's `connectorConfig`");
       expect(issue!.message).toContain('`params` → `input`');
-      // The one that motivates the block: a case slip on the id the executor
-      // reads, which used to dispatch with `connectorId: undefined`.
-      expect(unknownKeyIssue(FlowNodeSchema, node({
+    });
+
+    it('connectorConfig: the silent case was the OPTIONAL half, not the ids', () => {
+      // Before this change, `{ connectorId, actionId, params }` parsed clean and
+      // the executor dispatched `input ?? {}` — a successful call carrying
+      // nothing. A slip on a REQUIRED id was never silent (it reads as missing),
+      // which is why this block's history names the input map and not the ids.
+      const result = FlowNodeSchema.safeParse(node({
         connectorConfig: { connectorID: 'rest', actionId: 'get' },
-      }))!.message).toContain('`connectorID` → `connectorId`');
+      }));
+      expect(result.success).toBe(false);
+      expect(JSON.stringify(result.error!.issues)).toContain('connectorId');
     });
 
     it('position: rejects a third coordinate rather than dropping it at (0, 0)', () => {

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

@@ -85,11 +85,21 @@ export const FLOW_STRUCTURAL_NODE_TYPES: readonly string[] = ['start', 'end'];
  * / `.position` / `.inputSchema` / `.waitEventConfig` / `.boundaryConfig` and
  * `Flow.errorHandling`. That is the shape this campaign keeps re-finding: a
  * guard put where the author who wrote it was standing. The outer gate rejected
- * `nodee:` at the node level while `connectorConfig: { connectorID }` — one
- * capital letter — still parsed clean and dispatched the action against an
- * undefined connector id. They use {@link strictObject}, whose candidate list is
- * read from the shape itself, so these six need no drift-guard entry (and adding
- * one would be the second copy of the truth the helper exists to delete).
+ * `nodee:` at the node level while `connectorConfig: { connectorId, actionId,
+ * params: {…} }` parsed clean and dispatched the action with **no inputs at
+ * all** — the executor reads `input ?? {}`, so the whole mapped payload became
+ * an empty object and the call succeeded against nothing.
+ *
+ * Note which cases those six were, and were not, hiding: a slip on a REQUIRED
+ * key (`connectorID` for `connectorId`, `attachedToRef` for `attachedToNodeId`)
+ * was always loud, because the required key then reads as missing. What
+ * `.strip` swallowed is the OPTIONAL half — the input map, the retry budget,
+ * `interrupting: false`, `required: true` — i.e. exactly the keys an author adds
+ * to CONSTRAIN behaviour, dropped back to a permissive default without a word.
+ *
+ * They use {@link strictObject}, whose candidate list is read from the shape
+ * itself, so these six need no drift-guard entry (and adding one would be the
+ * second copy of the truth the helper exists to delete).
  *
  * Deliberately still open, both re-confirmed here rather than left to be
  * rediscovered: the node `config` slot (above), and
@@ -206,9 +216,9 @@ export const FlowNodeSchema = lazySchema(() => z.object({
         payload: 'input',
       },
       history:
-        'Until #4001 these were dropped silently — the block still parsed, so a ' +
-        'mis-spelled connector/action id or a whole input map was ignored and the ' +
-        'action dispatched with `input ?? {}` against `undefined`.',
+        'Until #4001 these were dropped silently — the block still parsed, so a whole ' +
+        'mapped input map written under another word vanished and the executor ' +
+        'dispatched the action with `input ?? {}`: a successful call carrying nothing.',
     },
     {
       connectorId: z.string().describe('Registered connector name'),
@@ -229,8 +239,10 @@ export const FlowNodeSchema = lazySchema(() => z.object({
     {
       surface: "this node's canvas `position`",
       history:
-        'Until #4001 these were dropped silently — the block still parsed, so a node ' +
-        'carrying a size or a third coordinate landed on the canvas at (0, 0) instead.',
+        'Until #4001 these were dropped silently — the block still parsed, so a canvas ' +
+        'hint written beside x/y (a size, a third coordinate, a designer marker) was ' +
+        'discarded, and the round-trip back through the designer could not tell it had ' +
+        'ever been written.',
     },
     { x: z.number(), y: z.number() },
   ).optional(),
@@ -255,8 +267,9 @@ export const FlowNodeSchema = lazySchema(() => z.object({
       },
       history:
         'Until #4001 these were dropped silently — the declaration still parsed, so a ' +
-        'parameter the author marked required was generated as an optional Studio form ' +
-        'field and never validated at run time.',
+        'parameter constrained under a word we do not declare (`optional: false`) came ' +
+        'back UNconstrained: `required` fell to its `false` default, and the engine\'s ' +
+        'pre-execution check (`validateNodeInputSchemas`) then had nothing to require.',
     },
     {
       type: z.enum(['string', 'number', 'boolean', 'object', 'array']).describe('Parameter type'),
@@ -368,9 +381,10 @@ export const FlowNodeSchema = lazySchema(() => z.object({
       duration: 'timerDuration',
     },
     history:
-      'Until #4001 these were dropped silently — the block still parsed, so a boundary ' +
-      'event whose host node the author named with the BPMN word attached to nothing and ' +
-      'never fired.',
+      'Until #4001 these were dropped silently — the block still parsed, so BPMN\'s ' +
+      '`cancelActivity: false` was discarded and `interrupting` fell to its `true` ' +
+      'default: an event the author declared NON-interrupting cancelled the host ' +
+      'activity anyway.',
   }, {
     /** ID of the host node this boundary event is attached to */
     attachedToNodeId: z.string().describe('Host node ID this boundary event monitors'),