36. Assisted framework upgrades

Rullst v12 introduced a bounded upgrade transaction for existing applications. The goal is to make the safe, repeatable part a single command while refusing to guess about application data or security policy.

The transaction steps below were written for 12.1.0; check publication status. The v12 line reached end of life on 16 October 2026, so a v12 application moves to v13 with the v13 CLI. The v13 source rules and the rule classification are described in v12 to v13: source findings and belong to the 13.0.0-alpha.4 prerelease. Install the exact release and complete the application-specific validation below before any production rollout.

What the command can guarantee

cargo rullst upgrade can inventory the Cargo workspace, update the Rullst release train, apply compiler suggestions, require cargo check, and restore the files it controls after a failure. It cannot prove that a database upgrade, authorization rule, provider integration or deployment still behaves correctly.

The automatic transaction owns only:

• versioned Rullst dependencies in exact Cargo workspace manifests;
• the root Cargo.lock produced by Cargo resolution;
• Rust edits proposed by cargo fix;
• a cargo check --workspace --all-targets --locked gate using the application’s selected features.

The 12.1 updater writes managed requirements as =VERSION, preserving the explicitly selected release instead of allowing Cargo to choose a later patch or minor version. cargo fix resolves the candidate lockfile, and the final check must use that resolution unchanged. Review these pins before restoring any broader dependency-update policy in your application.

It never runs migrations, changes secrets, invents tenant/ownership policy, opens Nexus or Studio, contacts application providers, or marks the result production-ready.

1. Prepare the application

Create a branch, make the worktree reviewable, record the old test result, and back up every database. Prove the database backup can be restored before changing the framework.

Install the exact CLI from the same release train as the target framework. For a v12 application, that is the v13 prerelease (Cargo never selects a prerelease on its own):

cargo install cargo-rullst --version =13.0.0-alpha.4 --locked --force

The framework command does not update its own executable. This matters for v5: the already-published v5 CLI cannot gain the v12 migration engine retroactively, and the v13 CLI upgrades only from v12 or later. A v5 application first moves to v12 with the end-of-life 12.x CLI (cargo install cargo-rullst --version 12.1.0 --locked --force, as the steps below show), then to v13. Run each CLI inside the application.

2. Inspect without writing

cargo rullst upgrade --dry-run

The plan shows every dependency edit and source finding. MUST-CHANGE (BLOCKER in the 12.x CLI) means a known old API or option requires a source change; REVIEW means the code uses an API, feature or configuration whose behaviour changed and must be revalidated. Neither label means that unreported code is automatically safe.

For automation, request JSON:

cargo rullst upgrade --dry-run --json > upgrade-plan.json

The root object uses schema_version: "rullst.upgrade-plan.v1" and identifies the rule catalog, exact target, manifest changes, detected source majors, findings, automatic scope and mandatory manual gates. Consumers must reject an unknown schema version rather than silently interpreting it as v1. The v13 CLI extends v1 additively (see the v13 fields); consumers must ignore keys they do not know.

Use an explicit target to make the selected published version visible:

cargo rullst upgrade --to 13.0.0-alpha.4 --dry-run

Other targets must exist in the registry and belong to the installed CLI’s major train, so a CLI never applies rules it does not carry: a v12 CLI cannot plan a v13 migration, and the v13 CLI cannot downgrade a project.

3. Apply the transaction

After resolving or accepting every finding:

cargo rullst upgrade

Before the first write, the CLI snapshots Cargo workspace manifests, the root lockfile and Rust sources under:

target/rullst-upgrades/<UTC-run-id>/
├── files/
├── index.tsv
├── report.md
└── report.json

It then edits the TOML while preserving comments and relative order, runs compiler-provided fixes and executes the Cargo check gate. A failing gate restores the controlled files automatically and returns a non-zero status.

To deliberately keep a partial result for diagnosis:

cargo rullst upgrade --keep-on-failure

To restore a persisted snapshot after that mode or after an interrupted run:

