fix(spec,service-automation)!: enforce the screen-field bound's value shape and require reference on a lookup screen field

Maintainer ruling A′ (decision batch #130 item 1, 2026-09-13, verbatim
「同意」), applied across the five items it names.

1. Server-side enforcement at resume STAYS — `min_value` / `max_value`,
   both already in the ADR-0114 D2 catalog, no new error code.

2. The string gap closes. `validateScreenInputs` gains its own pass, BEFORE
   the bound: a present value for a `type: 'number'` screen field that is not
   a finite JSON number is refused with `invalid_type` — ⛔ never coerced.
   The bound pass compares numbers, so before this every non-number satisfied
   it by never reaching it (`"25"` under a `max` of 20 was conformant). The
   pin that recorded that silence is INVERTED in place, not deleted, so a
   later re-widening has to come back through it. Narrow in two directions on
   purpose: it keys off `type: 'number'` and not off the presence of a bound,
   and it is presence-conditioned exactly as the bound is.

3. `ScreenFieldConfigSchema` requires `reference` when `type` is `lookup`,
   via a `superRefine` that leaves `.shape` enumerable and the key set
   unmoved. This REVERSES the optionality the card first shipped; ADR-0078's
   own example of silently-inert metadata is a `lookup` with no `reference`,
   and a degraded shipped twin is not a reason to bend the contract to it.
   A stored bare lookup has NO lossless conversion — nothing in the metadata
   says which object the author meant — so it registers as an ADR-0087
   SEMANTIC entry (`screen-field-lookup-reference-required`, protocol 18),
   ⛔ never a D2 conversion that would have to invent a target. The entry is
   one file under `migrations/entries/semantic/`; `registry.ts` is its
   GENERATED projection (`gen:migration-registry`), never hand-merged.

4. The wording items, in every carrier: the bound's "re-checked when the
   submitted value is a number" qualifier is gone from the changeset, the
   flows guide, the generated node-config reference, both `.describe()`
   pairs, the `ScreenFieldSpec` doc block and the Studio designer form,
   because the qualifier is no longer true. `reference`'s requirement is
   stated wherever its optionality was.

5. `check:reference-carrier-shape` is green (exit 0): both `reference` sites
   this PR introduced reach their value through a name, which is the
   population the gate documents as unjudged. ⛔ No path ignore, and the
   `['a']` fixture still tests what it tested — it widened to four shapes,
   including the `{ object: 'x' }` carrier shape the gate exists for.

Also repaired, each falsified by the above rather than pre-existing:

- The changeset declared no break. It now carries `**BREAKING**` and the
  `<!-- adr-0087: registered screen-field-lookup-reference-required -->`
  disposition marker — a semantic entry with no declaration on the changeset
  is exactly what `check-adr-0087-registration` exists to notice. `minor`
  stays: the launch-window guard keeps breaks off `major` outside pre-mode.
- `ScreenInputIssue.code` enumerated `required` and `unknown_field` only and
  spoke of "the same two conditions". This PR put three more codes through
  that field.
- `ScreenFieldSpec.reference` claimed absence was "what every `lookup` screen
  field did before this key existed". It now states that the authoring schema
  refuses that shape, and why the WIRE type stays optional: a run suspended
  before the upgrade rehydrates a `ScreenSpec` stored under the old accept set.
- `api-surface/automation.json` and `export-origins/automation.json` were
  stale — the new exported refusal constant had never been propagated. Both
  regenerated with the repo's own generators; one additive line each.

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

Author: claude

.changeset/17306-screen-field-bound-help-lookup.md

@@ -5,6 +5,8 @@
 
 A flow screen field can now express a numeric bound, help text and a lookup target — spelled with the object field's own key names
 
+<!-- adr-0087: registered screen-field-lookup-reference-required -->
+
 `ScreenFieldConfigSchema` was `.strict` over exactly
 `name`/`label`/`type`/`required`/`options`/`defaultValue`/`placeholder`/`visibleWhen`,
 so three ordinary authoring intents had **no expression at all**. They did not
@@ -25,33 +27,52 @@ the same thing on a screen field:
 | `inlineHelpText` | `FieldSchema.inlineHelpText` | help under the input — `FieldSchema` renames `help`/`helpText`/`hint`/`tooltip` onto it, so a screen-local `helpText` would have been a second contract for one question |
 | `reference` | `FieldSchema.reference` | the object a `type: 'lookup'` field picks records from |
 
