13. Risks
Ordered by how much of the project each one takes with it.
Adapter abstraction is a guess until a second adapter exists
An interface with one implementation is a description of that implementation wearing a costume. Every Next-shaped assumption will leak into the contract and nobody will notice until the second adapter is attempted, by which point the contract is load-bearing everywhere.
Mitigation: the throwaway Hono adapter in M0. Two hundred lines, never shipped, serving the same controllers. It is the cheapest possible test and it is not optional.
Twenty green packages that do not compose
The specific failure mode of fleet execution. Every package passes its own tests, every contract is satisfied on paper, and the vertical slice does not work.
Mitigation: conformance suites written before implementations, by someone other than the implementer. Contract freeze at S2 with no local edits permitted. Integration as an explicit milestone with a human owner rather than an assumed byproduct.
Ward compiler correctness
A predicate that compiles to the wrong policy is a data leak with no error message. Tests pass, the page renders, and the wrong rows are visible to the wrong people.
This is the only part of the framework where paranoia is proportionate.
Mitigation: property-based tests generating random predicates and comparing client-side scoping against database enforcement on identical fixtures, run against a live database. A published list of predicate shapes the compiler refuses outright rather than approximating. ward:check in CI.
Contract churn breaks the ecosystem
A contract published in v1 and changed in v1.1 breaks every third-party driver written against it. The first time that happens the driver ecosystem stops growing, because writing one stops being worth it.
Mitigation: implement seven contracts in v1, not sixteen. Mark unimplemented contracts unstable in their package names until a real driver exists. Version contracts independently of the framework.
Next.js convention churn
The thing that stalled Blitz and pushed Redwood off Next entirely.
Mitigation: generated files stay four lines and contain no logic, so a router change is a codegen change rather than a rewrite. All logic lives in @avelon/*. The adapter layer means a sufficiently hostile Next release is survivable by shipping a different adapter rather than by dying.
Server actions are the least stable surface in Next
The entire write path depends on them.
Mitigation: the .api() escape hatch generates route handlers for the same controllers, so the fallback path is already built and tested rather than theoretical.
PostgREST ceiling frustrates people in week two
No client-side transactions and shallow joins. Somebody hits it early, writes a post about it, and that becomes the framework's reputation.
Mitigation: @avelon/postgres ships in v1 (D15), so the answer to "no transactions" is "change one config line" rather than "wait for v2." Honest docs about the Supabase driver's limits, stated up front rather than discovered.
Bailiff is intolerable if it is wrong
A linter with a false positive and no escape hatch gets disabled wholesale, and then the entire thesis is gone. This risk is larger than it looks, because the failure is silent: nobody files an issue, they just add the plugin to their ignore list.
Mitigation: every rule has a documented reason, an autofix where possible, and an inline disable that requires stating why. A bare disable with no reason is itself an error, which turns the suppressions into a searchable list of everywhere the framework was not good enough.
Bun and platform drift
Bun is the default across install, dev, build, test, and runtime. A disagreement between Bun and a deployment platform could strand the project.
Mitigation: no-bun-in-core, CI running the full suite on both runtimes, and a documented Node fallback that is tested rather than claimed.
The audience is smaller than it looks
Most Next developers are used to inventing their own lib/. A framework that fails the build when you do that is a narrower sell than "TypeScript on Vercel."
Mitigation: validate it before M1 rather than after. The vocabulary page and the example app ship as the first thing a visitor sees. If nobody reads them, that is a cheap answer to an expensive question.
Scope
Vigil, Peal, Moot, Banner, and Notices are all named in these docs and none are in the plan. Named things feel owed.
Mitigation: say publicly which are deferred and which are shipping. A roadmap with dates you miss is worse than a list of things you have not started.
Trademark
Avelon collides with an existing building-automation software vendor. Same goods class. See 14-naming.md.
Mitigation: a paid clearance search before printing anything or filing. The npm scope and GitHub org can be secured now at near-zero cost, and the decision to commit publicly can wait for the search.