cargo rullst upgrade \
  --restore target/rullst-upgrades/<UTC-run-id>

Restore accepts only a path-validated snapshot inside the current project’s target/rullst-upgrades directory. cargo clean deletes target, so retain a normal version-control commit or copy a needed diagnostic report before cleaning.

Recovery boundaries and 12.1.0 hardening

Stop editors, watchers and other writers before restoring. File recovery does not undo build-script/test side effects or database/external-service changes. Keep an independent version-control backup; the directory under target is not a substitute for one. A filesystem error during application can leave some files restored and others unchanged, so always review the result.

Since 12.1.0 the CLI preflights the entire backup, stages every replacement before writing originals, and rejects linked or malformed paths. It limits indexes to 8 MiB/100,000 entries, each snapshot to 64 MiB and the total to 512 MiB. Disk failure while staging leaves originals intact; failure during the later per-file apply reports progress and retains the backup. This is not an all-files atomic commit and does not defend against hostile concurrent filesystem changes. These improvements are not in 12.0.0.

4. Finish a v5 to v12 migration

This step uses the v12 CLI. The v13 CLI accepts only v12 and v13 projects, so upgrade older applications to v12 first and then to v13.

The v5 README used attribute-style routing and a server builder with no router or port. The scanner reports these markers instead of applying a global text replacement. Replace the old shape:

#[routes]
fn home() -> Response {
    // ...
}

Server::new()
    .route("/", get(home))
    .run()
    .await;

with an explicit v12 router and typed error propagation:

use rullst::{Server, response::Html, routes};

async fn home() -> Html<&'static str> {
    Html("Hello from v12")
}

#[rullst::runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![get("/" => home)];
    Server::new(app).run(3000).await?;
    Ok(())
}

Then follow the complete v5 → v12 guide, including feature selection, disposable database migration/rollback, explicit Nexus and Studio boundaries, provider validation and authorization negatives.

5. Run the application-owned gates

At minimum:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo build --release

Also test the actual production feature set, restore/migrate/rollback against a production-shaped database copy, cross-user and cross-tenant denials, proxy/TLS identity, CSRF/CORS, Nexus/Studio exposure and every configured live provider.

v12 to v13: source findings

The v13 CLI carries the rullst-upgrade-rules-v4 catalog. It parses the application instead of matching text: Rust files with syn (so comments, doc comments and string literals never match an API rule, and macro bodies such as html! and routes! are read token by token), Cargo manifests with a TOML parser, and a few generated project files (.gitignore, .dockerignore, .cargo/config.toml, Foundry.toml, docker-compose.prod.yml, Kubernetes YAML, an Omni shell under omni-app/, rullst-client.ts, Dockerfile, .env/.env.example keys and release scripts). Files are read without following symbolic links; a finding records a rule and a line, never file contents. A Rust file that does not parse, is not UTF-8 or is larger than 2 MiB is listed as NOT SCANNED.

Each finding has a stable code (V13-...), a kind, a location, a one-line message and the first-column title of its row in the v13 migration guide:

Source findings (rullst-upgrade-rules-v4): 1 must-change, 2 review
  MUST-CHANGE src/views/home.rs:12 [V13-HTML-DYNAMIC-EVENT-HANDLER] a dynamic value in an `on*`/`hx-on*` attribute of `html!` no longer compiles
      migration-v13 row: `html!` event handlers
  REVIEW src/main.rs:64 [V13-RENDER-PAGE-LANGUAGE] `render_page` declares `lang="pt-BR"`; English pages should use `render_page_with_lang`
      migration-v13 row: Starter page language

