Skip to content
Looms
Documentation
On this page

Changing deployed code

A run records the exact version of every definition it starts. Recovery resolves that version, so the host must keep its implementation registered while the run can still wake. Looms does not store the historical code bundle for you.

This durability contract is separate from the SemVer version of @swirls/looms. A compatible package upgrade can still require a durable-definition or event migration for your application.

Keep old definitions available#

Set the definition's version, and register old and new versions together. Starts and child spawns persist kind:name@version; they never resolve to a floating latest version. Keep shared reducers and event contracts compatible with both versions.

Evolve events additively#

Existing logs contain old payloads. Prefer optional fields with defined defaults or new event names for incompatible meanings. Keep old logs and snapshots as compatibility test fixtures. A module's protocolVersion is descriptive metadata, not an automatic migration engine.

Plan snapshot changes#

Reducers and snapshot state must agree. Test loading existing snapshots before deployment. When a change is incompatible, keep the old implementation routed to old runs, migrate those runs with your own tools, or let them finish before retiring the old code. Do not rewrite historical events casually to make a new reducer accept them.

A deployment procedure#

  1. Inventory active and parked runs through your run index.
  2. Run old-history and snapshot compatibility tests.
  3. Deploy code that can still execute old definitions.
  4. Start a canary using the new definition and exercise reject, timeout, and restart paths.
  5. Monitor failures and keep the prior deployment available.
  6. Retire old definitions after their runs finish and you no longer need them for retained history.

Rollback limits#

A rollback cannot undo external actions. Old code may not understand events written by a new deployment. Plan forward-compatible readers or a controlled recovery procedure before rollout. Restoring a database backup also requires reconciling actions performed since the backup.