docs: RFC 0001 for declarative management of platform resources

[rohilsurana]

Proposes a declarative way to manage Frontier's platform configuration: desired-state YAML files, the frontier reconcile and frontier export commands, and per-kind behavior rules.

TLDR

• A YAML file per kind says what should exist. frontier reconcile -f file --dry-run prints the plan; the same command without the flag applies it. frontier export <kind> prints the live state in the same format.
• Documents carry apiVersion: v1 (absent means v1). The whole file is parsed and checked before anything applies; documents then apply in file order, and ordering dependencies (permissions before roles) is the file author's job.
• What a missing entry means is a per-kind choice: PlatformUser removes it (the file is the full access list); Permission and custom Role fail the plan (keep it or mark delete: true); predefined roles reset to their shipped definitions, so drift shows up in the plan instead of being skipped. Nothing structural is ever deleted by omission.
• A listed field is managed; an omitted field keeps its server value — except on predefined roles, where an omitted field takes the definition's value. Names are identities and never change — role renames are impossible by design (the server resolves predefined roles by name), only titles rename.
• Adds and updates always run before removes, so a failed run never leaves less access than intended.
• There are no transactions. Every API call commits on its own; nothing rolls back. The design compensates by being declarative and idempotent: re-applying the file is the one recovery for every failure — it picks up exactly the remaining difference and converges. Concurrent runs are last-write-wins for the same reason.
• Kinds are independent: a reconciler never resolves another kind's references. Cross-kind contradictions fail at the API call with a clear error.
• Every kind implements export. Output is sorted, and reconciling an export always plans no changes — so files are seeded from exports and a clean dry run proves a file matches its server.
• Boot changes: config-based superuser promotion is gone (v0.108.0); boot stops updating existing roles (this proposal); resources_config_path is deprecated and removed after two minor versions. New predefined-role defaults from a release roll out through the first reconcile run with the new image, reviewed in a plan, instead of invisibly at boot — so the CLI image should match the server release.
• Caveat when narrowing predefined roles: the base schema also grants many permissions directly (owner, member, superuser), so org owners are unaffected until relation-based ownership is removed (planned). Custom permissions always flip cleanly.
• Auth is any superuser credential; the bootstrap service user exists for automation. -H is interim — mask the token in logs.

What it covers

• The problem with the three current flows: config-driven superusers, boot-time resource YAML, and hand-run API changes.
• The file format, the commands, and the reconcile framework.
• Rules every kind must follow, so future kinds start from the same contract: server-managed objects stay invisible, identities never change, listed fields are managed, every kind declares what a missing entry means (fail the plan / removal / reset to default) and what deletion means, adds run before removes, and every kind exports deterministically with a clean round trip.
• The first three kinds against those rules: PlatformUser (shipped in v0.108.0), and Permission and Role (proposed here).
• Two boot behavior changes: superuser promotion removal (shipped) and boot no longer updating existing roles (proposed), with definition updates moving to reviewed reconcile runs.
• Decisions with reasons, alternatives considered, and known drawbacks.

Status

PlatformUser shipped and set the pattern. #1731 (export command) and #1737 (Permission and Role kinds) are draft implementations of this proposal; they change with this RFC's review and merge after it.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview, Comment	Jul 15, 2026 11:21am

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The RFC documents a declarative YAML workflow for reconciling and exporting Frontier resources, defines shared kind behavior and rules for PlatformUser, Permission, and Role, and specifies supporting server changes, decisions, trade-offs, and future work.

Changes

Declarative reconciliation design

Layer / File(s)	Summary
Workflow goals and command framework docs/rfcs/0001-declarative-reconcile.md	Defines the desired-state format, reconcile/export commands, validation and API behavior, and the framework interface for registering resource kinds.
Kind contracts and reconciliation rules docs/rfcs/0001-declarative-reconcile.md	Specifies universal reconciliation rules and detailed behavior for PlatformUser, Permission, and Role, including role permission effects and future-kind requirements.
Server support and design decisions docs/rfcs/0001-declarative-reconcile.md	Documents required server boot and loader changes, migration guidance, decisions, alternatives, trade-offs, future work, and references.

Estimated code review effort: 2 (Simple) | ~15 minutes

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d8fb691c-6b4f-4ac9-9f5e-4c8db0d04f33

📥 Commits

Reviewing files that changed from the base of the PR and between cd6b070 and a8506ce.

📒 Files selected for processing (1)

• docs/rfcs/0001-declarative-reconcile.md

[coveralls]

Coverage Report for CI Build 29411345758

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage increased (+0.3%) to 45.198%

Details

• Coverage increased (+0.3%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 112 coverage regressions across 2 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

112 previously-covered lines in 2 files lost coverage.

File	Lines Losing Coverage	Coverage
cmd/serve.go	84	0.0%
pkg/server/server.go	28	62.34%

---

Coverage Stats

Relevant Lines:	37701
Covered Lines:	17040
Line Coverage:	45.2%
Coverage Strength:	12.69 hits per line

---

💛 - Coveralls

[rohilsurana]

Verified the narrowing warning against the schema and against a live server (built from #1737, seeded an org, narrowed app_organization_owner via reconcile). One sentence in it is factually wrong; details inline. More comments on the other sections will follow.

[rohilsurana]

Follow-up comments on the remaining sections, per review discussion.

[rohilsurana]

Review notes (self-review after an independent pass)

Three wording fixes, all in 3ce4741:

• The predefined-role section said an omitted field "takes the definition's value" without
  the caveat that a field which is empty on the server converges only when it is listed.
  The headline now points at that edge, which is described a few lines below.
• The reset target is schema.PredefinedRoles, which can name the same role twice. The
  code takes the first definition, matching boot. The RFC now states this.
• Rule 8's parenthetical read awkwardly next to "permissions go before roles". Reworded so
  the good order and the rejected order read the same way round.

No behavior contradictions found between the RFC and the code on the implementation branch.