• must-change: a compile-breaking or API-shape change that the code uses (for example a dynamic onclick={...} in html!, a belongs_to without foreign_key, a struct-level #[sqlx(rename_all)] on a model, a match on FieldKind without a wildcard, a utoipa 5 dependency used with Studio).
• review: the code uses an API, feature or configuration whose behaviour changed (for example Model::all(), ValidatedJson, the Mail facade, render_page, a generated .gitignore without the SQLite journal files).

A review rule is reported once per file (its first location); a must-change rule at every location. The rule classification lists which migration rows have rules. Findings never block cargo rullst upgrade, whose cargo check gate still restores the project when the code does not compile. The gate’s error names the must-change findings and repeats the guidance of V13-CAPITAL-REMOVED and V13-MAIL-REMOVED findings, which name removed APIs but are review findings. update project verify, review and apply refuse a preparation that has must-change findings and carry review findings in the plan.

Rules by release

Each rule records the release that introduced the change it reports. The rules for the 12.x to 13 changes date from 13.0.0-alpha.1; a rule added later, or reworded because a later release changed what it reports, carries that release:

A rule is dated by the first release tag whose catalog contains its code (git show v13.0.0-alpha.2:cargo-rullst/src/generators/build/upgrade/rules/catalog.rs, or git log -S'"V13-..."' on that file), checked against the CHANGELOG entry that names it; a new rule takes the next release. A unit test checks that every rule names one of these releases.

The plan takes the application’s Rullst version to be the oldest version that a Rullst requirement in the workspace manifests admits (=13.0.0-alpha.3, or 13.0.0-alpha.1, a caret requirement) or that Cargo.lock holds. When that version is a 13.0 prerelease, only the rules introduced after it apply: an alpha.3 application gets the alpha.4 rules, an alpha.2 application the seven alpha.3 rules and the alpha.4 rules, and an alpha.1 application the alpha.2, alpha.3 and alpha.4 rules, because the earlier changes are already in the version it runs. The plan says what it skipped:

Source findings (rullst-upgrade-rules-v4): 0 must-change, 1 review
  Rules: introduced after 13.0.0-alpha.2, the Rullst version this project uses; earlier rules skipped: 100 (findings hidden: 3); --all-rules applies every rule

A v12 application, or one whose version cannot be read (path dependencies without a version and no Cargo.lock), gets every rule. --all-rules applies every rule to a prerelease application too, for example to review the 12.x to 13 changes again. Project preparations (cargo rullst update) always apply every rule, because their must-change findings gate execution.

JSON plan fields

--dry-run --json keeps every rullst.upgrade-plan.v1 key. Each element of source_findings keeps path, line, code (the stable rule id), severity (BLOCKER or REVIEW) and message, and adds:

The root object adds finding_counts (must_change, review), unscanned_sources (project-relative paths), migration_guide and rule_selection: current_version (the application’s Rullst version, or null when it cannot be read), all_rules (--all-rules, and always true in project preparations), skipped_rules (rules introduced in or before current_version that were not applied) and hidden_findings (the findings those rules would have added). A consumer that ignores unknown keys reads the plan as before; findings of skipped rules are absent from source_findings and finding_counts.

Fixing the findings

Each finding names its rule and the first-column title of its row in the v13 migration guide, which says what changed and how to adapt. Fix them by hand, or with your editor’s or terminal’s AI assistant given the plan, the migration row and the project’s AGENTS.md (cargo rullst generate:ai-context); review every edit it proposes. cargo rullst ai upgrade, which proposed such fixes in earlier 13.0 prereleases, was removed in 13.0.0-alpha.4.

A practical order:

1. cargo rullst upgrade --dry-run and read every finding with its migration row.
2. Fix findings that also compile against v12 (most review items and the html!, ORM and Nexus must-change items), then run the v12 tests.
3. cargo rullst upgrade. When a fix needs a v13 API (for example utoipa 6 with Studio), run cargo rullst upgrade --keep-on-failure, fix the kept state, and finish with cargo rullst upgrade (no further version edits; it validates the result).
4. Run the application-owned gates below.

Rehearsal on generated starters

A rehearsal generates starters with a published CLI, points their Rullst dependencies at a checkout of the next version through [patch.crates-io] (the registry requirements stay, so the upgrade edits them as it would for a published release), runs cargo rullst upgrade with the newer CLI and then each project’s build, tests and Clippy.

13.0.0-alpha.2 to 13.0.0-alpha.3

The October 2026 rehearsal used the published v13.0.0-alpha.2 Linux binary, checked with sha256sum -c cli-checksums-x86_64-unknown-linux-gnu.txt from the same release, and a CLI built from main; the projects built with Rust 1.99.0. Because main still carried the alpha.2 version, the rehearsal exported it (git archive), set every package to 13.0.0-alpha.3 in that copy, patched the projects to the copy and passed --to 13.0.0-alpha.3. The published alpha.3 CLI targets its own version, so --to is not needed there.

./cargo-rullst-13.0.0-alpha.2-x86_64-unknown-linux-gnu rullst new a2-saas --default \
  --blueprint saas --database sqlite --skip-initial-migration
cargo build && cargo test            # on 13.0.0-alpha.2; commit Cargo.lock
# append [patch.crates-io] entries for every rullst package in Cargo.lock, commit
cargo rullst upgrade --dry-run --to 13.0.0-alpha.3
cargo rullst upgrade --to 13.0.0-alpha.3
# edit what the findings ask for, then
cargo build && cargo test && cargo clippy --all-targets -- -D warnings

Blank, Blank --api, SaaS and LMS starters built on alpha.2 without warnings, and 3, 3, 7 and 11 tests passed. Against the alpha.3 candidate:

V13-ORM-SKIP-MANAGED-COLUMNS is the only finding about an alpha.3 change. The other findings locate APIs whose behaviour changed between 12.x and 13.0.0-alpha.2, so they also appear on a new alpha.2 or alpha.3 starter and need no edit in an application that already runs alpha.2. After the User edit the SaaS and LMS dry runs report 3 and 5 findings, all of that kind. The rehearsal’s CLI applied every rule; the plan now skips the rules an alpha.2 application already runs with (see Rules by release), so its default dry run lists only V13-ORM-SKIP-MANAGED-COLUMNS for SaaS and LMS and nothing for Blank and Blank --api, and --all-rules lists the findings in the table.

An HTTP smoke test of each upgraded starter (db:migrate, then the server in development) passed. In SaaS and LMS, registration stored is_admin = 0 and session_epoch = 0 from the column defaults, “Sign out everywhere” raised the epoch and the earlier cookie was refused, signing in again worked and the loopback Nexus answered 200. Blank and the JSON API answered / and /health, and the API’s bearer POST /api/messages returned 201 (401 without the token).

The same starters generated by the alpha.3 CLI differ from the alpha.2 ones only in the User fields above, in the localized account mail and APP_NAME of the password controller and .env and the checked reset-link lifetime of src/models/password_reset.rs (the “Account mail language and product name” and “Generated reset link lifetime” rows; existing projects keep their code) and in the SaaS users migration, which imports through rullst::db instead of rullst_orm (both compile). The alpha.2 to alpha.3 checklist turns this into steps for a real application.

Limits: SQLite only; the starters use none of the other APIs that alpha.3 removes or changes (Omni, offline-sync, default features, Orm::transaction, mock Connect credentials), so their rules ran only in the catalog’s unit tests; no live mail, billing or OAuth provider was called.

Earlier rehearsals: v12 to v13

.github/rehearse-v12-upgrade.sh is a manual helper (not a CI job) for the v12 to v13 path; its header documents the arguments. In October 2026 it and the published 12.3.0 binary upgraded Blank, Blog, SaaS and LMS starters of the 12.0.0, 12.1.2 and 12.3.0 CLIs to the 13.0.0-alpha.1 workspace with review findings only (5 to 14 per starter, for example V13-GITIGNORE-DATABASES, V13-MODEL-ALL and V13-HEALTH-PROBES) and no source edit, with one exception: the 12.3 SaaS starter still names LemonSqueezyProvider, so cargo fix failed and the project was restored until the Lemon Squeezy branches of src/controllers/billing_controller.rs and the BILLING_STORE_ID lines of .env and .env.example were removed, as V13-CAPITAL-REMOVED describes (that edit also compiles on 12.3). Starters of the 12.0 CLI also carry the build files listed in the migration guide. Those counts predate the alpha.2 and alpha.3 rules and were not re-measured.

v12 → v13 rule classification

Every row of the v13 migration guide is classified for rullst-upgrade-rules-v4:

• (a) must-change: a compile-breaking or API-shape change detectable in application source (12 rows);
• (b) review: changed behaviour worth reviewing when the application uses the affected API, feature or configuration, which the rules locate (100 rows);
• (c) none: no application impact, or not detectable in the application (CLI behaviour, generator output for new projects, opt-in features, fixes of inputs that previously failed) (99 rows).

A row with both a must-change and a review part counts in both. The catalog has 114 rules. A row can map to several rules and a rule to several rows; when a row changes in a later release, update this table and the rule together.

Planned simpler update experience

Since 13.0.0-alpha.4 the CLI never downloads or replaces its own binary. Install a newer CLI with Cargo and its exact version (cargo install cargo-rullst --version =VERSION --locked). At most once a day, in an interactive terminal, the CLI prints that command when crates.io has a newer release of its major; see the CLI reference. The 12.1.0 to 13.0.0-alpha.3 self-updater (update check, update verify, update stage and update install) was removed; the project commands below remain.

cargo rullst update project prepare --project PATH --json copies the Git working directory into private storage and edits only the candidate’s versioned workspace dependencies. It preserves dirty and untracked source, tracked deletions and the root lockfile, including a legacy ignored lockfile. Compare before/ and candidate/ at the reported location and review preparation.json. Builds/tests are not executed and neither execution nor application is authorized. See the preparation limits and exclusions. Use update project verify --prepared PATH --dry-run to inspect its validation commands. Only after reviewing the trusted project, use --allow-project-code to authorize lockfile resolution, locked checks and tests in a fresh private copy. This is not a sandbox; tests inherit your environment and can have external effects. See the verification options and limits. Then update project review --verified PATH --json revalidates the verification record and shows the full dependency diff with a review digest. Use the returned verified_directory; the digest grants no apply authority. Explicit update project apply --verified PATH --approved-review SHA256 applies only the reviewed manifests/root lockfile. The matching recover command restores only that operation and refuses unrelated edits.

The safe-update priority proposes one guided flow for project preparation, validation and approved application. cargo rullst update guided --to VERSION --project PATH composes those commands. Each approval defaults to no and follows its complete review. Version, directories and digests are carried between steps; separate prompts govern trusted project execution/network and original-file application. --offline keeps verification local. Since 13.0.0-alpha.4 the flow no longer installs a CLI (--scope and --root were removed): install the target CLI with Cargo first. See the guided command. File recovery does not replace database backups or application acceptance tests, and updating the CLI alone never updates a deployed application.

The 12.1.0 update mechanism does not implement v13 migrations. The v13 CLI (13.0.0-alpha.4 prerelease) carries its own rule catalog (v12 to v13: source findings); update guided offers a project update only within the installed CLI’s major.

Is this unique?

No. Assisted upgrades are an established framework practice: Rails documents interactive bin/rails app:update, Angular provides ng update, and Dart offers preview/apply analysis fixes through dart fix. Microsoft’s .NET Upgrade Assistant also analyzed and changed projects, although Microsoft now marks it deprecated in favor of its modernization tooling.

Rullst’s useful distinction is the bounded composition: Cargo-workspace-aware TOML edits, a version-selected framework rule catalog, human and JSON plans, controlled snapshots, default rollback, explicit recovery and Cargo gates in one CLI flow. This is a testable design choice, not evidence that Rullst is the first or universally the best updater.

Official references:

• Upgrading Ruby on Rails
• Angular ng update
• Dart dart fix
• .NET Upgrade Assistant overview