docs(adr): ADR-0056 — permission editing belongs in Studio, Setup keeps assignment

[os-zhuang]

What

Proposed ADR-0056 — the design for consolidating permission-set editing into Studio (Option B, the agreed direction). Epic: #2398.

Why

A permission set (sys_permission_set) has two editing surfaces over the same record:

• Setup renders it as six raw-JSON Field.textarea columns (object_permissions, field_permissions, system_permissions, row_level_security, tab_permissions, admin_scope).
• Studio has a structured PermissionMatrixEditor — but only for objects + fields.

Raw JSON authorization metadata is invisible to the ADR-0090 explain engine + publish linter, unvalidated at author time, duplicated (objects/fields authorable in both surfaces), and a silent-incident footgun (ADR-0049).

Decision (Option B)

Permission editing → Studio (structured editors). Setup keeps user management + permission-set assignment. Exception: system_permissions (includes studio.access) stays in Setup as a structured sys_capability multi-select — granting who-may-enter-Studio is an operator act.

sys_permission_set column	target editor	home
object/field_permissions	PermissionMatrixEditor (exists)	Studio
system_permissions	sys_capability multi-select (new)	Setup
admin_scope / row_level_security / tab_permissions	new structured editors	Studio

Status

Proposed — design-review PR. Open questions (RLS editor depth, deep-link UX/scope, legacy-JSON backward-compat) are listed in the ADR for reviewer input. Implementation is phased P1–P5 in #2398; P2 (capability picker) starts in a companion PR.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Jul 13, 2026 12:25am

[os-zhuang]

Direction reset — this ADR needs a revision pass before merge.

The design has moved from Option B (which kept system_permissionseditable in Setup as an exception) to a pure separation model:

• Studio = app developer designs the permission set — every facet (object, field, system capabilities, RLS, tab, admin_scope) via structured editors.
• Setup = system admin assigns users + sees each facet as a read-only summary with a "Design in Studio →" deep-link. No JSON, no [Object], nothing permission-shaped editable in Setup.
• The system_permissions-stays-in-Setup carve-out is dropped — capabilities are designed in Studio like every other facet.

Consolidated remaining work + the revised facet-by-facet table now live in the epic #2398 (rewritten to the pure model). Next step on this PR: update the ADR body (Decision + table) to match, then merge as the design of record.

[os-zhuang]

Revised to the pure model + marked Accepted (be3c08c). The Option-B system_permissions-in-Setup exception is dropped — all six facets are designed in the structured editor (reachable from both Studio and Setup's env-scope metadata route), and Setup renders every facet read-only (summary + Studio deep-link) plus assignment. Updated: decision, facet table, phase list (P1/P1b/P2/P3/P4 as shipped in #2403), resolved Q6, adopted A2, and added the metadata↔data-record projection-freshness gap as Q7 / a framework follow-up. This ADR now documents what shipped in #2403 (merged).