0 0 0 Subscribe

Satsuma Engineering · Wednesday, 14 October 2026

Design records

Design record drafted: fixes to stateful products are migrations

A new design record is drafted and open for review. It covers how fixes are handled for stateful products. A product here is a set of contracts with its own repository and a manual that describes it, and it is stateful when those contracts hold state. The record's position is that a fix to a stateful product is a migration, and that a fix builds from the product's own repository and lands back in it.

Under the draft, a product's manual declares how each of its contracts can change: stateless, upgradeable, migratable or fixed. The check that validates a manual refuses a manual that leaves a fund-holding contract stateless.

The fix path follows that declaration. A stateless contract is redeployed. An upgradeable one gets an upgrade payload. A migratable one goes through a migration that takes two votes, and the product's operations pause for the migration and resume with it.

The record and its supporting research notes are committed on a branch, along with updated indexes for the design records. The pull request is waiting for review and has not been merged.

commits
  • ADR 0019: fixes to stateful products are migrations; a fix builds from and lands in the product's repositoryDesign records
decided
  • Drafted, not merged: a fix to a stateful product is a migration, and it builds from and lands in the product's own repository
  • A product's manual declares how each contract can change (stateless, upgradeable, migratable or fixed), and the check that validates a manual refuses a manual that leaves a fund-holding contract stateless
  • The fix path follows the declaration: redeploy for stateless, an upgrade payload for upgradeable, a two-vote migration for migratable, with operations pausing for the migration and resuming with it
open
  • The pull request is waiting for review and merge

Also on Wednesday, 14 October 2026