Skip to main content
Formation exposes release compatibility metadata at GET /.well-known/mesh-release. Deployment tooling can use it when deciding whether a specific older application image has been approved as a rollback target. The endpoint does not perform a rollback, and this repository does not implement a hosted deployment controller.

​
Inspect a release

The response is public JSON with Cache-Control: no-store: These are build facts, not tenant data or secrets. The fingerprint describes the binary’s embedded migrations, not a live inspection of its database. It also does not identify the running image or Git revision; deployment tooling must obtain that identity independently from its image registry or hosting provider. The current approval file is empty. There are no approved predecessors in this build. An older image without this endpoint cannot supply the metadata required by this contract.

​
What an approval means

This contract supports application rollback only across identical migration bundles, and only after explicit compatibility testing. Matching fingerprints alone are insufficient: application code can change stored data formats, background work, authentication behavior, or external protocols without changing SQL migrations. Approval does not reverse migrations, restore a backup, bypass startup guards, undo external effects, or certify arbitrary earlier releases.

​
Approving a predecessor

For a release maintainer adding a revision to internal/release/rollback-predecessors.json (repository):
  1. Verify that the candidate and exact predecessor have identical migration bundles. Retain their immutable images and establish their Git revisions.
  2. On an isolated database with representative data, run the predecessor, upgrade to the candidate, and exercise affected writes, jobs, settings, and sign-in.
  3. Stop the candidate, run that exact predecessor against the resulting database and configuration, and verify reads, writes, sign-in, and recovery.
  4. Record the rehearsal in the release PR and add the full predecessor revision. Recheck or remove approval when later behavior changes invalidate it.
The JSON file accepts unique, full 40-character lowercase Git revisions. Its presence records an explicit maintainer decision; the runtime does not run the compatibility rehearsal itself.

​
Deployment-controller responsibilities

A controller adopting this contract must retain the previous healthy image identity and compatibility evidence before replacement. It must compare the actual candidate and predecessor, refuse missing or incompatible metadata, and retain evidence outside a process that may become unhealthy. Whether a hosted service supplies these behaviors depends on that service’s implementation; Formation’s public manifest alone does not establish them. For an incompatible release, use a corrective release or a separately planned database restore. A restore can lose subsequent writes and cannot undo external side effects. Preserve the required key material with the database; see secrets and recovery. Implementation: internal/release/manifest.go (repository) and internal/migrate (repository).

​
Continuous rehearsal

Every PR and main push now rehearses each declared predecessor with tools/release/rehearse-rollback.sh <full-revision>. It rejects different migration bundles, builds both exact source versions, boots old → new → old against an isolated database, compares runtime schema fingerprints, and verifies encrypted writes made before and after upgrade using both binaries. Application/configuration compatibility still requires review; this drill cannot prove every connector or external side effect. Do not approve a predecessor merely because this test passes. Revision 26804ad1ef531d8c0110d3adf170510f16d9ebe2 was rehearsed on 2026-10-14, before the content-key and dreaming-cycle migrations landed. Those migrations invalidate its schema compatibility with the current build, so that approval has been removed. This build declares no compatible predecessor. When adding migrations, remove incompatible approvals instead of bypassing the check. An empty list explicitly means no rollback support for that release; the console keeps the disabled rollback action visible with its reason. Keep the previous image in the registry. Before a customer has run this approved predecessor, this release does not invent historical eligibility for older installations.