Module upgrade 

Erlang/OTP-style appup — declarative upgrade instructions per prior caixa version. Composes with the :behavior :on-state-change callback to deliver state migration during hot upgrades.

See theory/INSPIRATIONS.md §II.4 for the prior-art frame.

(defcaixa
  :nome   "hello-rio"
  :versao "0.2.0"
  :upgrade-from
    ((:from "0.1.0"
      :instructions ((:load-module "hello-rio")
                     (:state-change "lib/migrations/v01-to-v02.lisp")
                     (:soft-purge "hello-rio-old")))
     (:from "0.1.5"
      :instructions ((:load-module "hello-rio")
                     (:soft-purge "hello-rio-old")))))

Each (:from <prior>) block declares the upgrade path from that version to the current :versao. wasm-operator picks the matching block at upgrade time, runs the instructions in order, and only swaps traffic to the new instance after all instructions succeed (transactional upgrade). On any failure, the current version stays load-bearing — a typed atomic upgrade.

Structs

UpgradeFromEntry

One upgrade entry: the prior version we’re upgrading from, plus the instruction sequence to execute.

Enums

UpgradeError

UpgradeInstruction

One upgrade instruction. The set mirrors OTP’s appup low-level instructions: enough to express every common upgrade pattern, few enough that the wasm-operator can implement each deterministically.

Functions

validate_upgrade_from

Validate a whole :upgrade-from list: per-entry typed shape via UpgradeFromEntry::validate and the cross-entry graph-edge-set invariant — at most one (:from <prior>) block per parsed semver.

validate_upgrade_from_against_behavior

Reject :upgrade-from entries whose :instructions list carries any (:state-change <script>) instruction unless the caixa also declares :behavior :on-state-change — the runtime callback the per-version migration script is delivered through during hot upgrade.

validate_upgrade_from_against_versao

Reject :upgrade-from entries whose :from is not strictly less than the caixa’s current :versao (under SemVer-2 precedence — the same ordering semver::Version::cmp implements, with build metadata ignored per SemVer §11).