Add change set revert by pournasserian · Pull Request #2511 · fluentcms/FluentCMS

pournasserian · 2026-10-18T23:20:17Z

What

The fifth slice of F-CHG (#2418): one revert action (CHG-06, D22), built on atomic publish (#2482). Reverting a published set opens a new set that puts every item back at the version it had before the original. Publishing that set restores the live content and moves the original to reverted, in one unit of work.

Core (FluentCMS.Core.ChangeSets):
- ChangeOperation.Inverse(): a create becomes a delete of the created version, an update becomes an update from its proposed version back to its base, and a delete becomes a create of the deleted version. An update back to an earlier version exists only this way; ChangeOperation.Create still asks for a later one.
- ChangeSet.Revert(rationale, initiator) opens a set with the inverse of every operation in the original's order. It names the original in RevertsChangeSetId instead of citing sources. Only a published set can be reverted (transition_not_allowed), and a revert set takes no further operations (revert_set_fixed).
Directory:
- RevertAsync(changeSetId, rationale) stores the revert set and its operations with change_set.opened and one change_set.operation_added each, whose previous version is the row of the version the original published. Before the unit of work it refuses an unknown set, a set that is not published, a blank rationale, and an item that moved on since (base_version_stale, as the revert's publish would).
- PublishAsync of a revert set also moves the original from published to reverted over its revision, and appends change_set.reverted after change_set.published. If the original is no longer published, nothing is written.
- TransitionAsync to reverted is refused with transition_not_allowed, after Refuse agents' review moves and enforce change set caps #2503's agent check, so an agent's attempt is still logged.
Agents cannot revert: RevertAsync runs the move check for reverted from Refuse agents' review moves and enforce change set caps #2503 (MCP-06). People are not capped, so the change set caps do not apply.
Infrastructure: ChangeSets.RevertsChangeSetId, nullable and indexed, with a foreign key to the reverted set. Migrations for SQLite and PostgreSQL.

Why

ADR-0005 says a revert restores the previous version pointers, so a revert proposes the earlier, stored version instead of writing a copy. Live content then reads exactly as it did before the original, and the diff, the stale check and publish all work on it unchanged.

Choices worth a look:

A revert is a normal set. It goes through checks and review like any other (S3 talks about it publishing), and nothing moves until it is published. Fixing its operations keeps "restores exactly what the original changed" true while it waits.
The stale check runs when the revert opens. A revert of a set whose item has moved on could never publish, so it is refused at once with the same message publish would give.
Two reverts of one set: the second one's publish fails, because the items have moved on and the original is no longer published, so the original is reverted once.
The original moves with the revert's publish, not when the revert opens. Until then the original is still what is live.
Not in this PR: fact propagation (F-PRP, M3), the correction as rule feedback (RUL-08), the desk's revert action, the MCP tool, webhooks on revert, and other item kinds, which publish with their epics.

Tests

Unit (Core):

The inverse of a create, an update and a delete, and the inverse of the inverse.
An update back to an earlier version is refused by Create.
A revert holds the inverse operations in order, names the original, has no sources, and leaves the original as it was.
Only a published set can be reverted. A revert needs a rationale and takes no further operations.

Integration, each on SQLite and PostgreSQL:

Reverting a published set with a create, an update and a delete stores the inverse operations, with each event naming the row it is based on. The diff shows the update going back.
Publishing the revert puts every content type back at its earlier published version and reverts the original. The events are one per item, then change_set.published and change_set.reverted.
Reverting the revert publishes the original's versions again.
An unknown set, an open set, a set whose item moved on and a blank rationale are refused without writing a set or an event. An operation added to a revert set and TransitionAsync to reverted are refused.
An agent's revert is refused and logged as agent.transition_refused.
Of two reverts of one set, only the first publishes.
A failure injected at each of the five audit appends of a revert's publish leaves the items, the revert and the original as they were.

dotnet build -warnaserror and the full suite pass locally on SQLite and against a postgres:17 container. No new package and no new project reference.

Checklist

Linked to an issue a maintainer has confirmed
Targets v2
Tests or docs updated where behaviour changed
No tool-generated co-author trailers or footers

Closes #2515 ## What The next F-CNT (#2416) slice: change sets hold operations on entries and entities, and diff, publish and revert them like schema operations (CHG-01, CHG-03, CHG-05, CHG-06). Builds on atomic publish (#2482) and revert (#2511). This is the first thing that moves `Entries.PublishedVersion`. - **Item kinds**: an `entry` operation must point at an entry of a plain content type, and an `entity` operation at an entry of an entity type, in each case of a type the agent's scope allows for the operation (MCP-05). The wrong kind fails with the new `item_kind_mismatch`. A missing or soft-deleted entry fails with `item_not_found`, and a missing version with `version_not_found`. `change_set.operation_added` carries the base version's row as previous version, as for schema items. Other kinds (media, rules) are still `item_kind_unavailable`. - **Diff** (`ItemDiff.ForEntry` in Core): two versions of an entry, field by field, with `ValueDiff.Compare`. On an entity a field's value is its whole fact, so a new source shows as a change. Fields follow the definition the shown version was written against, so the order is the same on SQLite and PostgreSQL even though `jsonb` reorders keys. `DiffAsync` reads every version the entry operations name, with their definitions, in one query. - **Publish**: each entry's published version moves from its operation's base version to the proposed one with a conditional update, alongside schema items in the same unit of work. Stale bases fail with `base_version_stale` before anything moves, and a soft-deleted entry fails with `item_not_found`. Events: `entry.published` / `entry.unpublished`, or `entity.*`. - **Delete means unpublish**: a published delete clears the published version and keeps the entry, its draft and its history. Revert of a create unpublishes, and revert of a delete publishes the base version again, through the same publish. - **One history per entity**: `EntryDirectory` now names entries of entity types `entity` in its events (`entity.created`, `entity.updated` and so on), so an entity's own events and the change set events about it share a subject. ## Why Entries were stored and versioned (#2491) but nothing could put them live. Publishing through change sets keeps CHG-05's all-or-nothing rule for mixed sets of schema, entry and entity items (CHG-09), and revert comes for free from `ChangeOperation.Inverse`. Choices worth a look: - **Separate kinds for entries and entities** let the desk and blast radius (ENT-04) tell content changes from fact changes, without a lookup per item. - **A published delete unpublishes rather than soft-deletes**, so its revert only has to move a pointer back. Soft delete stays a direct action with its retention window (#2502). The entry states slice will call an unpublished entry archived. - **Writes do not join change sets themselves yet.** A write stores a draft version and an operation points at it, as content types did before SCH-05. Entry writes will follow the change set target that #2514 introduced, together with the entry tools. - **Changes to the F-CHG lane's file are kept in separate methods** (`ResolveEntryAsync`, `EntryDiffsAsync`, `PublishedEntriesAsync`, `PublishableEntry`), so the SCH-05 work merges easily. ## Tests Unit (Core): - `ItemDiff.ForEntry`: changed fields in definition order, with a removed field the type no longer has last; formatting-only differences ignored; facts compared whole; create and delete; refusal of non-entry operations and of fields that do not match the operation's versions. Integration, each on SQLite and PostgreSQL: - An agent cannot add an operation on an entry of a type outside its scope. - Entry and entity operations stored with their kinds and events; the wrong kind both ways, a missing entry, a soft-deleted entry and a missing version each fail and write nothing; an update's event carries its base version's row. - The diff of an entry update and an entity create. - Publishing moves both pointers with one event per item; a resolved view follows the published price, not a new draft; an entity's own and change set events share its history. - A stale base and a soft-deleted entry fail the publish and move nothing. - A published delete unpublishes and keeps the entry; its revert publishes it again and marks the delete reverted. - Reverting an update puts the earlier version back, and its diff shows the change backwards. - A failure injected at each audit append of a publish leaves no entry published. The full suite ran locally against a `postgres:17` container as well as SQLite, after merging the latest v2. No migration, no new package and no new project reference. ## Checklist - [x] Linked to an issue a maintainer has confirmed - [x] Targets `v2` - [x] Tests or docs updated where behaviour changed - [x] No tool-generated co-author trailers or footers

Closes #2513 ## What The SCH-05 slice of F-SCH (#2415), on top of change set publish (#2482) and revert (#2511). Every content type write is now a change set operation. A create or a revision stores its new version and records the operation in the change set it names, in one unit of work. Nothing a write does is live until that set publishes. - **Core** (`FluentCMS.Core.ChangeSets`): - `ChangeSetTarget`: the set a write joins, either an existing set by id or a session id with the rationale and sources of the set the session's first write opens (CHG-02). - `ChangeSet.Record(operation)` adds the operation, or extends the one the set already holds for the item. The write must be based on the version that operation proposes, and the operation then proposes the write's version. A create stays a create and an update keeps its base, so a set still has one operation per item (CHG-03) and its diff runs from the base to the newest version. - **Core** (`FluentCMS.Core.Schema`): - `IContentTypeDirectory.CreateAsync` and `ReviseAsync` take a `ChangeSetTarget`. A create records a create proposing version 1, and a revision records an update from its base to the new version. - A revision's base is the latest version or the published one. In a set that already holds the type it is the version that set proposes, so the set can keep revising its own draft after another set drafts the type. Basing it on the published version leaves an unpublished draft behind, such as a rejected one. The referenced-field rule (SCH-04) then also checks the fields of every draft an open set proposes, so such a revision cannot drop a field another draft references. - A revision of a type no set has published, or one a published delete took offline (a rejected or reverted create), records a create, since there is nothing live to update. `ChangeSet.Record` takes whether the item is published, and an agent needs the create scope for such a revision (MCP-05). - A draft is a base only while a set that can still publish proposes it. A revision of a rejected or reverted draft is refused at once with `version_conflict` and points to the published version, instead of failing later at publish. While an open set proposes a draft, the latest or an older one, a revision keeps its referenced fields and its entity flag (SCH-03). A draft whose set went stale still counts until a person rejects it; #2588 tracks that. - References between types are checked against what each type is heading to: every draft an open set proposes, or its published version while there is none. A rejected draft neither drops a live reference nor offers a field to reference, and a field a pending draft removes is no target. A field another type references stays while any of that type's live versions or open drafts references it. - `GetPublishedAsync(slug)` reads the live version, or fails with `content_type_not_published`. `ContentTypeSummary` carries `PublishedVersion`. - **Infrastructure**: - `ChangeSetDirectory` gains an internal join for writes owned by another directory. `PrepareAsync` finds the expected failures before the caller's unit of work begins: unknown set, set not open, blank rationale, agent ownership and the items cap. Inside it, `BeginWriteAsync` opens the set or moves its revision, and `RecordAsync` records the operation after the item's own rows and event. An agent's daily cap is counted in `BeginWriteAsync` with its credential held, as `OpenAsync` does since #2580. It is therefore the one refusal that rolls a caller's unit of work back, and #2513's acceptance now says so. - `content_type.created` and `content_type.revised` now carry the set's id, and come after `change_set.opened` when the write opens its session's set. An extended operation appends `change_set.operation_updated`, the name #2575 uses for the same move of an entry operation. - Both directories share one `ChangeSetDirectory` per scope. - **MCP write tools** (#2514): `create_content_type` and `revise_content_type` pass their target to the directory, which now records the operation itself. `ProposedWrite` no longer opens its own unit of work or checks the set ahead of the write; the directory's checks run before anything is written, so a refused cap still keeps its security event. The answer names the kind the set recorded, so a revision of a type with nothing live reads as a create. In `WriteToolsTests` the agent's revision of the person's unpublished product is now expected as `Create null→2` instead of `Update 1→2`, which is the behaviour change agents see. The entry tools (#2525) keep the tool-level pre-check and add, since entry writes do not join change sets in their directory yet. - No migration: both pointers already exist. ## Why The decision, as written in #2513: `Version` is the latest version, which authoring builds on, and `PublishedVersion` is what is live. The authoring reads stay on the latest version: `GetAsync`, `ListAsync`, the schema document and entry validation. A set can then build on its own drafts, and entries can be written against the schema change they need in the same set (CHG-09). Delivery reads the published version when F-API arrives. Choices worth a look: - **The operation is written by the change set directory, inside the content type directory's unit of work.** Version and operation commit together, and the existing "expected failures before the unit of work" rule still holds for both. - **Extending instead of refusing a second write.** An agent iterating on a type within a session would otherwise need a new set for every revision. - **A unique index at commit** means the slug or version race it always meant. When the write opened a session's set, it may also be a concurrent first write of that session, so that case answers with `change_set_conflict`. - **Two revisions racing into the same set**: the loser now fails with `change_set_conflict`, since the set's revision moved first, rather than `version_conflict`. The race tests give each writer its own set to keep checking the version race. - **Reference checks at write time are best effort.** Sets publish in any order, and a revert can take a field away again, so a reference can still dangle across sets. #2604 checks references at publish, which is where the order is known. It also covers dropping a field together with the last reference to it in one set, which the write-time check still refuses. - **Breaking signature**: every caller of `CreateAsync` and `ReviseAsync` passes a target. In this PR that is the MCP schema tools and tests: the schema, entry and MCP scenarios write their content model in a `content-model` session set, as a person, so agent caps and the change set reads in tests are not affected. - **Answering from the set the write joined**: the schema tools read the session's set again after the write, which can race with a submit; #2615 passes the set out of the write. - **Not in this PR**: entries as change set operations, and refusing at publish an entry whose content type version is not published (F-CNT). Also left out: deleting a content type, the MCP schema tools, the desk's schema review and delivery reading the published schema. ## Tests Unit (Core): - A later write extends the item's operation, keeping its kind and base, for a create and an update. - A later write not based on the proposed version, a delete over an update, and an update over a delete are refused and change nothing. - A write is recorded only while the set is open. Integration, each on SQLite and PostgreSQL: - A create is an operation of its set, with `content_type.created` naming the set. The type lists with no published version and `GetPublishedAsync` refuses it until the set publishes. - A revision in the same set extends the operation (create from nothing to version 2). Its events name the version it was based on, and the diff lists both fields as added. - A revision of a published type into a new set is an update from the published version. It is live only after that set publishes, and the previous version stays readable. - After a rejected draft, a revision based on the published version goes through, while one based on the rejected draft fails with `version_conflict`. - After a rejected create, and after a published create was reverted, the next revision is recorded as a create, and publishing it makes the type live again. - A revision from the published version cannot drop a field that another draft in an open set references. - Writes through a session share the set the first one opens. - An unknown set, a set that is not open and a blank session rationale are refused inside a caller's unit of work, which then commits. - Inside a caller's unit of work, an agent cannot write into another agent's set, and a write past its items cap is refused. Neither stores a content type or change set event, the cap refusal keeps its security event, and the caller's unit of work commits. - A failure injected at either audit append of a revision, after the pointer and the set's revision reached the database, leaves neither the version nor the operation. A caller's unit of work rolled back after the revision's rows were saved leaves neither either. - A rejected draft is refused as a base, while a draft an open set proposes can be built on and publishes after it. - An agent without the create scope cannot revise a type with nothing live. - A revision from the published version keeps an open draft's entity flag, and may drop it once that draft's set is rejected. - A rejected draft of a page does not let its brand drop a field the live page references, and a field only a rejected draft has cannot be referenced. - A field that a pending draft removes cannot be referenced, from the draft's own set or another one. - A field that an older open draft references cannot be removed, even when a later draft of that type is the latest. - A set keeps revising its own draft after another set drafted the type, and a revision of it from the latest version is refused with `version_conflict`. - A revision into a rejected set that holds the type is refused with `change_set_not_open`. - A revision keeps the entity flag of an older open draft when the latest draft was rejected. - A content type write that would open a set past an agent's daily cap is refused, stores no set or type, and keeps one security event. - A session's first write appends the set's opening before the content type's own event. `dotnet build -warnaserror` and the full suite pass locally on SQLite and against a `postgres:17` container. No new package and no new project reference. ## Checklist - [x] Linked to an issue a maintainer has confirmed - [x] Targets `v2` - [x] Tests or docs updated where behaviour changed - [x] No tool-generated co-author trailers or footers

) Closes #2616 ## What A follow-up of F-CHG (#2418), from the post-merge review of publish (#2482) and revert (#2511). - **Core** (`ChangeSetTransitions`): the table gains approved → rejected. - A rejection still needs a reason (CHG-08). - Only people make this move. Agents are refused it, as any move other than submit and reopen is since #2503 (MCP-06). No engine owns it in `AgentPermissions.SystemMoves` (ADR-0012). - **Entries**: a rejected set holds nothing in review (CNT-01), so the entries of an approved set that a person rejects leave review with no further change. - **Publish** moves its items sorted by item kind and id, then appends their events in the set's order. Two sets that publish the same items take their row locks in the same order: the later one waits, finds its base gone and fails with `base_version_stale`. - **Deadlocks**: a PostgreSQL deadlock (`40P01`) or serialization failure (`40001`) during a publish, or at the commit of any change set write, is answered with `change_set_conflict` instead of an exception, as a unique violation already is (`DatabaseErrors.IsConcurrencyFailure`). - **Desk**: the set view offers Reject on an approved set too, next to Publish. Its hint says to reject it with a reason if it can no longer publish. ## Why An approved set whose publish has gone stale could never leave approved. For example, two reverts of one set are both approved and the first publishes. The second then sat approved forever, and its entries stayed in review. Rebasing a stale set is out of scope: a person rejects it and the author opens a new set. Publish moved items in the order the set lists them. On PostgreSQL, two sets that list the same items in opposite orders deadlocked, and one call threw. Choices worth a look: - **Lock order instead of retry.** Sorting the pointer moves removes the cycle. The deadlock mapping stays as a safety net for writers outside publish. - **The mapping has no test of its own.** With the sort in place, two publishes no longer deadlock, and no other writer here takes two item rows. To check the race test, I removed the sort and the mapping on purpose: it failed on PostgreSQL with `40P01: deadlock detected`, and with both back it passes. - **Events keep the set's order**, so the audit log reads as the set was written, whatever order the rows were locked in. - **The desk change is two conditions and one hint.** Without it, a person had no way to reach the new move from the admin. ## Tests Unit: - The transition table lists approved → rejected, and every other transition stays as it was. - `Reject` from approved succeeds with a reason, and stays refused where the table has no rejection. - The check engine cannot reject an approved set. - The set view offers Publish and Reject for an approved set. Integration, each on SQLite and PostgreSQL: - Two reverts R1 and R2 of one published set are both approved, and R1 publishes. R2's publish then fails with `base_version_stale`, and its entry stays in review. A blank reason is refused. With a reason, R2 is rejected, the entry leaves review, and the original set stays reverted once. - Two approved sets update the same two content types from the same base, listed in opposite orders, and publish at the same time, five rounds in a row. Each round, one wins, the other fails with `base_version_stale`, and neither call throws. - The table-driven tests cover the new transition for agents (refused and logged) and for people (stored with its event). `dotnet build -warnaserror` and the full suite pass locally on SQLite and against a `postgres:17` container. No new package and no new project reference. ## Checklist - [x] Linked to an issue a maintainer has confirmed - [x] Targets `v2` - [x] Tests or docs updated where behaviour changed - [x] No tool-generated co-author trailers or footers

Add change set revert

26b01bb

pournasserian added this to the M1 Governance core milestone Oct 18, 2026

pournasserian added type:feature New capability v2 FluentCMS v2 (v2 branch) area:change-sets Change sets (CHG) labels Oct 18, 2026

pournasserian merged commit e6a3b05 into v2 Oct 18, 2026
2 checks passed

pournasserian deleted the 2510-change-set-revert branch October 18, 2026 23:23

This was referenced Oct 18, 2026

Put entry and entity operations in change sets: diff, publish and revert #2515

Closed

Put entry and entity operations in change sets #2519

Merged

Record content type writes as change set operations #2520

Merged

This was referenced Oct 19, 2026

Check schema references when a change set publishes #2604

Open

Reject an approved change set and publish items in a stable order #2616

Closed

pournasserian mentioned this pull request Oct 19, 2026

Reject an approved change set and publish items in a stable order #2637

Merged

4 tasks done

Navigation Menu

Repository navigation

Add change set revert - #2511

Add change set revert#2511
pournasserian merged 1 commit into
v2from
2510-change-set-revert

pournasserian commented Oct 18, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

pournasserian commented Oct 18, 2026

What

Why

Tests

Checklist

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant