@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): a typed approval decision output's `type` and `multiple` are documented as enforced at the decision, not as a widget hint
+
+Clause-②: no
+Metadata-protocol: none
+
+The `DecisionOutputDefSchema` docblock, its `required` docblock and the `decisionOutputs` docblock on the approval node config said `type` and `multiple` only shape the decision dialog's input widget and that the runtime accepts whatever value shape arrives. They now state the contract (ADR-0104 as amended 2026-10-30): `multiple: true` takes a list with no entry twice, and an absent or false `multiple` takes one value, for every entry (`text` and bare-string entries included, judged by shape only); a picker output's values are also resolved, `user`, `department` and `team` by record id and `position` by the machine name of a position someone holds; a mismatch is refused with `400 VALIDATION_FAILED` naming `outputs.KEY`, before any write. The approvals guide (`content/docs/automation/approvals.mdx`) says the same, and its "previous approver picks the next step's approvers" example now declares `{ key: 'next_reviewers', multiple: true }`, since the list it sends is refused under a bare key. Comment and docs text only: no schema key, `.describe()` string, export or type changes.
@@ -327,8 +327,10 @@ run is never killed — and the log says both that the fallback fired and that i
 found nobody.
 
 The "previous approver picks the next step's approvers" loop needs no record
-field at all: declare `decisionOutputs: ['next_reviewers']` on node A, have the
-approver decide with `{ outputs: { next_reviewers: ['u2', 'u3'] } }`, and let
+field at all: declare `decisionOutputs: [{ key: 'next_reviewers', multiple: true }]`
+on node A (`multiple: true` because the answer is a list; a bare
+`'next_reviewers'` takes one value), have the approver decide with
+`{ outputs: { next_reviewers: ['u2', 'u3'] } }`, and let
 node B's approver be
 `{ type: 'expression', value: 'vars.<nodeA-id>.next_reviewers' }`. The author
 declares output keys, approvers only fill values; undeclared keys reject the
@@ -339,12 +341,31 @@ multiple: true }` — which renders a multi-select user picker in the decision
 dialog instead of free text (`department` / `team` render the matching
 system-object picker and commit record ids; `position` renders a picker over
 the position registry and commits position machine names; `multiple` collects
-an array of them). The type shapes only the input widget; the whitelist
-still works by `key`, so bare strings and typed declarations mix freely.
+an array of them). The whitelist still works by `key`, so bare strings and
+typed declarations mix freely.
+
+The runtime enforces every declaration at the decision, on an approve and a
+reject alike, before anything is written:
+
+- `multiple: true` takes a list, and only a list, with no entry twice. An
+  absent or `false` `multiple` takes one value. This holds for every entry,
+  `text` and bare strings included.
+- A picker output's values are also resolved, the way the matching
+  `expression` approver's `resolveAs` expands them, in the request's
+  organization: `user`, `department` and `team` by record id, `position` by
+  the machine name of a position someone holds. A position name nobody holds is
+  refused, and so is a `sys_position` record id: either would route to nobody.
+- A mismatch is refused with `400 VALIDATION_FAILED` naming every
+  `outputs.<key>` that does not match. No decision is recorded and the request
+  stays pending, so the approver can decide again.
+
+A `text` output (the default, and every bare-string entry) is judged by shape
+only: its value is free text. A blank value is left to `required`, below.
 
 Add **`required: true`** when the next step cannot run without it — the very
 case above, where node B has nobody to route to if the lead skipped the field.
-Unlike `type` / `multiple`, this one is enforced by the runtime: an **approve**
+Where `type` / `multiple` judge the shape of a value the approver supplies,
+`required` judges whether one is there: an **approve**
 carrying no value (or a blank one — `''`, `[]`) for a required key is rejected
 before any write, so the run can never resume past the node with the key
 missing. A **reject** never requires it: the run leaves down the `reject` edge,
 
@@ -656,8 +656,19 @@ export const DecisionOutputDefSchema = lazySchema(() => strictObject(
    * A TYPED decision-output declaration (#3447 P2 follow-up). The bare-string
    * form of a `decisionOutputs` entry renders as free text; this form tells the
    * decision UI which picker to render and whether to collect one value or many.
-   * The runtime treats `key` as the whitelist entry either way — `type` and
-   * `multiple` only shape the INPUT WIDGET, never the accepted value.
+   * The runtime treats `key` as the whitelist entry either way, and it ENFORCES
+   * `type` and `multiple` at the decision (ADR-0104 as amended 2026-10-30;
+   * #28658 ruling A). `multiple: true` takes a list, with no entry twice;
+   * `multiple` absent or false takes one value — for every entry, `text` and
+   * bare-string entries included. A picker output's values are also resolved,
+   * through the lookup the `expression` approver with the matching `resolveAs`
+   * expands them with:
+   * `user`, `department` and `team` by record id, `position` by the machine
+   * name of a position someone in the request's organization holds (a name
+   * nobody holds is refused). A `text` output is judged by shape only. A
+   * decision whose output does not match is refused with
+   * `400 VALIDATION_FAILED` naming `outputs.<key>`, before any write — no
+   * decision is recorded and the request stays pending.
    */
   {
     surface: 'this decision-output declaration',
@@ -696,8 +707,8 @@ export const DecisionOutputDefSchema = lazySchema(() => strictObject(
   /**
    * The approver must supply this output to APPROVE (objectui#2955).
    *
-   * Unlike `type`/`multiple` — which only shape the input widget — this one
-   * IS enforced by the runtime: an approve carrying no value for a required
+   * `type`/`multiple` judge the SHAPE of a value the approver supplies; this
+   * one judges PRESENCE: an approve carrying no value for a required
    * key is rejected before any write, so a downstream `expression` approver
    * reading `vars.<nodeId>.<key>` can never face a missing key. Without it an
    * author's only backstop was `onEmptyApprovers` — the run reaches the next
@@ -1201,16 +1212,21 @@ export const ApprovalNodeConfigSchema = lazySchema(() => strictObject(
    * next step's approvers" without a record-field detour. A decision carrying
    * undeclared keys is rejected; `decision` / `requestId` are reserved.
    *
-   * An entry is either a bare key (a plain text input in the decision UI) or a
-   * TYPED declaration — `{ key, type, multiple }` — that tells the decision UI
+   * An entry is either a bare key (a plain text input in the decision UI,
+   * taking one value) or a TYPED declaration — `{ key, type, multiple }` — that
+   * tells the decision UI
    * to render a picker instead of free text, sourced like the approver type of
    * the same name ({@link DecisionOutputDefSchema}'s `type`): `user` /
    * `department` / `team` → a record picker committing ids, `position` → the
    * position registry, committing machine names. `multiple: true` collects an
    * ARRAY of them (the natural fan-out shape for an `expression` approver
-   * downstream). The type describes the INPUT WIDGET only — the runtime accepts
-   * whatever value shape arrives (a single value, an array, CSV) and hands it
-   * to the flow verbatim.
+   * downstream). The runtime enforces the declaration at the decision:
+   * `multiple: true` takes a list with no entry twice and an absent or false
+   * `multiple` takes one value, for every entry (`text` and bare keys
+   * included, judged by shape only); a picker value must also name
+   * a record id (`user` / `department` / `team`) or the machine name of a
+   * position someone holds (`position`). A mismatch is refused with
+   * `400 VALIDATION_FAILED` naming `outputs.<key>` before any write.
    */
   decisionOutputs: z.array(z.union([
     z.string(),