feat(spec+approvals+lint): approver value bindings, retire queue authoring (#3508)

The designer's approver Value cell silently degraded to free text because it
sourced user/team/department candidates from the metadata registry
(GET /api/v1/meta/:type), which lists no records. Declare the contract once in
the spec so every designer sources it right:

- spec: export APPROVER_VALUE_BINDINGS (per-type value sourcing — record
  lookup objects + committed field, closed enum, auto, trigger-field,
  unsupported), ORG_MEMBERSHIP_LEVELS, and NON_AUTHORABLE_APPROVER_TYPES;
  publish 'queue' in xEnumDeprecated (declared-but-unenforced: the engine has
  no queue branch, the slot resolves to nobody) and map 'manager' in the value
  xRef so designers can render its auto-resolved state.
- plugin-approvals: warn when a stored queue approver is skipped at
  resolution time instead of dying silently into the 'queue:<id>' literal.
- lint: new approval-approver-type-unsupported warning, data-driven from
  APPROVER_VALUE_BINDINGS, so authoring a queue approver is called out at
  publish time (declared != enforced, Prime Directive #10).

Queue still parses — stored flows keep loading and rendering for the
deprecation window. Designer-side record lookups land in objectui.

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

Author: claude

.changeset/approval-approver-value-bindings.md

@@ -0,0 +1,26 @@
+---
+'@objectstack/spec': minor
+'@objectstack/plugin-approvals': patch
+'@objectstack/lint': minor
+---
+
+feat(approvals): declare approver value bindings; retire `queue` approver authoring (#3508)
+
+- `@objectstack/spec` exports `APPROVER_VALUE_BINDINGS` — the single declaration of how a
+  designer must source each approver row's `value`: `user`/`team`/`department`/`position`
+  are DATA-record lookups on the system directory objects (`sys_user` / `sys_team` /
+  `sys_business_unit` / `sys_position`; `position` commits the machine **name**, the
+  others the row id), `org_membership_level` is a closed enum (`ORG_MEMBERSHIP_LEVELS`),
+  `manager` is auto-resolved, `field` names a trigger-object field, and `queue` is
+  unsupported. Also exports `NON_AUTHORABLE_APPROVER_TYPES`.
+- `queue` approver type is deprecated-for-authoring: it still parses (stored flows keep
+  loading and rendering) but is published in `xEnumDeprecated`, so designers stop
+  offering it — the runtime has no queue resolution and the slot routes to nobody. The
+  approver `value` xRef now also maps `manager`, so designers can render its
+  auto-resolved state. No authored key is removed; nothing to migrate. If a flow carries
+  `{ type: 'queue' }`, replace it with `team` / `department` / `position` (or a concrete
+  `user`) until a real ownership-queue implementation lands.
+- `@objectstack/plugin-approvals` now warns at resolution time when a stored `queue`
+  approver is skipped.
+- `@objectstack/lint` adds `approval-approver-type-unsupported` (warning) for approver
+  types that are declared but not implemented by the runtime.

packages/lint/src/validate-approval-approvers.test.ts

@@ -6,6 +6,7 @@ import {
   APPROVAL_APPROVER_NOT_MEMBERSHIP_TIER,
   APPROVAL_APPROVER_TYPE_DEPRECATED,
   APPROVAL_APPROVER_TYPE_UNKNOWN,
+  APPROVAL_APPROVER_TYPE_UNSUPPORTED,
   APPROVAL_ESCALATION_REASSIGN_NO_TARGET,
   APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY,
 } from './validate-approval-approvers.js';
@@ -51,6 +52,20 @@ describe('validateApprovalApprovers', () => {
     expect(findings[0].hint).toContain("type: 'position'");
   });
 
+  // ── queue: declared-but-unenforced (#3508) ────────────────────────────────
+
+  it('flags a queue approver as unsupported — the runtime resolves it to nobody', () => {
+    const findings = validateApprovalApprovers(stackWithApprovers([
+      { type: 'queue', value: 'q_west' },
+      { type: 'user', value: 'u1' }, // a real route keeps the node off the empty-slate rule
+    ]));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(APPROVAL_APPROVER_TYPE_UNSUPPORTED);
+    expect(findings[0].severity).toBe('warning');
+    expect(findings[0].path).toBe('flows[0].nodes[1].config.approvers[0].type');
+    expect(findings[0].message).toContain('#3508');
+  });
+
   // ── the deprecated `role` spelling (ADR-0090 D3, #3133) ──────────────────
 
   it('flags the deprecated `role` spelling even when its value is a valid tier', () => {
@@ -77,14 +92,15 @@ describe('validateApprovalApprovers', () => {
     expect(findings[0].hint).not.toContain('org_membership_level, value');
   });
 
-  it('accepts the position approver type and the other spec types silently', () => {
+  it('accepts the position approver type and the other RESOLVABLE spec types silently', () => {
+    // `queue` is deliberately absent: it parses but the runtime never resolves
+    // it, so it now draws APPROVAL_APPROVER_TYPE_UNSUPPORTED (#3508).
     const findings = validateApprovalApprovers(stackWithApprovers([
       { type: 'position', value: 'sales_manager' },
       { type: 'user', value: 'u1' },
       { type: 'manager' },
       { type: 'department', value: 'bu_sales' },
       { type: 'field', value: 'owner_id' },
-      { type: 'queue', value: 'q1' },
       { type: 'team', value: 't1' },
     ]));
     expect(findings).toEqual([]);

packages/lint/src/validate-approval-approvers.ts

@@ -38,12 +38,14 @@ import {
   ApproverType,
   APPROVAL_NODE_TYPE,
   DEPRECATED_APPROVER_TYPES,
+  APPROVER_VALUE_BINDINGS,
   canonicalApproverType,
 } from '@objectstack/spec/automation';
 
 export const APPROVAL_APPROVER_NOT_MEMBERSHIP_TIER = 'approval-approver-not-membership-tier';
 export const APPROVAL_APPROVER_TYPE_DEPRECATED = 'approval-approver-type-deprecated';
 export const APPROVAL_APPROVER_TYPE_UNKNOWN = 'approval-approver-type-unknown';
+export const APPROVAL_APPROVER_TYPE_UNSUPPORTED = 'approval-approver-type-unsupported';
 export const APPROVAL_ESCALATION_REASSIGN_NO_TARGET = 'approval-escalation-reassign-no-target';
 export const APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY = 'approval-approvers-may-resolve-empty';
 
@@ -182,6 +184,25 @@ export function validateApprovalApprovers(stack: AnyRec): ApprovalApproverFindin
               `is removed in the next major.`,
             hint: `Author { type: '${fix}', value: '${value}' }. It resolves identically today.`,
           });
+        } else if (
+          (APPROVER_VALUE_BINDINGS as Record<string, { source: string }>)[canonical]?.source === 'unsupported'
+        ) {
+          // Declared-but-unenforced (#3508): the runtime has no resolution for
+          // this type — the slot degrades to an inert `type:value` literal and
+          // the request routes to nobody. Say it at authoring time instead of
+          // letting the request stall silently (Prime Directive #10).
+          findings.push({
+            severity: 'warning',
+            rule: APPROVAL_APPROVER_TYPE_UNSUPPORTED,
+            where,
+            path: `${path}.type`,
+            message:
+              `approver type '${type}' is declared but not implemented by the runtime (#3508) — ` +
+              `the slot resolves to nobody and the request stalls.`,
+            hint:
+              `Route to people the engine can expand: { type: 'team' | 'department' | 'position', ... }. ` +
+              `Queue approvers need a real ownership-queue implementation before they take effect.`,
+          });
         }
       }
 

packages/plugins/plugin-approvals/src/approval-service.test.ts

@@ -1699,3 +1699,28 @@ describe('ApprovalService — listActions attachments mapping (#3266)', () => {
     expect(approve?.attachments).toEqual(['file_a']);
   });
 });
+
+// #3508: `queue` is declared-but-unenforced — resolveApproverSpec has no queue
+// branch, so the spec value falls through to the dead `queue:<id>` literal.
+// The engine must at least WARN so operators can see the silent dead slot;
+// the spec marks the type non-authorable so designers stop offering it.
+describe('ApprovalService — queue approver is unresolved (#3508)', () => {
+  it('falls back to the dead literal and warns', async () => {
+    const engine = makeFakeEngine();
+    const warnings: any[] = [];
+    let n = 0;
+    const svc = new ApprovalService({
+      engine: engine as any,
+      clock: { now: () => new Date(1757000000000 + (n++) * 1000) },
+      logger: { warn: (msg: any, meta: any) => warnings.push([msg, meta]) },
+    });
+    const req = await svc.openNodeRequest(
+      { ...openInput([]), config: { approvers: [{ type: 'queue', value: 'q_west' }], behavior: 'first_response', lockRecord: false } },
+      CTX,
+    );
+    // No queue expansion exists: the slot is the raw `type:value` literal,
+    // which matches no real user id — the request routes to nobody.
+    expect(req.pending_approvers).toEqual(['queue:q_west']);
+    expect(warnings.some(([msg]) => String(msg).includes("'queue'") && String(msg).includes('#3508'))).toBe(true);
+  });
+});

packages/plugins/plugin-approvals/src/approval-service.ts

@@ -474,6 +474,18 @@ export class ApprovalService implements IApprovalService {
         }
       }
     } catch { /* fall through */ }
+    // #3508: `queue` is declared-but-unenforced — there is no queue branch
+    // above, so a queue approver always lands here and the `queue:<id>` slot
+    // routes to nobody. The spec marks it non-authorable
+    // (NON_AUTHORABLE_APPROVER_TYPES) so designers stop offering it; warn for
+    // the stored flows that still carry one, so the silent dead slot is at
+    // least visible to operators.
+    if (type === 'queue') {
+      this.logger?.warn?.(
+        `[approvals] approver type 'queue' is not implemented — the slot resolves to nobody (#3508)`,
+        { value: a.value },
+      );
+    }
     return [`${a.type}:${a.value}`];
   }
 

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

