docs(adr): ADR-0090 — Permission Model v2: concept convergence, final naming, AI-authoring safety#2695
Merged
Merged
Conversation
…naming, AI-authoring safety Records the eight decisions converging the authorization model ahead of launch: OWD defaults to private for custom objects (D1), the Profile concept is removed (D2), sys_role and friends are renamed to position with "role" as a lint-enforced forbidden word (D3), the OWD enum drops its legacy aliases (D4), a built-in `everyone` position carries default grants (D5), an explain engine plus access-matrix snapshot gate is promoted to P0 (D6), security-domain publishes get a linter and tiered human gates (D7), and teams are confirmed as sharing recipients that never carry capability (D8). Ships with the companion reference docs/design/permission-model.md — the maintained source of truth for the decided model (concepts, evaluation pipeline, CRM worked example, AI-safety layers, glossary). Supersedes ADR-0056 D7 (default-profile fallback) and ADR-0057 D5/D7 alias clauses (pre-launch one-step renames, no compatibility layers). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
13 tasks
…my, external OWD, delegated admin
Extends the proposed ADR with four decisions raised in review discussion:
D9 — audience anchors: builtin `guest` position joins `everyone`; packages
suggest bindings, never ship shared builtin sets; deliberately no
admin anchor (superuser wildcard already covers new packages).
D10 — principal taxonomy (kind: human|agent|service|guest|system,
audience: internal|external, onBehalfOf). AI agents act on the
INTERSECTION of their own grants and their delegator's, under a
lint-enforced ceiling, with human co-sign for destructive ops.
D11 — external OWD dimension: optional `externalSharingModel`, default
private, validated external <= internal; depth axis inapplicable
to externals.
D12 — delegated administration: admin scopes (BU subtree + assignable-set
allowlist + no self-escalation) so subsidiary admins run their own
units without tenant-wide power.
Non-goals section restructured into deliberate non-goals + six named
follow-up ADRs (grant lifecycle/recertification, SoD, scale hardening,
dimension restrictions, ALM promotion, portal identity). Phasing updated:
P1 additionally lands the ctx principal shape and externalSharingModel
spec shape; P2 becomes both audience anchors; P3 adds delegated admin.
Companion design doc gains plain-language sections: "Who is calling"
(principal kinds, the agent overlap rule, guardrails), "Running a large
organization" (delegated admin worked example), external OWD dial, guest
position, and glossary entries.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H
github-actions
Bot
added
the
documentation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H
os-zhuang
marked this pull request as ready for review
July 9, 2026 01:07
This was referenced Jul 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two documents, deciding and describing the converged permission model ahead of launch:
docs/adr/0090-permission-model-v2-concept-convergence.md— the decision record (Status: Proposed). Twelve decisions:private; the unset state ceases to exist (existing metadata grandfathered by explicit stamping, no silent behavior change)isProfiledeleted fromPermissionSetSchema);isDefaultnarrows to an install-time package suggestionsys_role/sys_user_role/sys_role_permission_set/ctx.roles[]/current_user.rolerenamed toposition; "role" becomes a lint-enforced reserved-forbidden word (single exception: better-auth'ssys_member.role, already projected asorg_membership_level)read/read_write/fullaliases; authoring rejects, no lenient parseeveryoneposition carries default grants: packages suggest, admins confirm, resolution is per-request (abolishes the fallback cliff; no second distribution channel)guestposition joinseveryone; packages suggest bindings to audiences, never ship shared builtin sets; deliberately no admin anchor (the superuser wildcard already covers every new package)kind: human | agent | service | guest | system,audience: internal | external,onBehalfOf): AI agents act on the intersection of their own grants and their delegator's, under a lint-enforced ceiling, with human co-sign for destructive operations; services are seatless least-privilege machine identitiesexternalSharingModel, defaultprivate, validatedexternal ≤ internal; BU depth inapplicable to externalsdocs/design/permission-model.md— the companion complete reference for the decided model: the five concepts, the evaluation pipeline, OWD semantics (internal + external dials), a worked CRM-package example (developer story + admin story), theeveryone/guestbaselines, plain-language sections on principal kinds (the agent "overlap rule") and delegated administration, the AI-safety layers, a "if you come from Salesforce/Dataverse/ServiceNow/SAP/AWS" mapping table, and the glossary/naming rules.Why
Three forcing facts, argued in the ADR's Context: the pre-launch window is the only zero-cost moment for breaking renames (hence no aliases — explicitly superseding ADR-0057 D5/D7's alias clauses); the metadata is AI-authored, so vocabulary size is attack surface; and a dogfood incident (objectstack-ai/objectui#2348) proved the current "unset OWD = fully public" default silently inverts the admin's mental model into org-wide read/write. D9–D12 add the operating-a-large-organization dimension raised in review: universal audiences, AI-agent/service principals, portal users, and subsidiary-scoped administration.
Relationship to existing ADRs
Builds on 0049 / 0056 / 0057 / 0066 / 0086. Amends: ADR-0056 D7 (default-profile fallback → replaced by the
everyoneposition), ADR-0057 D5/D7 (deprecated-alias discipline → superseded pre-launch). ADR-0057's core (BU tree, scope depth,sys_user_roledecoupling) is untouched and load-bearing. Six named follow-up ADRs are scoped out explicitly (grant lifecycle/recertification, SoD, scale hardening, dimension restrictions, ALM promotion, portal identity) and tracked on #2696.What this PR does NOT do
Docs only — no spec, plugin, or runtime changes. Implementation is phased in the ADR (P1 breaking wave incl. ctx/
externalSharingModelspec shapes → P2 audience anchors → P3 linter/gates/delegated admin → P4 explain/matrix), each phase with its own proofs per ADR-0054 discipline.🤖 Generated with Claude Code
https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H