-**The bound is re-checked on resume when the submitted value is a number.**
-It rides to the client on `ScreenFieldSpec` so the user is stopped at the
-input, **and** `validateScreenInputs` re-checks it when the run resumes
-(`min_value` / `max_value`, both already in the ADR-0114 D2 field-error catalog
-— no new error code). A screen field's declared contract is the only contract
-behind it, so a bound the dialog alone applied would be bypassed by any caller
-posting a number to `resume` directly — the gap #4477 closed for `required`.
+**The bound is enforced, not advisory.** It rides to the client on
+`ScreenFieldSpec` so the user is stopped at the input, **and**
+`validateScreenInputs` re-checks it when the run resumes (`min_value` /
+`max_value`, both already in the ADR-0114 D2 field-error catalog — no new error
+code). A screen field's declared contract is the only contract behind it, so a
+bound the dialog alone applied would be bypassed by any caller posting to
+`resume` directly — the gap #4477 closed for `required`.
 
-⚠️ The re-check is as wide as what this surface can judge, and no wider: it
-fires only on a value that is already a finite number, because a screen field's
-`type` is an open widget hint with no closed vocabulary. A numeric string
-(`"25"`) is not coerced and passes the bound silently — so this is a narrower
-guarantee than "enforced server-side" on its own would claim.
+That sentence needs no "when the value is a number" qualifier, because the
+value SHAPE is checked first: on a `type: 'number'` field a present value that
+is not a finite JSON number is refused with `invalid_type` (also already in the
+catalog — still no new code), ⛔ **not coerced**. Before this, a bound pass that
+compares numbers was satisfied by anything that never reached it, so `"25"`
+under a `max` of `20` was conformant. One member of the open `type` vocabulary
+is read as a value domain; every other widget hint stays open, and a bound on a
+non-numeric field still constrains nothing.
 
 **Delivered with its rendering, not ahead of it.** The executor forwards all
 four onto the wire and the Studio designer form offers all four as repeater
 columns; `builtin-node-form-zod-ledger.test.ts` reconciles the two key sets
 against the Zod in both directions, so a key declared here and absent from the
 form fails that test rather than shipping as a field nobody can author.
 
-**Additive by construction.** `reference` is **optional** on `type: 'lookup'` —
-unlike `FieldSchema`, where it is required — because screen fields declaring a
-bare `lookup` with no target already exist in shipped flows, and refusing them
-would break metadata that parses today. Such a field keeps exactly its current
-behaviour. Nothing that parsed before this change stops parsing, and no resume
-bag that was accepted before is refused now: the bound fires only on a field
-that declares one, which nothing did before this release.
+**BREAKING** in the accept-set sense, in TWO places — landing as `minor` on
+both packages because the launch-window guard (`check-changeset-no-major`)
+keeps breaking changes off `major` outside pre-mode, not because the narrowing
+is small. Both were ruled (maintainer ruling A′, decision batch #130 item 1,
+2026-09-13); this release is **not** purely additive.
+
+1. `reference` is **required** when `type` is `lookup`, as it is on an object
+   field. A picker with no target object resolves nothing — ADR-0078's own
+   example of silently-inert metadata — and a degraded shape that ships today
+   is not a reason to bend the contract to it. A stored flow with a bare
+   `lookup` screen field parsed before and does not now. There is **no lossless
+   conversion**: nothing in the metadata says which object the author meant, so
+   this is an ADR-0087 **semantic** migration entry — a structured TODO
+   (`screen-field-lookup-reference-required`) that names the flow and the field
+   for a human to answer — and ⛔ never a D2 conversion that would have to
+   invent a target.
+2. A non-number submitted for a `type: 'number'` screen field is refused on
+   resume (`invalid_type`) instead of passing silently. A resume bag that was
+   accepted before can be refused now; it was never doing what its author
+   declared.
+
+Everything else is additive: the bound itself fires only on a field that
+declares one, which nothing did before this release.
 
 The neighbouring spellings are refused **with their landing key** rather than
 with a bare key list: `help`/`helpText`/`hint`/`tooltip` name `inlineHelpText`,

content/docs/automation/flows.mdx

