Skip to content

Commit d14bbcf

Browse files
committed
docs(permissions): describe the packaged permission-set lock in "One authoritative store"
The section's first bullet still said a Setup edit of a packaged set becomes an environment overlay that takes effect, and its closing sentence still named an overlay as the way to narrow a packaged set. Since the packaged lock, that edit answers 403 NOT_OVERRIDABLE and stores nothing. The bullet now names the locked population (sets shipped in code: a package's declarations and the platform defaults), the clone remedy the refusal itself names, and the sets that stay editable in place (created here, clones, sets saved into a writable runtime package). The closing sentence now routes narrowing through clone-and-bind-in-its-place, and names narrowing the packaged set itself as the package author's change. Claude-Session: https://claude.ai/code/session_0115N1oNnQS5WqofZ2DzaT3q Co-authored-by: Claude <noreply@anthropic.com>
1 parent 117d34d commit d14bbcf

1 file changed

Lines changed: 15 additions & 10 deletions

File tree

‎content/docs/permissions/permission-sets.mdx‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -329,14 +329,16 @@ goes through the data engine) is redirected into a metadata write and the
329329
record is re-derived by an awaited projector, so the two can never drift. This
330330
has three author-visible consequences:
331331

332-
- **Editing any declared set through Setup — packaged sets included** becomes
333-
an environment overlay of that definition (the standard metadata
334-
customization): it genuinely takes effect, where a record-only edit
335-
previously displayed but never enforced. The row keeps its package
336-
provenance; the Studio layered view diffs the shipped baseline against your
337-
customization, and removing the overlay resets to the baseline. Note the
338-
trade every overlay makes: while an overlay pins a set, the vendor's later
339-
baseline changes don't take effect for it until you reset or re-author.
332+
- **A set shipped in code cannot be edited in the environment.** That is a set
333+
an installed package declares (a `*.permission.ts` file, a stack's
334+
`permissionSets`) or a platform default such as `member_default`. Editing it
335+
through Setup or the metadata API answers `403 NOT_OVERRIDABLE` and stores
336+
nothing. Clone it to a new name instead (the **Clone** action on the set, or
337+
`POST /api/v1/data/sys_permission_set` with a new name) and edit the clone:
338+
the clone is your organization's own set, and package upgrades keep reaching
339+
the original. Every other set (one created in this environment, a clone, or
340+
one saved into a writable runtime package) is edited in place: the edit
341+
lands on its one stored definition, and the record follows it.
340342
- **The API name is immutable after creation.** It is the definition's metadata
341343
identity, so the create form accepts it but the edit form locks it, and a
342344
rename through the data door is rejected. Clone the set to a new name instead.
@@ -348,8 +350,11 @@ has three author-visible consequences:
348350
packaged set entirely.
349351

350352
A cross-package job function needs no hand-authored cross-package set: bind
351-
each package's own sets to one **position** (the union model adds), and use an
352-
overlay where a packaged set must be narrowed.
353+
each package's own sets to one **position** (the union model adds). Where a
354+
packaged set grants too much, clone it, narrow the clone, and bind the clone
355+
in its place: restriction is done by not granting. Narrowing the packaged set
356+
itself is the package author's change: they edit the declaration in the
357+
package and re-publish it (ADR-0086 two-doors).
353358

354359
### Declared ≠ enforced — diagnosing a frozen package set
355360

0 commit comments

Comments
 (0)