Manage Entity Mutations and Unsaved Changes in the Back End

[AerunDev]

As a Pokémon Studio contributor
I want entity mutations and unsaved changes to be managed by the back end
So that every create, update, and delete operation changes validated project state predictably

Parent

• Centralize Project State Management in the Back End #292

Context

The parent contract requires getEntity, createEntity, deleteEntity, updateEntity, getEntityList, and hasProjectAnyChanges. Updates also establish the entity-scoped history used by #49.

The back-end history may be keyed by entity type and identifier, but its user-visible lifetime must remain consistent with #49: changing entity or page clears the active history, and returning does not restore it.

Acceptance Criteria

• The back end can create a valid entity for a registered entity type and identifier.
• Creating an entity makes it available through both the entity read operation and the relevant entity list.
• The back end rejects an invalid or conflicting entity creation with an actionable error and without changing existing project data.
• The back end can update an existing entity with data that passes the registered validator.
• Updating an entity changes only the targeted entity and any entity lists explicitly identified as affected.
• The back end rejects an invalid update with an actionable error and preserves the last valid entity state.
• A successful entity update records the previous state in the history entry for that entity.
• A new successful update after an undo clears the obsolete redo branch for that entity.
• The back end can delete an existing entity without deleting unrelated entities.
• Deleting an entity removes it from the relevant entity list and makes the prior entity query unavailable.
• Creating, updating, or deleting an entity marks the project as containing unsaved changes.
• A failed mutation does not mark an otherwise clean project as changed.
• Each successful mutation identifies the entity and list query keys that must be invalidated.
• Creating an entity invalidates the unsaved-change state and the relevant entity list.
• Deleting an entity invalidates the unsaved-change state, the relevant entity list, and the deleted entity query.
• Updating an entity invalidates the unsaved-change state, the affected entity query, and every affected entity-list query.
• Switching entity or page can clear the active history as required by Implement Entity-Scoped Undo and Redo #49 even if the internal storage is keyed by entity.

Out of Scope

• User-facing Undo and Redo controls, shortcuts, and complete history behavior, which remain in Implement Entity-Scoped Undo and Redo #49.
• Saving changes to disk.
• Binding multilingual text into entity properties.
• Migrating every front-end consumer away from the legacy global state.
• Changing user-facing database workflows.

Decisions Still Required

• Define identifier allocation and conflict behavior for entity creation.
• Define deletion behavior for entity references and for an entity's retained history.
• Define which entity updates affect additional entity lists.
• Finalize the boundary between the mutation history recorded here and the navigation-scoped history lifecycle required by Implement Entity-Scoped Undo and Redo #49.
• Define whether create and delete operations are included in the first Undo and Redo inventory.

Dependencies

• Parent contract: Centralize Project State Management in the Back End #292
• Read-only project-state contract: Expose Read-Only Project State through React Query #807
• Coordinate entity-scoped history behavior with Implement Entity-Scoped Undo and Redo #49.

Validation Notes

Validate valid and invalid creates, updates, and deletes; entity-list changes; dirty-state transitions; protection of unrelated entities; an update after undo; and clearing active history on entity or page change. Automated tests are strongly encouraged for validation, dirty state, and history branching, but are not required to complete this ticket.