@@ -0,0 +1,18 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: an approver `position` and a decision-output `position` are catalog names, listed from the metadata registry (ADR-0131 D4)
+
+Clause-②: yes
+
+<!-- adr-0087: not-required (no-migration-prescription) no authorable key, export or stored value changes: a position approver's value and a position decision output were names at run time and stay names; only the published picker binding changes shape -->
+
+**BREAKING** for a renderer that derives its position picker from `APPROVER_VALUE_SOURCES`, shipped as `minor` under the repo's launch-window convention for breaking changes. Authored and stored metadata is untouched.
+
+- **`APPROVER_VALUE_BINDINGS.position`** is a registry binding, `{ source: 'registry', type: 'position' }`. It was a record binding on `sys_position` rows that committed the row's `name`. `ApproverValueBinding` gains the `registry` member: the value is the machine name of an item of metadata `type`, and a catalog item has no other reference, so the member carries no `valueField`.
+- **`APPROVER_VALUE_SOURCES.position`**, the same binding on the wire (the `xRef.sources` of the approval node schema's `approvers[].value`), reads `{ source: 'registry', type: 'position' }`. It read `{ source: 'data', object: 'sys_position', valueField: 'name' }`, and its type gains the `{ source: 'registry'; type: string }` member. A picker for a `registry` source lists `GET /api/v1/meta/position`, which serves the code-declared and the environment-authored positions alike, and commits the item's `name`. `user`, `team` and `department` still read `data`.
+- **A `position` decision output collects position machine names**, the value the approver type of the same name takes. `DecisionOutputDef` said every picker collected record ids. The one reader that interprets a position output, an `expression` approver with `resolveAs: 'position'`, filters `sys_user_position.position` by name, so a `sys_position` id there routed the request to nobody. The `type` and `multiple` descriptions now say what each picker commits.
+- **The runtime does not change.** The approvals engine routes a position approver, an escalation target and a `resolveAs: 'position'` value by name, as it did.
+
+Why: positions are declared metadata (ADR-0131 D2), and every reference to one names it and resolves through the registry (D4). The `sys_position` table is a mirror that the ADR-0131 cutover retires, so a picker that lists its rows lists the mirror, not the catalog.
@@ -333,9 +333,10 @@ decision, and `decision` / `requestId` are reserved.
 
 A declaration can also be **typed** — `{ key: 'next_reviewers', type: 'user',
 multiple: true }` — which renders a multi-select user picker in the decision
-dialog instead of free text (`department` / `position` / `team` render the
-matching system-object picker; picker values are record ids, `multiple`
-collects an id array). The type shapes only the input widget; the whitelist
+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.
 
 Add **`required: true`** when the next step cannot run without it — the very
 
@@ -105,8 +105,8 @@ const result = ApprovalDecision.parse(data);
 | :--- | :--- | :--- | :--- |
 | **key** | `string` | ✅ | Output key (the flow variable name under the node id) |
 | **label** | `string` | optional | Field label in the decision dialog |
-| **type** | `Enum<'text' \| 'user' \| 'department' \| 'position' \| 'team'>` | optional | Decision-dialog input widget (default 'text') |
-| **multiple** | `boolean` | optional | Collect multiple values (id array) |
+| **type** | `Enum<'text' \| 'user' \| 'department' \| 'position' \| 'team'>` | optional | Decision-dialog input widget (default 'text'). The user, department and team pickers commit record ids; the position picker commits position machine names |
+| **multiple** | `boolean` | optional | Collect multiple values (an array of what the picker commits) |
 | **required** | `boolean` | optional | Approver must supply this output to approve |
 
 ### Nested Shape: `ApprovalNodeConfig.escalation`
@@ -150,8 +150,8 @@ Approval step approver type. `manager` is resolved from the directory rather tha
 | :--- | :--- | :--- | :--- |
 | **key** | `string` | ✅ | Output key (the flow variable name under the node id) |
 | **label** | `string` | optional | Field label in the decision dialog |
-| **type** | `Enum<'text' \| 'user' \| 'department' \| 'position' \| 'team'>` | optional | Decision-dialog input widget (default 'text') |
-| **multiple** | `boolean` | optional | Collect multiple values (id array) |
+| **type** | `Enum<'text' \| 'user' \| 'department' \| 'position' \| 'team'>` | optional | Decision-dialog input widget (default 'text'). The user, department and team pickers commit record ids; the position picker commits position machine names |
+| **multiple** | `boolean` | optional | Collect multiple values (an array of what the picker commits) |
 | **required** | `boolean` | optional | Approver must supply this output to approve |
 
 
 
@@ -6,12 +6,15 @@ import { defineFlow } from '@objectstack/spec';
  * #3508 dogfood: one node per RECORD-BACKED approver kind.
  *
  * The designer's Approvers → Value control used to query the metadata registry
- * (`GET /api/v1/meta/:type`) for every kind. `user` / `team` / `department` /
- * `position` are DATA rows in the platform's directory objects, not registry
- * entries, so candidates came back empty and the control degraded to a free-text
- * box — the author could only hand-type a userid. `APPROVER_VALUE_BINDINGS`
- * now publishes the data contract per kind (`xRef.sources`), and the designer
- * renders a real record lookup off it.
+ * (`GET /api/v1/meta/:type`) for every kind. `user` / `team` / `department` are
+ * DATA rows in the platform's directory objects, not registry entries, so
+ * candidates came back empty and the control degraded to a free-text box — the
+ * author could only hand-type a userid. `position` is a registry binding
+ * (ADR-0131 D4): its candidates come from the position registry
+ * (`GET /api/v1/meta/position`), and the value committed is the position's
+ * machine name. `APPROVER_VALUE_BINDINGS` now publishes the data contract per
+ * kind (`xRef.sources`) — a record lookup for the directory kinds, the registry
+ * for `position` — for the designer to source each picker from.
  *
  * This flow is the authoring specimen for that surface: every kind whose control
  * changed gets a node, so opening it in the flow designer exercises each one.
 
@@ -18,6 +18,7 @@ import {
   normalizeDecisionOutputs,
 } from './approval.zod';
 import { BUILTIN_MEMBERSHIP_ROLES } from '../identity/membership-role';
+import { MetadataTypeSchema } from '../kernel/metadata-plugin.zod';
 
 describe('ApproverType', () => {
   it('should accept all valid approver types', () => {
@@ -147,9 +148,25 @@ describe('APPROVER_VALUE_BINDINGS — an approver value is picked from the recor
     // find('sys_business_unit', { id: value }) — a sys_business_unit id
     // (deliberately NOT a `sys_department`).
     expect(APPROVER_VALUE_BINDINGS.department).toEqual({ source: 'record', object: 'sys_business_unit', valueField: 'id' });
+  });
+
+  it('binds position to the registry by machine name — a catalog item, not a sys_position row (ADR-0131 D4)', () => {
     // find('sys_user_position', { position: value }) — the position machine
-    // NAME, not an id (portable across environments).
-    expect(APPROVER_VALUE_BINDINGS.position).toEqual({ source: 'record', object: 'sys_position', valueField: 'name' });
+    // NAME, the only reference a registry item has. No `valueField`: there is
+    // no other column a catalog item could commit.
+    expect(APPROVER_VALUE_BINDINGS.position).toEqual({ source: 'registry', type: 'position' });
+    // Every registry binding names a type the registry actually serves — the
+    // compile-time check the binding forgoes to keep approval.zod.ts free of
+    // the kernel module graph.
+    for (const [type, binding] of Object.entries(APPROVER_VALUE_BINDINGS)) {
+      if (binding.source !== 'registry') continue;
+      expect(MetadataTypeSchema.safeParse(binding.type).success, `'${type}' binds unknown metadata type '${binding.type}'`)
+        .toBe(true);
+    }
+    // No binding names the retiring table as its source.
+    for (const [type, binding] of Object.entries(APPROVER_VALUE_BINDINGS)) {
+      expect((binding as { object?: string }).object, `'${type}' binds sys_position rows`).not.toBe('sys_position');
+    }
   });
 
   it('keeps the non-record kinds off the record-lookup path', () => {
@@ -189,8 +206,17 @@ describe('APPROVER_VALUE_SOURCES — where each picker finds its candidates, pub
     expect(APPROVER_VALUE_SOURCES.user).toEqual({ source: 'data', object: 'sys_user', valueField: 'id' });
     expect(APPROVER_VALUE_SOURCES.team).toEqual({ source: 'data', object: 'sys_team', valueField: 'id' });
     expect(APPROVER_VALUE_SOURCES.department).toEqual({ source: 'data', object: 'sys_business_unit', valueField: 'id' });
-    // The one kind that commits something other than the primary key.
-    expect(APPROVER_VALUE_SOURCES.position).toEqual({ source: 'data', object: 'sys_position', valueField: 'name' });
+  });
+
+  it('routes position to the metadata registry, where positions are declared items (ADR-0131 D4)', () => {
+    // `GET /api/v1/meta/position` serves both provenances; the picker commits
+    // the item's name, which is what the engine filters sys_user_position by.
+    expect(APPROVER_VALUE_SOURCES.position).toEqual({ source: 'registry', type: 'position' });
+    // `registry` is position's alone: every directory kind stays on the data API.
+    const registryKinds = Object.entries(APPROVER_VALUE_SOURCES)
+      .filter(([, s]) => s.source === 'registry')
+      .map(([type]) => type);
+    expect(registryKinds).toEqual(['position']);
   });
 
   it('keeps the non-record kinds off the lookup path and carries the closed enum inline', () => {
@@ -207,7 +233,26 @@ describe('APPROVER_VALUE_SOURCES — where each picker finds its candidates, pub
     const sources = schema?.properties?.approvers?.items?.properties?.value?.xRef?.sources;
     expect(sources).toBeDefined();
     expect(sources.department).toEqual({ source: 'data', object: 'sys_business_unit', valueField: 'id' });
-    expect(sources.position).toEqual({ source: 'data', object: 'sys_position', valueField: 'name' });
+    expect(sources.position).toEqual({ source: 'registry', type: 'position' });
+  });
+});
+
+// A typed decision output's picker is read downstream by an `expression`
+// approver's `resolveAs` of the same name, so it must source and commit what
+// that approver type takes. The docblock says so; this holds it: every picker
+// kind is an approver type whose binding is a lookup (record or registry).
+describe('DecisionOutputDef picker kinds follow the approver bindings of the same name', () => {
+  const pickerKinds = (DecisionOutputDefSchema as any).shape.type.unwrap().options
+    .filter((k: string) => k !== 'text') as string[];
+
+  it('names only approver types that are looked up, and covers the four it always had', () => {
+    expect([...pickerKinds].sort()).toEqual(['department', 'position', 'team', 'user']);
+    for (const kind of pickerKinds) {
+      const binding = (APPROVER_VALUE_BINDINGS as Record<string, { source: string }>)[kind];
+      expect(binding, `decision output '${kind}' has no approver binding`).toBeDefined();
+      expect(['record', 'registry'], `decision output '${kind}' is bound to '${binding.source}'`)
+        .toContain(binding.source);
+    }
   });
 });