There is no moment at which "this installation is up to date" is true

[BechsteinDigital]

Finding

Each plugin migrates itself when it activates, under its own Postgres advisory lock derived from its pluginId (PluginDbContextFactory<TContext>.MigrateAsync). That is correct in isolation and races nothing.

What it does not give us:

• No ordering across plugins. Activation order is the only order there is.
• No single point of truth. An operator upgrading a host cannot run one command and know the installation is consistent; they activate plugins and hope.
• No record of what was touched. A migration that goes wrong leaves us restoring a full backup, because nothing wrote down which tables the run modified.
• No pre-flight conflict check. Two plugins fighting over the same overridable service is discovered at runtime, if at all.

What Frappe does

frappe/migrate.py defines SiteMigration as a named, documented sequence — before_migrate hooks → pre-model-sync patches → schema → post-model-sync patches → dashboards → jobs → fixtures → customizations → languages → www pages → after_migrate — with each step wrapped in an @atomic decorator that commits or rolls back.

Three details are directly transferable:

1. touched_tables.json — the run writes down which tables it modified. A targeted backup instead of a full one, and a much shorter list to check when something looks wrong afterwards.
2. Conflict warning before the schema step — pre_schema_updates collects override_doctype_class across all installed apps and warns: "The controller for X is overridden by multiple apps: a, b." Detected before anything is written, not after.
3. A single command with a stated contract, so "is this site migrated?" has an answer.

Proposal

1. A host-level migration orchestrator that runs every installed plugin's pending migrations in a deterministic, dependency-aware order (we already resolve dependencies and requiresCapabilities at install; reuse that graph), records the outcome per plugin, and reports one verdict.
2. Write a touched-relations manifest per run — plugin schemas and tables — as an artifact an operator can act on.
3. Run the conflict check before any schema work: two plugins claiming the same replaceable extension point, or the same overridable service. We already have this shape in the Admin frontend as getServiceConflicts() (src/core/extensions/services.ts); the backend has no equivalent.
4. Expose it as a callora CLI verb and through the operator API, so it is scriptable in a deployment.

Done when

• One command migrates every installed plugin in a deterministic order and reports a single pass/fail verdict
• A test asserts ordering follows the dependency graph, not activation order
• The touched-relations manifest is written and covers a multi-plugin run; a test pins its content
• Backend conflict detection exists and reports before schema changes are applied; a test with two colliding test plugins pins the warning
• docs-site/maintainer/migration-and-rollback.md documents the sequence, and a documentation gate under tests/Callora.Core.Tests/Documentation/ keeps the described order honest

Prior art

frappe/migrate.py (SiteMigration, atomic, pre_schema_updates).

Found while reviewing frappe/frappe against this repository.

[BechsteinDigital]

Design draft — and a correction to this issue

Read the code before drafting. One claim here is wrong and one is misleading.

Wrong: "no ordering across plugins"

PluginActivationOrdering exists and produces a dependency-safe order from declared capabilities and tier, feeding PluginActivationPlanner. It is used by both startup paths (auto-load and DB rehydration). There is an order, and it is derived rather than incidental.

Its own comment records an earlier bug worth knowing about here: IsFoundation was hard-coded to false, so "foundation first" was a dead parameter in production while the manifest value was parsed and dropped. That is the same failure class as #367 — and it is already fixed.

Misleading: "each plugin migrates on activation"

True, but it understates the constraint. The host never calls MigrateAsync. The plugin does, from its own StartAsync:

// custom/plugins/videoconference/…/VideoConferencePlugin.cs:79
await dbContextFactory.MigrateAsync(cancellationToken);

The host cannot know when a plugin migrates, because migrating is something the plugin does to itself. Everything this issue asks for runs into that.

The decision that comes before any code

Does the host take migration over, or does it only observe?

Take it over — the host calls MigrateAsync for every installed plugin in dependency order, before activation. Gives a real verdict, real ordering, one command. Costs: IPluginDbContextFactory.MigrateAsync stops being the plugin's to call, every existing plugin's StartAsync becomes wrong, and it is a contractVersion bump. It also assumes every plugin migrates through EF, which IPluginMigration says is not guaranteed.

Observe — the host asks each plugin whether it is migrated and reports. No contract break, and the verdict is honest for anything that answers. Costs: a new contract member, and a plugin that does not implement it is simply unknown — the verdict has holes, and holes in a verdict are how you get a false "everything is fine".

I would observe, and say so plainly in the report: n plugins current, m unknown. A verdict that admits what it cannot see is worth having; one that quietly counts unknown as fine is not. Taking migration over is a defensible move but it is a contract change, and it should be argued on its own rather than smuggled in behind a status command.

What is worth building either way

Two of the three Frappe ideas do not depend on that decision:

Touched relations. Recording which schemas and tables a run modified turns "restore the backup" into something targeted. Cheap, and useful regardless of who triggers the migration.

Conflict detection before schema work. Two plugins claiming the same replaceable extension point, or the same overridable service. getServiceConflicts() already exists in the Admin frontend (src/core/extensions/services.ts); the backend has no equivalent. This is independent of migration entirely and would probably be better as its own issue.

Suggested split

• This issue → the status command, once the observe/take-over question is answered.
• New issue → backend conflict detection, which needs no migration decision at all and is the piece I would build first.