@@ -404,9 +404,9 @@ field means the same thing here:
 
 | Key | Type | What it does |
 |:---|:---|:---|
-| `min` / `max` | `number` | Numeric bound. Applied by the client at the input **and re-checked server-side on resume when the submitted value is a number**. |
+| `min` / `max` | `number` | Numeric bound. Applied by the client at the input **and enforced server-side when the run resumes**. |
 | `inlineHelpText` | `string` | Help text under the input. Unlike `placeholder`, it stays readable after the user types. |
-| `reference` | `string` | Object whose records a `type: 'lookup'` field picks from, so the field renders a record picker. |
+| `reference` | `string` | Object whose records a `type: 'lookup'` field picks from, so the field renders a record picker. **Required** on a `lookup` field. |
 
 ```typescript
 {
@@ -424,18 +424,19 @@ field means the same thing here:
 }
 ```
 
-**The bound is re-checked on resume — for a value that arrives as a number.**
-`min` / `max` ride to the client so the user is stopped at the input, and
-`validateScreenInputs` re-checks them on resume, so a caller that skips the
-dialog and posts a *number* to `resume` directly is refused too (`min_value` /
-`max_value`, inside the run's `INVALID_SCREEN_INPUT`). A screen field's declared
-contract is the only contract behind it — there is no object schema to catch a
-bad bag downstream.
+**The bound is not advice.** `min` / `max` ride to the client so the user is
+stopped at the input, and `validateScreenInputs` re-checks them on resume, so a
+caller that skips the dialog and posts to `resume` directly is refused too
+(`min_value` / `max_value`, inside the run's `INVALID_SCREEN_INPUT`). A screen
+field's declared contract is the only contract behind it — there is no object
+schema to catch a bad bag downstream.
 
-⚠️ The re-check reads only finite numbers. `"25"` — the same quantity as a
-*string* — is not coerced and passes the bound in silence, for the reason the
-next list gives: this surface has no closed `type` vocabulary and so does not
-judge value shape. Outside that, the bound is the client's alone.
+That sentence carries no "if the value is a number" qualifier, because the
+shape is checked first: on a `type: 'number'` field a submitted value that is
+not a JSON number is **refused** on resume with `invalid_type`. `"25"` — the
+same quantity as a *string* — is **not coerced** into `25` and does not reach
+the bound; it is rejected as the wrong shape. The bound then compares numbers
+only, which is all a bound can do.
 
 **What these keys refuse:**
 
@@ -450,17 +451,23 @@ judge value shape. Outside that, the bound is the client's alone.
   (render that object's whole form), on a screen **field** it can only mean the
   lookup target.
 - **A non-string `inlineHelpText` or `reference`.**
+- **A `lookup` field with no `reference`.** A picker with no target object
+  resolves nothing, which is ADR-0078's own example of silently-inert
+  metadata, so `reference` is **required** when `type` is `lookup` — as it is
+  on an object field. The refusal names the key and shows the spelling.
+  ⚠️ This is a **narrowing**: a stored flow declaring a bare `lookup` screen
+  field parsed before this release and does not now. There is no lossless
+  conversion — nothing in the metadata says which object the author meant — so
+  the migration chain carries it as a structured TODO
+  (`screen-field-lookup-reference-required`) naming the flow and the field,
+  not an automatic rewrite.
 
 **What they deliberately do NOT refuse:**
 
-- **A `lookup` field with no `reference`.** Unlike an object field — where the
-  reference is required — this stays optional, because screen fields declaring a
-  bare `lookup` type already exist in shipped flows and refusing them would break
-  metadata that parses today. Such a field keeps its current behaviour: no
-  picker target to resolve.
-- **A bound on a non-numeric field, or a non-numeric value under a bound.** A
-  screen field's `type` has no closed vocabulary, so neither this schema nor the
-  resume check judges value shape; the bound simply never fires.
+- **A bound on a non-numeric field.** A screen field's `type` has no closed
+  vocabulary, so this schema cannot judge which types a bound is meaningful on.
+  A bound on a `text` field constrains nothing and is not an error — the shape
+  check above reads `type: 'number'` alone, never the presence of a bound.
 - **An absent value.** A bound constrains a value that is present — an optional
   bounded field left empty is conformant. Presence is `required`'s question.
 - **A bound on a field the user was never shown.** Like `required`, a bound on a

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

@@ -227,10 +227,10 @@ Value the variable takes: a string (`{token}` flow interpolation — a sole toke
 | **defaultValue** | `any` | optional | Prefilled value (interpolates `{token}` templates) |
 | **placeholder** | `string` | optional | Input placeholder text |
 | **visibleWhen** | `string` | optional | CEL predicate controlling visibility, evaluated client-side |
-| **min** | `number` | optional | Minimum accepted value (numeric fields); re-checked on resume when the submitted value is a number |
-| **max** | `number` | optional | Maximum accepted value (numeric fields); re-checked on resume when the submitted value is a number |
+| **min** | `number` | optional | Minimum accepted value (numeric fields); enforced on resume |
+| **max** | `number` | optional | Maximum accepted value (numeric fields); enforced on resume |
 | **inlineHelpText** | `string` | optional | Help text displayed below the field |
-| **reference** | `string` | optional | Target object name (snake_case) whose records a `type: 'lookup'` field picks from |
+| **reference** | `string` | optional | Target object name (snake_case) whose records a `type: 'lookup'` field picks from; REQUIRED when `type` is `lookup` |
 
 
 ---
@@ -249,10 +249,10 @@ Value the variable takes: a string (`{token}` flow interpolation — a sole toke
 | **defaultValue** | `any` | optional | Prefilled value (interpolates `{token}` templates) |
 | **placeholder** | `string` | optional | Input placeholder text |
 | **visibleWhen** | `string` | optional | CEL predicate controlling visibility, evaluated client-side |
-| **min** | `number` | optional | Minimum accepted value (numeric fields); re-checked on resume when the submitted value is a number |
-| **max** | `number` | optional | Maximum accepted value (numeric fields); re-checked on resume when the submitted value is a number |
+| **min** | `number` | optional | Minimum accepted value (numeric fields); enforced on resume |
+| **max** | `number` | optional | Maximum accepted value (numeric fields); enforced on resume |
 | **inlineHelpText** | `string` | optional | Help text displayed below the field |
-| **reference** | `string` | optional | Target object name (snake_case) whose records a `type: 'lookup'` field picks from |
+| **reference** | `string` | optional | Target object name (snake_case) whose records a `type: 'lookup'` field picks from; REQUIRED when `type` is `lookup` |
 
 ### Nested Shape: `ScreenFieldConfig.options[number]`
 

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

@@ -69,7 +69,7 @@ const LOOKUP_TARGET_COLUMN = {
   type: 'string',
   title: 'Lookup object',
   xRef: { kind: 'object' },
-  description: "Object whose records a `lookup` field picks from.",
+  description: "Object whose records a `lookup` field picks from. Required on a `lookup` field — a picker with no target object resolves nothing.",
 };
 
 export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext): void {
@@ -132,8 +132,8 @@ export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext
                   // a form that omitted them would leave the keys authorable
                   // only by hand. `builtin-node-form-zod-ledger.test.ts`
                   // reconciles this column set against the Zod both ways.
-                  min: { type: 'number', title: 'Min', description: 'Minimum accepted value (numeric fields). Re-checked when the run resumes, for a submitted value that is a number.' },
-                  max: { type: 'number', title: 'Max', description: 'Maximum accepted value (numeric fields). Re-checked when the run resumes, for a submitted value that is a number.' },
+                  min: { type: 'number', title: 'Min', description: 'Minimum accepted value (numeric fields). Enforced when the run resumes.' },
+                  max: { type: 'number', title: 'Max', description: 'Maximum accepted value (numeric fields). Enforced when the run resumes.' },
                   inlineHelpText: { type: 'string', title: 'Help text', description: 'Help text shown under the input. Unlike the placeholder, it stays readable once the user types.' },
                   reference: LOOKUP_TARGET_COLUMN,
                   visibleWhen: { type: 'string', title: 'Visible when', xExpression: 'expression' },

packages/services/service-automation/src/screen-input-contract.test.ts

@@ -9,6 +9,13 @@
  * would be bypassed by any caller that posts to `resume` directly. That is the
  * gap #4477 closed for `required`, and these pin the same closure for the
  * bound: the client stops the user at the input, the server stops everyone.
+ *
+ * ⚠️ Ruling A′ (2026-09-13) closed the second half of that sentence. The bound
+ * pass compares numbers, so a caller posting a non-number satisfied it by
+ * never reaching it — `"25"` under a `max` of 20 was conformant. A present
+ * value for a `type: 'number'` field is now refused unless it is a finite JSON
+ * number (`invalid_type`, ⛔ not coerced), and the pin that recorded the old
+ * silence is inverted in place rather than removed.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -55,10 +62,51 @@ describe('validateScreenInputs — the declared bound pair (#17306)', () => {
     expect(validateScreenInputs([discount], {}, ALWAYS_VISIBLE)).toEqual([]);
   });
 
-  it('does not fire on a non-numeric value — `type` has no closed vocabulary here', () => {
-    // The surface deliberately does not judge value shape; inventing an
-    // `invalid_number` on this path would promise a check it never declared.
-    expect(validateScreenInputs([discount], { discount: 'twenty' }, ALWAYS_VISIBLE)).toEqual([]);
+  // ── REVERSED (ruling A′, 2026-09-13): this pin used to assert the SILENCE ──
+  // It read 'does not fire on a non-numeric value — `type` has no closed
+  // vocabulary here', and asserted `[]` for `{ discount: 'twenty' }`. That
+  // silence was the string gap: under a `max` of 20 the string `"25"` satisfied
+  // the bound pass (which compares numbers) and no other pass looked at it, so
+  // the guarantee "skipping the dialog is refused too" held only for callers
+  // that already sent a number. The maintainer closed it — refuse, ⛔ never
+  // coerce — so the same input now yields an issue, and the assertion is
+  // inverted rather than deleted: a later widening that re-admits the string
+  // has to come back through this case.
+  it('refuses a non-number for a `type: \'number\'` field — the string gap is closed', () => {
+    const issues = validateScreenInputs([discount], { discount: 'twenty' }, ALWAYS_VISIBLE);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]!.code).toBe('invalid_type');
+    expect(issues[0]!.field).toBe('discount');
+    // ⛔ Not coerced: a numeric STRING is the shape being refused, so it must
+    // not be read as the number it spells and then bound-checked.
+    const numericString = validateScreenInputs([discount], { discount: '25' }, ALWAYS_VISIBLE);
+    expect(numericString.map((i) => i.code)).toEqual(['invalid_type']);
+    // …and the non-finite numbers, which are not JSON numbers either.
+    for (const value of [Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(validateScreenInputs([discount], { discount: value }, ALWAYS_VISIBLE).map((i) => i.code),
+        `value ${String(value)}`).toEqual(['invalid_type']);
+    }
+  });
+
+  it('reads only `type: \'number\'` as a value domain — every other widget hint stays open', () => {
+    // The closure is one member of an open vocabulary, not a new rule that
+    // every `type` constrains its value. A bound on a non-numeric field still
+    // constrains nothing, exactly as `FieldSchema.min`/`.max` do.
+    const texty: ScreenFieldSpec = { name: 'discount', type: 'text', min: 0, max: 20 };
+    expect(validateScreenInputs([texty], { discount: 'twenty' }, ALWAYS_VISIBLE)).toEqual([]);
+    const untyped: ScreenFieldSpec = { name: 'discount', min: 0, max: 20 };
+    expect(validateScreenInputs([untyped], { discount: 'twenty' }, ALWAYS_VISIBLE)).toEqual([]);
+  });
+
+  it('leaves the shape check to `required` when the value is absent, and off a hidden field', () => {
+    // Absence is `required`'s question — reading it as a bad shape would make
+    // every optional numeric field secretly required.
+    expect(validateScreenInputs([discount], {}, ALWAYS_VISIBLE)).toEqual([]);
+    expect(validateScreenInputs([discount], { discount: null }, ALWAYS_VISIBLE)).toEqual([]);
+    const conditional: ScreenFieldSpec = { ...discount, visibleWhen: 'wantsDiscount == true' };
+    expect(validateScreenInputs([conditional], { discount: 'twenty' }, () => false)).toEqual([]);
+    // …and the control, or the reading above proves nothing.
+    expect(validateScreenInputs([conditional], { discount: 'twenty' }, () => true)).toHaveLength(1);
   });
 
   it('does not fire on a field the user was never shown', () => {