docs(spec): the permission set name describe and the permission sets page say one holder per namespace

.changeset/32758-permission-set-name-describe.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the permission set `name` describe says a set is identified by its package and name, one holder of a name per namespace
+
+Clause-②: no
+Metadata-protocol: none
+
+The `name` describe on `PermissionSetSchema` (`packages/spec/src/security/permission.zod.ts`) read "unique within the security catalog the environment serves", which stopped being true when a permission-set name became one holder per namespace (ADR-0150 D2/D9). It now says a set is identified by its package and name: packages of two namespaces may each hold a set of one name, while two packages of one namespace, a package with no namespace, a platform package (`base`, `system`, `sys`), the environment and the platform-requested `guest_portal` share one set of it. The generated reference page and the permission sets guide say the same; positions and capabilities keep one name per deployment. No schema, rule or runtime behaviour changes.

content/docs/permissions/permission-sets.mdx

@@ -434,8 +434,15 @@ posture, the platform operator. This has three author-visible consequences:
   Studio, or the clone door below) and edit the copy: a copy of a set an
   installed package ships lands in that package's paired `<package>.custom`,
   and package upgrades keep reaching the original. A set is never overridden
-  under its own name, not even from `.custom`: permission sets, positions and
-  capabilities hold one name per deployment (ADR-0146 D6). Every other set
+  under its own name, not even from `.custom`: a permission set takes no
+  override (ADR-0146 D6), and a set of the shipped set's name saved into the
+  pair is refused like an edit of the set itself (`403 NOT_OVERRIDABLE`). A
+  permission set is identified by its package and name (ADR-0150 D2), so a name
+  has one holder per namespace: packages of two namespaces may each ship a set
+  of one name, each granted by its own package and name, while two packages of
+  one namespace, a package with no namespace, a platform package (`base`,
+  `system`, `sys`) and the platform-requested `guest_portal` keep one holder.
+  Positions and capabilities keep one name per deployment. Every other set
   (one authored in this system, a clone, or one saved into a writable runtime package) is edited in place: the edit
   lands on its one stored definition.
 - **The API name is immutable after creation.** It is the definition's metadata

content/docs/references/security/permission.mdx

@@ -119,7 +119,7 @@ const result = AdminScopeSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **name** | `string` | ✅ | Permission set name, unique within the security catalog the environment serves (lowercase snake_case) |
+| **name** | `string` | ✅ | Permission set name (lowercase snake_case). A set is identified by its package and name: a name has one holder per namespace, so packages of two namespaces may each hold a set of one name, while two packages of one namespace, a package with no namespace, a platform package (base, system, sys), the environment and the platform-requested guest_portal share one set of it |
 | **label** | `string` | optional | Display label |
 | **description** | `string` | optional | Human-readable description shown in Setup |
 | **packageId** | `string` | optional | [ADR-0086 D3] Owning package id for a package-shipped set (absent = env-authored); a value that disagrees with the package that ships the set, or that it is saved into, is refused by the stack schema (defineStack, os validate, os build), the package registration, and the metadata save, restore and publish doors |

packages/spec/src/security/permission.zod.ts

@@ -1203,9 +1203,12 @@ export const PermissionSetSchema = lazySchema(() => strictObject(
   // the environment serves. This `describe()` is the SOURCE of the generated
   // reference page (`content/docs/references/security/permission.mdx`); its
   // earlier "unique per organization" (#8554) read the retired
-  // `sys_permission_set` row's index.
-  /** Permission set name, unique within the security catalog the environment serves */
-  name: SnakeCaseIdentifierSchema.describe('Permission set name, unique within the security catalog the environment serves (lowercase snake_case)'),
+  // `sys_permission_set` row's index. [ADR-0150 D2/D9] A set is identified by
+  // its package and name, so a name has one holder per namespace (the one
+  // predicate is `permissionSetHoldersMeet`, `@objectstack/core`); positions
+  // and capabilities keep one name per deployment.
+  /** Permission set name; a set is identified by its package and name, one holder of a name per namespace */
+  name: SnakeCaseIdentifierSchema.describe('Permission set name (lowercase snake_case). A set is identified by its package and name: a name has one holder per namespace, so packages of two namespaces may each hold a set of one name, while two packages of one namespace, a package with no namespace, a platform package (base, system, sys), the environment and the platform-requested guest_portal share one set of it'),
 
   /** Display label */
   label: z.string().optional().describe('Display label'),