[Deep Dive #52] Route Group Covenants - discussion
Deep Dive #52 is a pragmatic answer to mixed routing terminology: route groups need a covenant so 'pages' and 'tracks' can coexist without endless debates.
The covenant rule is blunt: any segment can render any behavior as long as the group covenant records the decision and keeps the group's state handle stable. If it's not visible in render, it isn't auditable.
Do you already have group-level contracts in your app, or does behavior drift per segment? What do you record in a covenant ledger (arrivals, transitions, reroutes, owners, policy)? How strict are you about 'no reroute from leaf components' vs 'segments can reroute from render if recorded'?
Comments (10)
Back to latestThe covenant ledger is the key. Without it, mixed terminology turns into mixed behavior and nobody can explain why a route changed.
Related: The App Router Mindset.
I like that it treats covenants as 'not a folder rule'. It's a contract any segment can read/write.
That makes it survivable when teams inevitably move routes around.
The simplest covenant evidence we shipped was just rendering the groupId + policy in the shell:
tsx
const ledger = useCovenantLedger('settings');
return <div data-covenant={ledger.read('groupId')} data-policy={ledger.read('scope').policy} />;Counterpoint: 'any segment can render any behavior' can become an excuse for no boundaries.
I'd still want a default owner (shell) plus an override registry for exceptions.
Related: Override Registry (Deep Dive #29).
This pairs nicely with navigation routines (Deep Dive #4). If navigation is routine, covenants are the rulebook for where routines live.
Related: Navigation Routines (Deep Dive #4).
We had "group contracts" accidentally (shared deep prop object + shared fetch lane), but they weren't explicit.
Writing the covenant down made it easier to say "this behavior belongs to the group" instead of arguing per segment.
Ledger content that actually helped us:
- arrivals (file route -> group entry), - transitions (track switches), - reroutes (why we overrode intent), - owner (which shell/group policy decided), - and the stable handle id for shared state.
If the ledger doesn't include handle id + owner, it turns into a history log with no accountability.
On reroutes: I'm less strict than the blog tone. Leaves can request reroute if it's recorded as a request, not a decision.
Decision still belongs to the shell (or covenant owner), but letting leaves *ask* stops a lot of awkward prop threading.
I misunderstood the first read and thought this was "route groups must be folders".
It's more like "route groups are contracts" and the folder is just a convenient naming surface.
Exactly. The folder helps humans, but the covenant is the real artifact.
If the group moves, the covenant should survive the move (stable handle, stable rules).
The good version of this feels like routing hygiene: where does policy live, where does state live, where does evidence live.
Related: Routing and Navigation.