@@ -2,6 +2,9 @@ import { describe, it, expect } from 'vitest';
 import {
   ApproverType,
   DEPRECATED_APPROVER_TYPES,
+  NON_AUTHORABLE_APPROVER_TYPES,
+  APPROVER_VALUE_BINDINGS,
+  ORG_MEMBERSHIP_LEVELS,
   canonicalApproverType,
   APPROVAL_NODE_TYPE,
   ApprovalDecision,
@@ -45,15 +48,71 @@ describe('ApproverType', () => {
   // Cross-repo contract: the published node configSchema must carry
   // `xEnumDeprecated` on the approver type, or the Studio designer (objectui)
   // derives its dropdown straight from `enum` and keeps offering `role` — the
-  // exact trap ADR-0090 D3 retires. Renderers read this to omit deprecated
-  // members from pickers while still rendering a stored value.
-  it('publishes xEnumDeprecated on the approver type so pickers can drop `role`', () => {
+  // exact trap ADR-0090 D3 retires — and `queue`, which the runtime never
+  // resolves (#3508). Renderers read this to omit these members from pickers
+  // while still rendering a stored value.
+  it('publishes xEnumDeprecated on the approver type so pickers drop `role` and `queue`', () => {
     const schema = getApprovalNodeConfigJsonSchema() as any;
     const typeNode = schema?.properties?.approvers?.items?.properties?.type;
     expect(typeNode?.enum).toContain('role');            // still parses (back-compat)
+    expect(typeNode?.enum).toContain('queue');           // still parses (stored rows render)
     expect(typeNode?.enum).toContain('org_membership_level');
-    expect(typeNode?.xEnumDeprecated).toEqual(Object.keys(DEPRECATED_APPROVER_TYPES));
+    expect(typeNode?.xEnumDeprecated).toEqual([...NON_AUTHORABLE_APPROVER_TYPES]);
     expect(typeNode?.xEnumDeprecated).toContain('role');
+    expect(typeNode?.xEnumDeprecated).toContain('queue');
+  });
+
+  // #3508: queue is declared-but-unenforced. It stays parseable (stored flows
+  // keep loading) but is not authorable, and every deprecated spelling is
+  // non-authorable too.
+  it('marks queue non-authorable while keeping it parseable', () => {
+    expect(() => ApproverType.parse('queue')).not.toThrow();
+    expect(NON_AUTHORABLE_APPROVER_TYPES).toContain('queue');
+    for (const spelling of Object.keys(DEPRECATED_APPROVER_TYPES)) {
+      expect(NON_AUTHORABLE_APPROVER_TYPES).toContain(spelling);
+    }
+  });
+});
+
+// #3508: the designer contract for sourcing each approver row's `value`. The
+// record-backed kinds MUST match the engine's resolution semantics
+// (`plugin-approvals` resolveApproverSpec / expand*Users) — these assertions
+// pin the object names and stored fields the engine actually queries.
+describe('APPROVER_VALUE_BINDINGS (#3508)', () => {
+  it('covers every ApproverType member', () => {
+    for (const t of ApproverType.options) {
+      expect(APPROVER_VALUE_BINDINGS[t]).toBeDefined();
+    }
+  });
+
+  it('binds record-backed kinds to the objects and fields the engine queries', () => {
+    // applyOooDelegation(String(value)) — a sys_user id.
+    expect(APPROVER_VALUE_BINDINGS.user).toEqual({ source: 'record', object: 'sys_user', valueField: 'id' });
+    // find('sys_team_member', { team_id: value }) — a sys_team id.
+    expect(APPROVER_VALUE_BINDINGS.team).toEqual({ source: 'record', object: 'sys_team', valueField: 'id' });
+    // 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' });
+    // 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' });
+  });
+
+  it('keeps the non-record kinds off the record-lookup path', () => {
+    expect(APPROVER_VALUE_BINDINGS.org_membership_level).toEqual({ source: 'enum', values: ORG_MEMBERSHIP_LEVELS });
+    // The deprecated alias renders with the same control as its replacement.
+    expect(APPROVER_VALUE_BINDINGS.role).toEqual(APPROVER_VALUE_BINDINGS.org_membership_level);
+    expect(APPROVER_VALUE_BINDINGS.manager.source).toBe('auto');
+    expect(APPROVER_VALUE_BINDINGS.field.source).toBe('trigger-field');
+    expect(APPROVER_VALUE_BINDINGS.queue.source).toBe('unsupported');
+  });
+
+  it('publishes a manager mapping in the value xRef so designers can render auto-resolution', () => {
+    const schema = getApprovalNodeConfigJsonSchema() as any;
+    const valueNode = schema?.properties?.approvers?.items?.properties?.value;
+    expect(valueNode?.xRef?.map?.manager).toBe('manager');
+    // queue stays mapped so stored rows keep rendering during the window.
+    expect(valueNode?.xRef?.map?.queue).toBe('queue');
   });
 });