@objectstack/plugin-approvals 12.6.0 → 14.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/plugin-approvals@12.6.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
+> @objectstack/plugin-approvals@14.3.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     120.29 KB
-ESM dist/index.mjs.map 215.92 KB
-ESM ⚡️ Build success in 284ms
-CJS dist/index.js     121.96 KB
-CJS dist/index.js.map 217.12 KB
-CJS ⚡️ Build success in 285ms
+CJS dist/index.js     123.99 KB
+CJS dist/index.js.map 220.47 KB
+CJS ⚡️ Build success in 241ms
+ESM dist/index.mjs     122.33 KB
+ESM dist/index.mjs.map 219.27 KB
+ESM ⚡️ Build success in 244ms
 DTS Build start
-DTS ⚡️ Build success in 24925ms
-DTS dist/index.d.mts 381.04 KB
-DTS dist/index.d.ts  381.04 KB
+DTS ⚡️ Build success in 28424ms
+DTS dist/index.d.mts 382.64 KB
+DTS dist/index.d.ts  382.64 KB

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # @objectstack/plugin-approvals
 
+## 14.3.0
+
+### Patch Changes
+
+- Updated dependencies [2a71f48]
+- Updated dependencies [02f6af4]
+- Updated dependencies [c1064f1]
+  - @objectstack/platform-objects@14.3.0
+  - @objectstack/spec@14.3.0
+  - @objectstack/core@14.3.0
+  - @objectstack/formula@14.3.0
+  - @objectstack/metadata-core@14.3.0
+
+## 14.2.0
+
+### Patch Changes
+
+- Updated dependencies [ac8f029]
+- Updated dependencies [4ab9958]
+  - @objectstack/spec@14.2.0
+  - @objectstack/platform-objects@14.2.0
+  - @objectstack/core@14.2.0
+  - @objectstack/formula@14.2.0
+  - @objectstack/metadata-core@14.2.0
+
+## 14.1.0
+
+### Minor Changes
+
+- 5a8465f: SLA escalation `escalateTo` is position-first (ADR-0090 D3 follow-up to the `position` approver type).
+
+  - **spec**: `ApprovalEscalationSchema.escalateTo` is documented as a position machine name or a
+    specific user id (was "User id, role, or manager level" — the same pre-D3 'role' trap the
+    `position` approver type fixed); the Studio xRef picker kind moves `role` → `position`.
+  - **plugin-approvals**: on escalation, `escalateTo` now expands position holders via
+    `sys_user_position` ∪ the `sys_member.role` transition source (ADR-0057 D4) for both the
+    `reassign` approver hand-off and the `notify` audience. An empty expansion falls back to
+    treating the value as a literal user id, so configs naming a specific user keep working
+    unchanged. The audit trail keeps the authored target.
+  - **lint**: new `approval-escalation-reassign-no-target` warning — `escalation.action: 'reassign'`
+    with no `escalateTo` silently degrades to a notify at runtime; the fix-it prescribes a position
+    or user id target (or `action: 'notify'`).
+
+### Patch Changes
+
+- Updated dependencies [5a8465f]
+- Updated dependencies [7f8620b]
+- Updated dependencies [82ba3a6]
+  - @objectstack/spec@14.1.0
+  - @objectstack/core@14.1.0
+  - @objectstack/formula@14.1.0
+  - @objectstack/metadata-core@14.1.0
+  - @objectstack/platform-objects@14.1.0
+
+## 14.0.0
+
+### Minor Changes
+
+- 216fa9a: Add a `position` approver type so approvals can route to org positions (ADR-0090 D3 fallout).
+
+  Post ADR-0090 D3 the `role` approver type resolves against the better-auth org-membership
+  tier (`sys_member.role`: `owner`/`admin`/`member`) — it was never a position. Downstream
+  apps that authored `{ type: 'role', value: 'sales_manager' }` silently routed approvals to
+  nobody. Now:
+
+  - **spec**: `ApproverType` gains `'position'` — `value` is the position machine name; the
+    approver expands to its holders via `sys_user_position`. Authoring guidance: keep
+    `type: 'role'` ONLY for membership tiers; for org positions use
+    `{ type: 'position', value: '<position_name>' }` (one-line fix for the mismatch above).
+  - **plugin-approvals**: the engine resolves `position` approvers via `sys_user_position` ∪
+    the `sys_member.role` transition source (same semantics as `PositionGraphService` in
+    plugin-sharing). The `department` approver type is now honored by its spec spelling
+    (previously only the off-spec `business_unit`/`bu` dialect matched).
+  - **lint**: new `validateApprovalApprovers` rule — `approval-role-not-membership-tier`
+    warns when a `role` approver's value is not a membership tier and prescribes the
+    `position` rewrite; `approval-approver-type-unknown` flags off-spec approver types
+    (with a `business_unit` → `department` fix-it). Wired into `os lint`.
+
+### Patch Changes
+
+- Updated dependencies [0a8e685]
+- Updated dependencies [afa8115]
+- Updated dependencies [80f12ca]
+- Updated dependencies [332b711]
+- Updated dependencies [e2fa074]
+- Updated dependencies [23c8668]
+- Updated dependencies [29f017d]
+- Updated dependencies [216fa9a]
+- Updated dependencies [6c22b12]
+- Updated dependencies [d0531c4]
+- Updated dependencies [cff5aac]
+  - @objectstack/spec@14.0.0
+  - @objectstack/platform-objects@14.0.0
+  - @objectstack/core@14.0.0
+  - @objectstack/formula@14.0.0
+  - @objectstack/metadata-core@14.0.0
+
+## 13.0.0
+
+### Patch Changes
+
+- Updated dependencies [6d83431]
+- Updated dependencies [01917c2]
+- Updated dependencies [b271691]
+- Updated dependencies [a5a1e41]
+- Updated dependencies [466adf6]
+- Updated dependencies [5be00c3]
+- Updated dependencies [466adf6]
+- Updated dependencies [2bee609]
+- Updated dependencies [9fa84f9]
+- Updated dependencies [fc7e7f7]
+  - @objectstack/spec@13.0.0
+  - @objectstack/core@13.0.0
+  - @objectstack/formula@13.0.0
+  - @objectstack/platform-objects@13.0.0
+  - @objectstack/metadata-core@13.0.0
+
 ## 12.6.0
 
 ### Patch Changes
