0017 · Runtime crates next to the generator
Status: Accepted (2026-10-12). Spec: PLAN.md § Phase 12. Rollout: done — puerto-core,
puerto-web and puerto-sqlx.
Context
Section titled “Context”Puerto is a generator only: a generated project depends on no puerto crate. Everything it gets is
copied into it — including code that is identical in every project and that nobody is meant to
edit:
| Copied today | Lines | Varies per project |
|---|---|---|
presentation/src/main.rs — tracing, server, graceful shutdown, port, banner |
97 | name only |
presentation/src/health.rs — /health, /health/ready (ADR-0008) |
48 | no |
presentation/src/api/error.rs — ErrorResponse, IntoErrorResponse (ADR-0007) |
31 | no |
business/src/domain/shared/pagination.rs — PageRequest, Page (ADR-0016) |
107 | no |
business/src/domain/shared/repository_error.rs (ADR-0015) |
17 | no |
infrastructure/src/db.rs — pool, ping, map_sqlx_error |
— | no |
CORS and OpenApiService setup inside bootstrap.rs |
— | no |
Three costs follow, and they grow with the roadmap:
- A fix never reaches an existing project. A wrong Postgres code in
map_sqlx_errorstays wrong in every project generated before the fix. Rails and Loco ship the same fix throughbundle update/cargo update. - The missing production pieces are too large to generate. Auth, background jobs, mailers, storage, typed config, security middleware: thousands of lines each. Generated, every project owns and maintains a private fork of them.
- The generator pays for code that is not generated. Every template must stay green in the compile matrix and the snapshots; code in a crate is tested once, with ordinary tests.
There are no generated projects in use yet, so moving code now breaks nobody.
How other frameworks split it
Section titled “How other frameworks split it”- Loco (closest: Rust, Rails-inspired) — one runtime crate,
loco-rs, with cargo features (auth,worker,worker_redis…), plus a generator. The app implements aHookstrait (routes,boot,connect_workers,after_routes,initializers,seed,on_shutdown…): the framework calls the app. Every minor has broken the app-facing API (thebootsignature in 0.14,init_loggerin 0.16,AppContextandErrormade#[non_exhaustive]only in 1.0 “so future fields are non-breaking”). Upgrades are a written checklist — since 1.1 one written for a coding agent — pluscargo loco doctor. Generated code (scaffolds) is not upgraded: “this only affects code you generate after upgrading”. - Pavex (Rust) — a runtime crate (
pavex: request, response, extractors,Blueprint) and a transpiler that turns theBlueprintinto a generated “server SDK” crate: the application state, the DI call graph and the router are plain generated Rust, no runtime container. It needs nightlyrustdoc --output-format jsonto discover signatures. - Laravel —
laravel/laravelis a thin skeleton,laravel/frameworkis the versioned runtime. What the user may want to change is copied on request:vendor:publish(config, views),stub:publish(the generator’s templates). - Rails — gems (
railties,activerecord…) for the runtime; generators for app code.bin/rails app:updatereplays the new skeleton over the app and asks file by file. Rails 8 ships authentication as a generator, not a gem: the user model and controllers belong to the app, the primitives (has_secure_password, sessions) stay in the framework. - Spring Boot — starters (dependency bundles) and auto-configuration that backs away when the app declares its own bean of the same type.
Decision
Section titled “Decision”1. The rule: what is generated, what is a crate
Section titled “1. The rule: what is generated, what is a crate”- Generated — anything derived from
puerto.tomlor meant to be edited: entities, value objects, errors and theirFrom<RepositoryError>, use cases, repositories, DTOs, routes, error mappers,bootstrap.rs, the web slices. This is Puerto’s value and does not move. - Runtime crate — anything identical in every project and not meant to be edited.
- Both, split along that line — a feature with a domain part (auth: the
Userentity, the login use case are generated, as in Rails 8; password hashing, token signing, the middleware are in the runtime).
2. The runtime follows the Dependency Rule — one crate per layer, not one crate
Section titled “2. The runtime follows the Dependency Rule — one crate per layer, not one crate”A single puerto crate with features (Loco’s shape) would make business depend on a crate that
also carries poem and sqlx; the domain’s “no external crates” rule could only be kept by feature
discipline nobody checks. The split mirrors the layers instead:
| Crate | Content | Dependencies | Used by |
|---|---|---|---|
puerto-core |
PageRequest, Page, RepositoryError; later the ports UnitOfWork, Mailer, JobQueue, Clock, FileStore |
std, thiserror, async-trait |
business |
puerto-sqlx |
pool, ping, map_sqlx_error, migrations at startup; later the UnitOfWork adapter |
puerto-core, sqlx |
infrastructure |
puerto-web |
App: server, graceful shutdown, health, ErrorResponse / IntoErrorResponse, typed Config per environment, CORS, security headers, body limit, request id, serving web/dist |
puerto-core, poem, poem-openapi, tokio |
presentation |
later: puerto-jobs, puerto-mail, puerto-auth, puerto-storage |
adapters for the puerto-core ports |
their own | infrastructure, presentation |
The framework is hexagonal too: puerto-core holds ports, the other crates are adapters. A user
replaces an adapter by implementing the port — the Spring “back away”, without a container.
3. The app calls the runtime; the runtime does not call the app
Section titled “3. The app calls the runtime; the runtime does not call the app”Loco’s Hooks trait inverts control: the app’s shape is dictated by a trait whose signature
changes between minors, and the call graph is hidden inside the framework. Puerto keeps the
composition root visible, as Pavex does: bootstrap.rs stays generated, explicit Rust that
calls runtime building blocks. The runtime is a library, not a host:
// presentation/src/main.rs — generated once#[tokio::main]async fn main() -> Result<(), puerto_web::Error> { let config = puerto_web::Config::from_env()?; // fails fast on a missing / invalid value puerto_web::App::new(config) .serve(generated::bootstrap::build_app) .await}Customisation happens in one hand-written file the generator creates once and never touches
(presentation/src/app.rs: extra middleware, an adapter swap), which bootstrap.rs calls. No
runtime DI container, no reflection, no proc macro that hides routes: an agent reading the project
can follow every call.
4. Versioning: one version for the CLI and every runtime crate
Section titled “4. Versioning: one version for the CLI and every runtime crate”- All runtime crates live in Puerto’s workspace (
crates/core,crates/web,crates/sqlx) and are released in lockstep with the CLI:puerto 0.14.0generatespuerto-web = "0.14". puerto validatewarns when the project’s runtime minor differs from the CLI’s.- Every public enum and every struct a user may receive is
#[non_exhaustive]from day one (Loco needed a 1.0 to learn this); constructors or builders instead of struct literals. - Each breaking release keeps
release.md’s Migration Guide and also ships it as a prompt for a coding agent (Loco 1.1’s pattern): Puerto is AI-ready, so its upgrade path is too. release.ymlpublishes the runtime crates beforepuerto.
5. The compile matrix tests the unreleased runtime
Section titled “5. The compile matrix tests the unreleased runtime”Generated projects in make test/full / make test/db get a [patch.crates-io] pointing at the
workspace crates, so a template and the runtime it calls change in the same commit and are tested
together. The runtime crates get ordinary unit tests, and make test/mutation covers them.
6. Escape hatch: eject
Section titled “6. Escape hatch: eject”puerto eject <component> (later, Laravel’s vendor:publish) copies a runtime module’s source
into the project and rewires the import, for the rare case where implementing the port is not
enough. Ejected code is the user’s; it no longer receives fixes.
Alternatives rejected
Section titled “Alternatives rejected”- Stay a generator, add
puerto upgrade(a three-way merge of the new template over the project, asrails app:update). It handles the skeleton, not features: auth or jobs would still be thousands of generated lines per project, and every conflict lands on the user. It remains useful for the generated files themselves and may come later — it does not replace this. - One
puertocrate with features (Loco). See § 2: it breaks the domain’s dependency rule in all but discipline. - A Pavex-style transpiler over rustdoc JSON. Puerto already generates its DI graph, from
puerto.tomlrather than from reflection — no nightly toolchain needed. Nothing to adopt beyond the principle (generated composition root over a runtime container), kept in § 3.
Consequences
Section titled “Consequences”-
Fixes and security patches to infrastructure reach existing projects through
cargo update. -
The missing production pieces (
PLAN.md: auth, jobs, mailer, storage, config, security) can be built as tested library code instead of templates. -
Generated projects get smaller: the snapshots show exactly which files stop being generated.
-
Two public contracts instead of one: the generated shape and the runtime crates’ API, both under
release.md’s SemVer policy. -
Less is visible in the project: an agent reads the runtime from docs.rs or
~/.cargo, not from the repo. The generatedAGENTS.mdnames the runtime crates and what each owns (ADR-0010 tests it); eject covers the case where the source must live in the project. -
The crate names (
puerto-core,puerto-web,puerto-sqlx,puerto-jobs,puerto-mail,puerto-auth,puerto-storage) were free on crates.io on 2026-10-12. -
Rollout, one commit each, every one a pure move with no new behaviour:
- workspace crates +
puerto-core(pagination,RepositoryError) — ADR-0015/0016 types move, their codes do not change; puerto-web(main.rs, health,ErrorResponse, CORS,Config) — ADR-0007/0008 hold;puerto-sqlx(pool,ping,map_sqlx_error).
New features land in the runtime from then on.
- workspace crates +
Amendment (12.1, 2026-10-12): traits the project implements for its own types stay in it
Section titled “Amendment (12.1, 2026-10-12): traits the project implements for its own types stay in it”IntoErrorResponse did not move: every error_mapper.rs implements it for an error of
business, and with the trait in puerto-web both trait and type would be foreign to
presentation — the orphan rule (E0117) rejects it. Only the body, ErrorResponse, is the
runtime’s. The rule for later pieces: a trait that one project crate implements for a type of
another project crate (here presentation for business) is generated into the implementing
crate. Runtime traits implemented for a type in the same crate — a repository adapter for a
puerto-core port — are fine.