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.

The RFC now opens with an "At a glance" section (a flow diagram, the object-vs-value model with a decision diagram, the kinds table, and the five rules in one line each), so the whole model fits on one screen before the detail. This TLDR is just the lead keywords; the RFC has the full text.

TLDR

• A file per kind, two commands. frontier reconcile -f file [--dry-run] plans, then applies; frontier export <kind> prints the live state in the same format.
• The file. apiVersion: v1, a kind, and a spec, checked whole before anything applies.
• Object or value. Each entry is one or the other. That decides what a missing entry means and whether delete applies.
• Five rules every kind follows: Scope and identity; the file is the desired state; check the whole file before changing anything; converge, do not transact; export is the reverse of reconcile.
• Five kinds: PlatformUser, Permission, Role, Preference, Webhook.
• Boot changes. Config superuser promotion is gone; boot no longer updates existing roles; resources_config_path is deprecated.
• Auth. Any superuser credential; the bootstrap service account exists so automation always has one.

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, 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 23, 2026 6:30am

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

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.1%) to 46.209%

Details

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

Uncovered Changes

No uncovered changes found.

Coverage Regressions

1113 previously-covered lines in 33 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
core/membership/service.go	193	81.22%
internal/api/v1beta1connect/user.go	102	66.81%
core/authenticate/service.go	101	15.01%
internal/api/v1beta1connect/project.go	74	44.0%
internal/api/v1beta1connect/role.go	68	26.92%
internal/api/v1beta1connect/organization.go	53	63.27%
internal/bootstrap/schema/schema.go	52	16.67%
core/organization/service.go	43	27.36%
internal/api/v1beta1connect/authenticate.go	41	25.1%
internal/store/postgres/organization_repository.go	37	78.92%

---

Coverage Stats

Relevant Lines:	38538
Covered Lines:	17808
Line Coverage:	46.21%
Coverage Strength:	14.07 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.

[rohanchkrabrty]

LGTM 🚀