@@ -355,8 +472,8 @@
   ADR-0057 — ERP authorization core. Adds permission-grant access DEPTH
   (`own`/`own_and_reports`/`unit`/`unit_and_below`/`org`), renames `sys_department`
   → `sys_business_unit` (no aliases — see BREAKING above), introduces the platform-owned
-  `sys_user_role` assignment, and seeds stack-declared `roles`/`sharingRules` into
-  `sys_role`/`sys_sharing_rule` at boot (closes #2077). Hierarchy-relative scopes are
+  `sys_user_position` assignment, and seeds stack-declared `roles`/`sharingRules` into
+  `sys_position`/`sys_sharing_rule` at boot (closes #2077). Hierarchy-relative scopes are
   delegated to a pluggable `IHierarchyScopeResolver` (open edition fails closed to
   owner-only; `defineStack` errors without `requires: ['hierarchy-security']`). Also
   fixes a latent over-grant where `engine.find({ filter })` was ignored (driver reads
@@ -765,8 +882,8 @@
     `i18n.loadTranslations` (the i18n service is optional — load is best-effort).
     - `plugin-webhooks` ← `sys_webhook`, `sys_webhook_delivery`
     - `plugin-approvals` ← `sys_approval_request`, `sys_approval_action`
-    - `plugin-security` ← `sys_role`, `sys_permission_set`,
-      `sys_user_permission_set`, `sys_role_permission_set`
+    - `plugin-security` ← `sys_position`, `sys_permission_set`,
+      `sys_user_permission_set`, `sys_position_permission_set`
     - `plugin-sharing` ← `sys_record_share`, `sys_sharing_rule`, `sys_share_link`
   - `@objectstack/platform-objects` translation bundles are regenerated to drop
     those objects' keys (its extract config already excluded them); all other

package/dist/index.d.mts

@@ -320,7 +320,12 @@ declare const SysApprovalRequest: Omit<{
     access?: {
         default: "public" | "private";
     } | undefined;
-    requiredPermissions?: string[] | undefined;
+    requiredPermissions?: string[] | {
+        read?: string[] | undefined;
+        create?: string[] | undefined;
+        update?: string[] | undefined;
+        delete?: string[] | undefined;
+    } | undefined;
     softDelete?: {
         enabled: boolean;
         field: string;
@@ -666,9 +671,10 @@ declare const SysApprovalRequest: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "create" | "import" | "delete" | "get" | "update" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("search" | "create" | "import" | "delete" | "update" | "get" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
-    sharingModel?: "full" | "private" | "read" | "public_read" | "public_read_write" | "controlled_by_parent" | "read_write" | undefined;
+    sharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
+    externalSharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
     publicSharing?: {
         enabled: boolean;
         allowedAudiences?: ("email" | "public" | "link_only" | "signed_in")[] | undefined;
@@ -4507,7 +4513,12 @@ declare const SysApprovalAction: Omit<{
     access?: {
         default: "public" | "private";
     } | undefined;
-    requiredPermissions?: string[] | undefined;
+    requiredPermissions?: string[] | {
+        read?: string[] | undefined;
+        create?: string[] | undefined;
+        update?: string[] | undefined;
+        delete?: string[] | undefined;
+    } | undefined;
     softDelete?: {
         enabled: boolean;
         field: string;
@@ -4853,9 +4864,10 @@ declare const SysApprovalAction: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "create" | "import" | "delete" | "get" | "update" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("search" | "create" | "import" | "delete" | "update" | "get" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
-    sharingModel?: "full" | "private" | "read" | "public_read" | "public_read_write" | "controlled_by_parent" | "read_write" | undefined;
+    sharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
+    externalSharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
     publicSharing?: {
         enabled: boolean;
         allowedAudiences?: ("email" | "public" | "link_only" | "signed_in")[] | undefined;
@@ -7028,7 +7040,12 @@ declare const SysApprovalApprover: Omit<{
     access?: {
         default: "public" | "private";
     } | undefined;
-    requiredPermissions?: string[] | undefined;
+    requiredPermissions?: string[] | {
+        read?: string[] | undefined;
+        create?: string[] | undefined;
+        update?: string[] | undefined;
+        delete?: string[] | undefined;
+    } | undefined;
     softDelete?: {
         enabled: boolean;
         field: string;
@@ -7374,9 +7391,10 @@ declare const SysApprovalApprover: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "create" | "import" | "delete" | "get" | "update" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("search" | "create" | "import" | "delete" | "update" | "get" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
-    sharingModel?: "full" | "private" | "read" | "public_read" | "public_read_write" | "controlled_by_parent" | "read_write" | undefined;
+    sharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
+    externalSharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
     publicSharing?: {
         enabled: boolean;
         allowedAudiences?: ("email" | "public" | "link_only" | "signed_in")[] | undefined;
@@ -8442,8 +8460,8 @@ declare const SysApprovalApprover: Omit<{
  * `approve` / `reject` edge.
  *
  * This service owns the durable approval *state* — `sys_approval_request` /
- * `sys_approval_action`, approver resolution (team / department / role /
- * manager graph), and the optional status-field mirror — plus the decision
+ * `sys_approval_action`, approver resolution (team / department / position /
+ * role / manager graph), and the optional status-field mirror — plus the decision
  * API. It does not author processes, submit, or walk multi-step machinery
  * anymore; that orchestration lives on the one automation engine.
  */
@@ -8548,16 +8566,20 @@ declare class ApprovalService implements IApprovalService {
     private loadPendingRow;
     /**
      * Expand the approvers on an Approval node into user IDs by querying the
-     * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-     * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-     * produce nothing — so existing fixtures and flows that rely on substring
-     * matching keep working.
+     * graph tables for `team:` / `department:` / `position:` / `role:` /
+     * `manager:` approver types. Falls back to a prefixed literal
+     * (`type:value`) when graph lookups produce nothing — so existing fixtures
+     * and flows that rely on substring matching keep working.
      *
      * **Graph semantics:**
      *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
      *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
      *                    → members of every descendant via `sys_business_unit_member`
-     *   - `role`       → users with `sys_member.role = value` in tenant
+     *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+     *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+     *   - `role`       → users with `sys_member.role = value` in tenant — the
+     *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+     *                    position; author `position` for org positions
      *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
      *   - `field`      → literal user id stored in `record[value]`
      *   - `user`       → literal value
@@ -8567,6 +8589,16 @@ declare class ApprovalService implements IApprovalService {
     private expandTeamUsers;
     /** Recursive department — walks `sys_business_unit.parent_business_unit_id`. */
     private expandBusinessUnitUsers;
+    /**
+     * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+     * assignment table, keyed by the position's machine name (ADR-0057 D4),
+     * unioned with the better-auth membership string (`sys_member.role`) as a
+     * transition source — the same semantics as `PositionGraphService` in
+     * `plugin-sharing`, so an approval routes to exactly the users the sharing
+     * engine would expand for the same position.
+     */
+    private expandPositionUsers;
+    /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
     private expandRoleUsers;
     private lookupManager;
     /** Mirror a request status onto a business-object field, if configured. */

package/dist/index.d.ts

@@ -320,7 +320,12 @@ declare const SysApprovalRequest: Omit<{
     access?: {
         default: "public" | "private";
     } | undefined;
-    requiredPermissions?: string[] | undefined;
+    requiredPermissions?: string[] | {
+        read?: string[] | undefined;
+        create?: string[] | undefined;
+        update?: string[] | undefined;
+        delete?: string[] | undefined;
+    } | undefined;
     softDelete?: {
         enabled: boolean;
         field: string;
@@ -666,9 +671,10 @@ declare const SysApprovalRequest: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "create" | "import" | "delete" | "get" | "update" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("search" | "create" | "import" | "delete" | "update" | "get" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
-    sharingModel?: "full" | "private" | "read" | "public_read" | "public_read_write" | "controlled_by_parent" | "read_write" | undefined;
+    sharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
+    externalSharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
     publicSharing?: {
         enabled: boolean;
         allowedAudiences?: ("email" | "public" | "link_only" | "signed_in")[] | undefined;
@@ -4507,7 +4513,12 @@ declare const SysApprovalAction: Omit<{
     access?: {
         default: "public" | "private";
     } | undefined;
-    requiredPermissions?: string[] | undefined;
+    requiredPermissions?: string[] | {
+        read?: string[] | undefined;
+        create?: string[] | undefined;
+        update?: string[] | undefined;
+        delete?: string[] | undefined;
+    } | undefined;
     softDelete?: {
         enabled: boolean;
         field: string;
@@ -4853,9 +4864,10 @@ declare const SysApprovalAction: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "create" | "import" | "delete" | "get" | "update" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("search" | "create" | "import" | "delete" | "update" | "get" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
-    sharingModel?: "full" | "private" | "read" | "public_read" | "public_read_write" | "controlled_by_parent" | "read_write" | undefined;
+    sharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
+    externalSharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
     publicSharing?: {
         enabled: boolean;
         allowedAudiences?: ("email" | "public" | "link_only" | "signed_in")[] | undefined;
@@ -7028,7 +7040,12 @@ declare const SysApprovalApprover: Omit<{
     access?: {
         default: "public" | "private";
     } | undefined;
-    requiredPermissions?: string[] | undefined;
+    requiredPermissions?: string[] | {
+        read?: string[] | undefined;
+        create?: string[] | undefined;
+        update?: string[] | undefined;
+        delete?: string[] | undefined;
+    } | undefined;
     softDelete?: {
         enabled: boolean;
         field: string;
@@ -7374,9 +7391,10 @@ declare const SysApprovalApprover: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "create" | "import" | "delete" | "get" | "update" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("search" | "create" | "import" | "delete" | "update" | "get" | "upsert" | "list" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
-    sharingModel?: "full" | "private" | "read" | "public_read" | "public_read_write" | "controlled_by_parent" | "read_write" | undefined;
+    sharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
+    externalSharingModel?: "private" | "public_read" | "public_read_write" | "controlled_by_parent" | undefined;
     publicSharing?: {
         enabled: boolean;
         allowedAudiences?: ("email" | "public" | "link_only" | "signed_in")[] | undefined;
@@ -8442,8 +8460,8 @@ declare const SysApprovalApprover: Omit<{
  * `approve` / `reject` edge.
  *
  * This service owns the durable approval *state* — `sys_approval_request` /
- * `sys_approval_action`, approver resolution (team / department / role /
- * manager graph), and the optional status-field mirror — plus the decision
+ * `sys_approval_action`, approver resolution (team / department / position /
+ * role / manager graph), and the optional status-field mirror — plus the decision
  * API. It does not author processes, submit, or walk multi-step machinery
  * anymore; that orchestration lives on the one automation engine.
  */
@@ -8548,16 +8566,20 @@ declare class ApprovalService implements IApprovalService {
     private loadPendingRow;
     /**
      * Expand the approvers on an Approval node into user IDs by querying the
-     * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-     * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-     * produce nothing — so existing fixtures and flows that rely on substring
-     * matching keep working.
+     * graph tables for `team:` / `department:` / `position:` / `role:` /
+     * `manager:` approver types. Falls back to a prefixed literal
+     * (`type:value`) when graph lookups produce nothing — so existing fixtures
+     * and flows that rely on substring matching keep working.
      *
      * **Graph semantics:**
      *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
      *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
      *                    → members of every descendant via `sys_business_unit_member`
-     *   - `role`       → users with `sys_member.role = value` in tenant
+     *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+     *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+     *   - `role`       → users with `sys_member.role = value` in tenant — the
+     *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+     *                    position; author `position` for org positions
      *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
      *   - `field`      → literal user id stored in `record[value]`
      *   - `user`       → literal value
@@ -8567,6 +8589,16 @@ declare class ApprovalService implements IApprovalService {
     private expandTeamUsers;
     /** Recursive department — walks `sys_business_unit.parent_business_unit_id`. */
     private expandBusinessUnitUsers;
+    /**
+     * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+     * assignment table, keyed by the position's machine name (ADR-0057 D4),
+     * unioned with the better-auth membership string (`sys_member.role`) as a
+     * transition source — the same semantics as `PositionGraphService` in
+     * `plugin-sharing`, so an approval routes to exactly the users the sharing
+     * engine would expand for the same position.
+     */
+    private expandPositionUsers;
+    /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
     private expandRoleUsers;
     private lookupManager;
     /** Mirror a request status onto a business-object field, if configured. */

package/dist/index.js

@@ -1029,7 +1029,7 @@ var ESCALATION_JOB_NAME = "approvals-sla-escalation";
 var ESCALATION_SCAN_INTERVAL_MS = 5 * 60 * 1e3;
 var SLA_ACTOR_ID = "system:sla";
 var ACTION_TOKEN_TTL_MS = 72 * 60 * 60 * 1e3;
-var SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] };
+var SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] };
 function uid(prefix) {
   const g = globalThis;
   if (g.crypto?.randomUUID) return `${prefix}_${g.crypto.randomUUID()}`;
@@ -1152,16 +1152,20 @@ var _ApprovalService = class _ApprovalService {
   }
   /**
    * Expand the approvers on an Approval node into user IDs by querying the
-   * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-   * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-   * produce nothing — so existing fixtures and flows that rely on substring
-   * matching keep working.
+   * graph tables for `team:` / `department:` / `position:` / `role:` /
+   * `manager:` approver types. Falls back to a prefixed literal
+   * (`type:value`) when graph lookups produce nothing — so existing fixtures
+   * and flows that rely on substring matching keep working.
    *
    * **Graph semantics:**
    *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
    *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
    *                    → members of every descendant via `sys_business_unit_member`
-   *   - `role`       → users with `sys_member.role = value` in tenant
+   *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+   *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+   *   - `role`       → users with `sys_member.role = value` in tenant — the
+   *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+   *                    position; author `position` for org positions
    *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
    *   - `field`      → literal user id stored in `record[value]`
    *   - `user`       → literal value
@@ -1186,12 +1190,18 @@ var _ApprovalService = class _ApprovalService {
             for (const u of users) out.push(u);
             continue;
           }
-        } else if (a.type === "business_unit" || a.type === "bu") {
+        } else if (a.type === "department" || a.type === "business_unit" || a.type === "bu") {
           const users = await this.expandBusinessUnitUsers(String(a.value), organizationId);
           if (users.length) {
             for (const u of users) out.push(u);
             continue;
           }
+        } else if (a.type === "position") {
+          const users = await this.expandPositionUsers(String(a.value), organizationId);
+          if (users.length) {
+            for (const u of users) out.push(u);
+            continue;
+          }
         } else if (a.type === "role") {
           const users = await this.expandRoleUsers(String(a.value), organizationId);
           if (users.length) {
@@ -1278,6 +1288,36 @@ var _ApprovalService = class _ApprovalService {
     }
     return Array.from(new Set((rows ?? []).map((r) => String(r.user_id ?? "")).filter(Boolean)));
   }
+  /**
+   * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+   * assignment table, keyed by the position's machine name (ADR-0057 D4),
+   * unioned with the better-auth membership string (`sys_member.role`) as a
+   * transition source — the same semantics as `PositionGraphService` in
+   * `plugin-sharing`, so an approval routes to exactly the users the sharing
+   * engine would expand for the same position.
+   */
+  async expandPositionUsers(positionName, organizationId) {
+    if (!positionName) return [];
+    const users = /* @__PURE__ */ new Set();
+    const filter = { position: positionName };
+    if (organizationId) filter.organization_id = organizationId;
+    try {
+      const rows = await this.engine.find("sys_user_position", {
+        filter,
+        fields: ["user_id"],
+        limit: 1e4,
+        context: SYSTEM_CTX
+      });
+      for (const r of rows ?? []) {
+        const uid2 = String(r.user_id ?? "");
+        if (uid2) users.add(uid2);
+      }
+    } catch {
+    }
+    for (const uid2 of await this.expandRoleUsers(positionName, organizationId)) users.add(uid2);
+    return Array.from(users);
+  }
+  /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
   async expandRoleUsers(roleName, organizationId) {
     if (!roleName) return [];
     const filter = { role: roleName };
@@ -2199,6 +2239,15 @@ var _ApprovalService = class _ApprovalService {
     const escalateTo = typeof esc2.escalateTo === "string" && esc2.escalateTo.trim() ? esc2.escalateTo.trim() : void 0;
     const now = this.clock.now().toISOString();
     const pending = csvSplit(raw.pending_approvers);
+    let escalatees = [];
+    if (escalateTo) {
+      try {
+        escalatees = await this.expandPositionUsers(escalateTo, raw.organization_id ?? null);
+      } catch {
+        escalatees = [];
+      }
+      if (!escalatees.length) escalatees = [escalateTo];
+    }
     await this.engine.insert("sys_approval_action", {
       id: uid("aact"),
       request_id: raw.id,
@@ -2210,16 +2259,16 @@ var _ApprovalService = class _ApprovalService {
       comment: `${action}${escalateTo ? ` \u2192 ${escalateTo}` : ""}`,
       created_at: now
     }, { context: SYSTEM_CTX });
-    if (action === "reassign" && escalateTo) {
+    if (action === "reassign" && escalatees.length) {
       await this.engine.update("sys_approval_request", {
         id: raw.id,
-        pending_approvers: escalateTo,
+        pending_approvers: escalatees.join(","),
         updated_at: now
       }, { context: SYSTEM_CTX });
-      await this.syncApproverIndex(raw.id, [escalateTo], raw.organization_id ?? null, now);
+      await this.syncApproverIndex(raw.id, escalatees, raw.organization_id ?? null, now);
       await this.notify({
         topic: "approval.escalated",
-        audience: [escalateTo],
+        audience: escalatees,
         actorId: SLA_ACTOR_ID,
         source: { object: "sys_approval_request", id: raw.id },
         payload: {
@@ -2237,7 +2286,7 @@ var _ApprovalService = class _ApprovalService {
     } else {
       await this.notify({
         topic: "approval.sla_breached",
-        audience: [...pending, ...escalateTo ? [escalateTo] : []],
+        audience: [...pending, ...escalatees],
         actorId: SLA_ACTOR_ID,
         source: { object: "sys_approval_request", id: raw.id },
         payload: {
@@ -2937,7 +2986,7 @@ function unbindAllHooks(engine) {
 
 // src/approval-node.ts
 var import_automation2 = require("@objectstack/spec/automation");
-var SYSTEM_CTX2 = { isSystem: true, roles: [], permissions: [] };
+var SYSTEM_CTX2 = { isSystem: true, positions: [], permissions: [] };
 function registerApprovalNode(automation, service, logger) {
   automation.registerNodeExecutor({
     type: import_automation2.APPROVAL_NODE_TYPE,