docs: RFC 0001 for declarative management of platform resources

[rohilsurana]

Documents a declarative way to manage Frontier's platform configuration: desired-state YAML files, the frontier reconcile and frontier export commands, and the five rules every resource kind follows.

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, so a file is seeded from a running server.
• A document carries apiVersion: v1 (absent means v1). Content with no kind, an unknown kind, or a missing spec is rejected; write spec: [] to mean an empty list. The whole file is checked before anything applies, and documents then apply in the order they appear.
• Five rules every kind follows:
  1. Scope and identity. A kind manages a set it declares: which entries, and which fields within an entry. Anything outside that set is invisible. The diff skips it, export leaves it out, and a file entry that names it is rejected. Values other tools set pass through writes untouched. Every entry has one stable identity, so a rename is a delete plus a create.
  2. The file is the desired state. Each entry is an object or a value, and the resource decides which. An object is created and deleted: a missing one fails the plan, and deleting needs delete: true. A value always exists and has a default: a value the file leaves out goes back to its default, and there is no delete flag. One field rule covers both. A field you write is the whole value. A field you leave out takes the default. An empty field ("" or []) means empty. Nothing merges.
  3. Check the whole file before changing anything. Version, kind, spec, order, fields, and every entry are checked up front. A check that needs live state runs during the diff, where it shows in the plan or fails it.
  4. Converge, do not transact. Each change is one API call. Adds and updates run before deletes, so a run that stops halfway never leaves less access than intended. Nothing rolls back. Recovery is to fix the cause and run again; what already applied shows no change and the run picks up the rest. Concurrent runs are last-write-wins.
  5. Export is the reverse of reconcile. Export writes sorted output that carries only the fields that differ from their default. The guarantee is over server states: for every state the server can reach, reconciling its export plans zero changes.
• Five kinds under those rules: PlatformUser (value, a missing entry removes access), Permission (object), custom Role (object), predefined Role (value, resets to the shipped definition), Preference (value, resets to the trait default), and Webhook (object, the URL is the identity, an empty event set means all events, and the signing secret is server-owned so it is never in a file, a plan, or an export).
• Boot changes. Config superuser promotion is gone (v0.108.0). Boot no longer updates existing roles, so definition updates move to a reviewed reconcile run after an upgrade. resources_config_path is deprecated and removed two minor versions later. The reconcile image must match the server release, because the reset target for predefined roles is compiled into the CLI.
• Narrowing a predefined role only restricts principals whose access comes through the role; the base schema still grants owners directly, so removing that is future work. Custom permissions flip cleanly.
• Auth is any superuser credential; the bootstrap service account exists so automation always has one. -H passes the token for now and is masked in logs.

What it covers

• The problem with the three old flows: config-driven superusers, boot-time resource YAML, and hand-run API changes.
• The file format, the two commands, and the reconcile framework.
• The five rules every kind must follow, so future kinds start from the same contract.
• The five kinds against those rules: PlatformUser, Permission, Role, Preference, and Webhook.
• The two boot behavior changes, with predefined-role definition updates moving to reviewed reconcile runs, and the plan to deprecate and remove resources_config_path.
• Key decisions with reasons, trade-offs, and future work.

Status

The RFC is marked Accepted, and the flow is implemented in the reconcile package and the reconcile and export commands. PlatformUser, Permission, Role, and Preference are merged to main; the Webhook kind is in review (#1772). This document describes the shipped design.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview, Comment	Jul 20, 2026 2:07pm

[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 29749206689

Coverage remained the same at 46.11%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	38321
Covered Lines:	17670
Line Coverage:	46.11%
Coverage Strength:	13.32 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.