@@ -0,0 +1,22 @@
+---
+'@objectstack/spec': patch
+'@objectstack/plugin-security': patch
+'@objectstack/plugin-auth': patch
+---
+
+feat(plugin-security,spec,plugin-auth)!: a delegated admin's write outside their own scope answers `403 DELEGATION_SCOPE_VIOLATION` with the gate's reason
+
+When a delegated administrator's write on `sys_user_position` or `sys_user_permission_set` fell outside their own `adminScope`, the delegated-administration gate knew exactly why ("business unit … is outside the delegated subtree", "… is not in the scope's allowlist"), but threw it as a plain `403 PERMISSION_DENIED`. A client could not tell it from a denial whose reason must stay hidden, so the console showed only its fixed "no permission" line.
+
+Clause-②: yes (widening: the ADR-0112 ledger registers `DELEGATION_SCOPE_VIOLATION` under `@objectstack/plugin-security`)
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling, object definition, stored row or stored shape is added, removed, renamed or re-shaped, and no exported declaration is removed or narrowed, so there is nothing for `objectstack migrate meta` to rewrite. What changes is the error code three of the gate's refusal reasons answer with: every write that was refused is still refused, with the same 403 status and the same reason, and every write that was admitted is still admitted. The remedy is on the consumer's side, reading `code`; never a rewrite of a package source or a stored row. The other categories are closed on facts: all three packages publish (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->
+
+**BREAKING** (a wire-answer change), shipped as `patch`: no metadata protocol kind moves.
+
+- **`@objectstack/plugin-security`.** Three reasons describe the caller's own delegated scope: a business unit outside the delegated subtree (the new row's or the existing row's), a permission set not in the scope's allowlist (one the position distributes, or one granted directly), and a target user outside the subtree. They now throw `DelegationScopeViolationError`: status `403`, code `DELEGATION_SCOPE_VIOLATION`, and the message `[Security] Outside your delegated scope: delegated 'OP' on OBJECT rejected — REASON (scope from 'SET').` Every other refusal of the gate keeps `403 PERMISSION_DENIED`, unchanged: the audience anchor, principal-less writes, `sys_member` being tenant-only, the organization boundary, plain CRUD with no scope, filter writes, delegation of duty, a scope without `manageAssignments`, an unanchored assignment, adminScope containment, a stored grant whose set is unnamed or not in the catalog, a grant naming no target user, and a target user with no business unit.
+- The message does not open with `[Security] Access denied`, which `mapDataError`, `isPermissionDeniedError` and the explain route read as `PERMISSION_DENIED`. The REST door (`mapDataError`) and the runtime dispatcher (`resolveThrownHttpError`) carry the new code as it was thrown.
+- **`@objectstack/spec`.** One ADR-0112 ledger row, `DELEGATION_SCOPE_VIOLATION`, registered as its own meaning. It is not a synonym of `PERMISSION_DENIED`, and no waiver is needed.
+- **`@objectstack/plugin-auth`.** The invitation door reads the new code as the gate's verdict too, so an invitation placed outside the issuer's scope still answers `403 INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE`, not the `503` read-fault answer.
+- For a client: a `403` with code `DELEGATION_SCOPE_VIOLATION` carries a message about the caller's own scope, which is safe to show. A `403 PERMISSION_DENIED` stays opaque. A client that matched `PERMISSION_DENIED` to catch these three refusals should also match the new code.
@@ -354,7 +354,7 @@ const result = AutomationApiErrorCode.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +345 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +346 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
 | **message** | `string` | ✅ | The inner refusal's own diagnostic text, verbatim, without the node and operation prefixes the run's failure text adds |
 
 ### Allowed Values: `FlowInnerRefusal.code`
@@ -460,6 +460,7 @@ const result = AutomationApiErrorCode.parse(data);
 * `DATASOURCE_ADMIN_ERROR`
 * `DEFAULT_RECORD_PAGE_CONFLICT`
 * `DELEGABLE_SCOPE_FAILED`
+* `DELEGATION_SCOPE_VIOLATION`
 * `DELETE_HOOK_RESULT_NOT_WRITE_SHAPE`
 * `DELIVERY_NEVER_SENT`
 * `DELIVERY_NOT_ELIGIBLE`
 
@@ -28,7 +28,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +345 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +346 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -141,6 +141,7 @@ const result = ApiErrorSchema.parse(data);
 * `DATASOURCE_ADMIN_ERROR`
 * `DEFAULT_RECORD_PAGE_CONFLICT`
 * `DELEGABLE_SCOPE_FAILED`
+* `DELEGATION_SCOPE_VIOLATION`
 * `DELETE_HOOK_RESULT_NOT_WRITE_SHAPE`
 * `DELIVERY_NEVER_SENT`
 * `DELIVERY_NOT_ELIGIBLE`
 
@@ -308,6 +308,7 @@ const result = ErrorCode.parse(data);
 * `DATASOURCE_ADMIN_ERROR`
 * `DEFAULT_RECORD_PAGE_CONFLICT`
 * `DELEGABLE_SCOPE_FAILED`
+* `DELEGATION_SCOPE_VIOLATION`
 * `DELETE_HOOK_RESULT_NOT_WRITE_SHAPE`
 * `DELIVERY_NEVER_SENT`
 * `DELIVERY_NOT_ELIGIBLE`
 
@@ -1052,6 +1052,34 @@ describe('AuthManager', () => {
       expect(String(err?.body?.message)).toMatch(/outside the delegated subtree/);
     });
 
+    it('issuance: the gate\'s scope-violation refusal (DELEGATION_SCOPE_VIOLATION) is the same verdict — 403 INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE, not an outage', async () => {
+      // [#26189] A refusal that describes the issuer's own delegated scope (a
+      // unit outside the subtree, a set off the allowlist) now carries its own
+      // code. It is still the gate's verdict, so the invitation answers what
+      // it answered before. Structural stand-in, as above.
+      const assertIssuable = vi.fn(async () => {
+        throw Object.assign(new Error("[Security] Outside your delegated scope: business unit 'bu_plant_b' is outside the delegated subtree"), {
+          name: 'DelegationScopeViolationError',
+          code: 'DELEGATION_SCOPE_VIOLATION',
+          status: 403,
+          statusCode: 403,
+        });
+      });
+      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable, apply: vi.fn() });
+      warnSpy.mockRestore();
+
+      const err = await placementAnswer(
+        hooks.beforeCreateInvitation({
+          invitation: PLACEMENT_INVITE,
+          inviter: { id: 'u_issuer' },
+          organization: { id: 'org-42' },
+        }),
+      );
+      expect(err?.statusCode).toBe(403);
+      expect(err?.body?.code).toBe('INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE');
+      expect(String(err?.body?.message)).toMatch(/outside the delegated subtree/);
+    });
+
     it('issuance: a store fault out of the placement check is an outage (503 SERVICE_UNAVAILABLE), not a scope refusal', async () => {
       // [#24243] `assertIssuable` resolves the issuer's grants from the store
       // BEFORE the gate runs; a store that cannot answer throws there, as the
 
@@ -1391,12 +1391,17 @@ export const ORGANIZATION_SLUG_LOCKED_CODE: RegisteredErrorCode = 'ORGANIZATION_
  * [#24243] Is this throw out of `assertIssuable` the delegated-administration
  * gate's own refusal? The service's contract is that the gate refuses with its
  * `PermissionDeniedError` (`invitation-placement.ts`), whose ADR-0112 code is
- * `PERMISSION_DENIED`. Read by that code, structurally, because plugin-auth has
- * no runtime dependency on plugin-security (see
+ * `PERMISSION_DENIED`, or, when the reason describes the issuer's own scope (a
+ * unit outside the subtree, a set off the allowlist), its
+ * `DelegationScopeViolationError`, code `DELEGATION_SCOPE_VIOLATION` (#26189).
+ * Both are the gate's verdict. Read by code, structurally, because plugin-auth
+ * has no runtime dependency on plugin-security (see
  * {@link InvitationPlacementServiceLike}).
  */
 export function isInvitationPlacementGateRefusal(err: unknown): boolean {
-  return !!err && typeof err === 'object' && (err as { code?: unknown }).code === 'PERMISSION_DENIED';
+  if (!err || typeof err !== 'object') return false;
+  const code = (err as { code?: unknown }).code;
+  return code === 'PERMISSION_DENIED' || code === 'DELEGATION_SCOPE_VIOLATION';
 }
 
 /**
 
@@ -195,7 +195,8 @@ describe('[ADR-0090 D12 / ADR-0105 D8 × ADR-0068 D2] every branch of the delega
           for (const name of RESERVED_IDENTITY_NAMES) {
             const r = await assign(h, context, name);
             const gatedFirst = branch === 'delegated' && name === BUILTIN_IDENTITY_ORG_EXTERNAL;
-            expect([r.status, r.code], `${name}: ${r.message}`).toEqual(gatedFirst ? [403, 'PERMISSION_DENIED'] : [400, 'VALIDATION_FAILED']);
+            // [#26189] The gate refuses it because its set is off the caller's allowlist: a scope violation, its own code.
+            expect([r.status, r.code], `${name}: ${r.message}`).toEqual(gatedFirst ? [403, 'DELEGATION_SCOPE_VIOLATION'] : [400, 'VALIDATION_FAILED']);
             expect(await storedRows(h, name), `${name} stored nothing`).toHaveLength(0);
           }
 
 
@@ -114,7 +114,8 @@ async function refusal(p: Promise<unknown>): Promise<any> {
 describe('DelegatedAdminGate — a position distributes what its definition declares', () => {
   it('a binding declared only on the definition is judged: a non-allowlisted set refuses the assignment', async () => {
     const err = await refusal(assign(gateOver(bindTestSecurityCatalog(makeQl(), CATALOG)), 'mixed'));
-    expect(err).toMatchObject({ code: 'PERMISSION_DENIED', statusCode: 403 });
+    // [#26189] A set off the caller's allowlist is a scope violation: its own code.
+    expect(err).toMatchObject({ code: 'DELEGATION_SCOPE_VIOLATION', statusCode: 403 });
     expect(String(err.message)).toMatch(/position 'mixed' distributes permission set 'finance_admin', which is not in the scope's allowlist/);
   });
Original file line number	Diff line number	Diff line change
`@@ -195,7 +195,8 @@ describe('[ADR-0090 D12 / ADR-0105 D8 × ADR-0068 D2] every branch of the delega`
`195`	`195`	`for (const name of RESERVED_IDENTITY_NAMES) {`
`196`	`196`	`const r = await assign(h, context, name);`
`197`	`197`	`const gatedFirst = branch === 'delegated' && name === BUILTIN_IDENTITY_ORG_EXTERNAL;`
`198`		- expect([r.status, r.code], `${name}: ${r.message}`).toEqual(gatedFirst ? [403, 'PERMISSION_DENIED'] : [400, 'VALIDATION_FAILED']);
	`198`	`+ // [#26189] The gate refuses it because its set is off the caller's allowlist: a scope violation, its own code.`
	`199`	+ expect([r.status, r.code], `${name}: ${r.message}`).toEqual(gatedFirst ? [403, 'DELEGATION_SCOPE_VIOLATION'] : [400, 'VALIDATION_FAILED']);
`199`	`200`	expect(await storedRows(h, name), `${name} stored nothing`).toHaveLength(0);
`200`	`201`	`}`
`201`	`202`