enhance rollback query with range support
Why
When a merge fails partway through, everything it already wrote to the default branch has to be reversed — the bulk graph merge and any schema-migration collateral. The existing rollback couldn't fully do that: it matched edges at one exact timestamp and restored metadata only for a node-UUID list held in memory on the DiffMerger instance. That made it blind to migration collateral for post-migration failures, a silent no-op when the merge crashed before the UUID discovery step, and unusable out-of-process — a restarted worker has no UUID list, so the upcoming infrahub recover could never share it.
Goal: one rollback mechanism, keyed only on (destination branch, merge_started_at), that reverses every write of the merge window uniformly and restores vertex updated_at/updated_by metadata from its snapshots — usable identically by the in-process failure path today and by out-of-process recovery in the next PR.
Why this is safe: the write-block shipped in the detection PR closes the default branch to client writes for the whole merge window, so everything stamped on the destination branch at-or-after merge_started_at is provably the merge's own work. The range rollback is that invariant applied in reverse. (This PR also tightens the invariant: the write-protection key is now published before the merge timestamp is stamped, so a write that slips in ahead of the block can never fall inside the rollback range.)
Non-goals (follow-ups):
- recovery entry points —
MergeFailureIdentifier.recover()and theinfrahub recoverCLI. - range indexes on edge
from/to+ nodeupdated_at. - Schema migrations co-writing
previous_updated_at/by.
This is the rollback core of IFC-2566 (reset the app to its pre-merge state). It does not close IFC-2566. That still requires the operator-facing recovery command.
What changed
Behavioral changes (what you'll observe differently):
- A failed merge now rolls back everything with a timestamp on or after the time of the merge. All of the changes during a merge should have included the same timestamp, but using a >= range ensures that nothing is missed, such as changes from asynchronous tasks run during the merge.
- The destination branch's
schema_changed_at/schema_hashare restored literally to their pre-merge values on rollback. Previously they were recomputed, which stampedschema_changed_atwith the rollback time. The same bug is fixed inSchemaUpdateCoordinator's failure path. - The rollback is idempotent and needs no in-memory state, so a re-run (or a post-restart recovery run) is safe.
Internals:
RollbackQueryrewritten: per-edge-type subqueries over all 8DatabaseEdgeTypes (relationship indexes are per-type; a label-less match uses none), with an explicitRollbackScope—AT_TIMESTAMPfor unified-timestamp callers whose branch is not write-blocked (other writers' later writes must survive),SINCE_TIMESTAMPfor the merge window.restore_metadatais validated to the default/global branches only — vertex metadata properties exist nowhere else.- The metadata restore selects the vertices adjacent to reverted edges plus the owner
Nodeone hop up viaHAS_ATTRIBUTE/IS_RELATED(a value change reverts edges only on the Attribute vertex, while the merge metadata bump also stamps the owning Node), filtered byupdated_atinside the window. DiffMerger.rollback(merge_started_at)runs the range query with no UUID list; the UUID-scoped rollback, its_affected_node_uuidsinstance state, andGraphMerger.rollback()are deleted. A_merge_startedguard keeps routine pre-write failures (unresolved conflicts, constraint violations) from paying for a full range scan.MergeRollbackHandlergets its collaborators by constructor injection (both branches, the diff merger, the schema manager) and receives the captured pre-merge state as a frozenPreMergeState.- The orchestrator publishes the write-block key first, then stamps
merge_at, then capturesPreMergeState.
What stayed the same: the healthy-merge happy path; no database migration; the coordinator's rollback semantics on user branches (rebase, branch schema loads).
Suggested review order
backend/infrahub/core/query/rollback.py— the range query itself: scope modes, per-edge-type phases, orphan cleanup, metadata-restore phase.backend/infrahub/core/diff/merger/merger.py— the new rollback entry and the removal of the UUID instance state.backend/infrahub/core/merge/(rollback_handler.py,orchestrator.py,builder.py,graph_merger.py) — the unified in-process path,PreMergeState, and the key-before-timestamp reorder.backend/infrahub/core/schema/update_coordinator.py— exact-timestamp scope + literal hash/changed-at restore.- Tests —
backend/tests/component/core/diff/query/test_rollback.py(new),backend/tests/integration/diff/test_merge_rollback.py(extended), mechanical keyword updates across the merge component tests.
Impact & rollout
- Backward compatibility: purely internal — no schema, API, enum, or config change; no migration.
- Performance: the range query runs only on merge-failure/recovery paths. Real performance testing will come later. Depending on how it goes, changes to the query or indexes on certain properties might be required.
- ⚠️ Known gap until IFC-2716: schema migrations bump vertex
updated_at/bywithout writingprevious_*snapshots, so migration-collateral vertices of a failed merge restore to an empty value rather than their true pre-merge metadata. The structural revert is complete either way; the metadata co-write lands with IFC-2716. - Deployment notes: safe to deploy; behavior changes only manifest when a merge fails.
Checklist
- Tests added/updated
- Changelog entry — intentionally omitted; folded into the
infrahub recoverPR's changelog once the operator-facing command lands - External docs — n/a (no user-facing surface changed)
- Internal .md docs updated (
dev/specs/ifc-2437-merge-failure-recovery/*task tracking) - I have reviewed AI generated content
Summary by cubic
Adds a range-based rollback with timestamp scopes and optional metadata restore, and unifies merge rollback to use it. Improves merge failure recovery for IFC-2566 and correctly restores branch schema_hash and schema_changed_at.
-
New Features
- Rewrote
RollbackQuerywithRollbackScope.AT_TIMESTAMPandRollbackScope.SINCE_TIMESTAMP, per-edge-type phases, and orphan cleanup. - Optional
updated_at/byrestore driven by edges + owningNode, allowed only on default/global branches; idempotent and validated. DiffMerger.rollback(merge_started_at)runs a SINCE range with metadata restore; orchestrator publishes the merge write-block before stampingmerge_atand cleans it up if setup fails.
- Rewrote
-
Refactors
- Unified in-process merge rollback onto
DiffMerger.rollback(merge_started_at); removedGraphMerger.rollbackand the UUID-scoped paths. MergeRollbackHandlernow restores the destination schema content and literally resetsschema_hash/schema_changed_atviaPreMergeState; reopens the source branch and clears the write block.SchemaUpdateCoordinatorkeeps exact-timestamp rollback (no metadata restore) and now restoresschema_hash/schema_changed_atliterally on failure.
- Unified in-process merge rollback onto