Restore named project snapshots

docs/circuit-list-editor-api.md

@@ -44,6 +44,16 @@ this value for optimistic concurrency checks.
   - snapshot creation does not increment the project revision or alter
     undo/redo stacks
   - duplicate names and stale revisions return `409`
+- `POST /projects/:projectId/snapshots/:snapshotId/restore`
+  - body: `{ "expectedRevision": 13 }`
+  - verifies the stored payload checksum and atomically restores the complete
+    supported project state as revision `14` with source `restore`
+  - stores the complete pre-restore state as the inverse command, so project
+    Undo/Redo can revert or repeat the restore after a restart
+  - stale revisions or state checks return `409`; unknown snapshots return
+    `404`
+  - clients cannot submit arbitrary `project.restore-state` payloads through
+    the generic command endpoint
 
 The public dispatcher currently supports `circuit.update`, `circuit.insert`,
 `circuit.delete`, `circuit-device-row.update`,

docs/circuit-list-editor-interactions.md

@@ -142,5 +142,6 @@ Covered operations include:
 - renumber and identifier update flows
 - apply sorted order
 
-The toolbar currently exposes availability through its Undo/Redo buttons. A
-browsable revision timeline and named restore points are separate future work.
+The toolbar currently exposes availability through its Undo/Redo buttons.
+Named restore points can be created, listed and restored through the API. A
+browsable revision/snapshot UI remains future work.

docs/circuit-list-editor-known-limitations.md

@@ -7,8 +7,9 @@
 - A paginated revision-metadata API exists, but there is no browsable timeline
   UI yet; the editor currently exposes only the next eligible Undo/Redo
   actions.
-- Named logical project snapshots can be created and listed through the API,
-  but snapshot UI, periodic snapshots and restore are not implemented yet.
+- Named logical project snapshots can be created, listed and restored through
+  the API with persistent Undo/Redo. Snapshot UI and periodic snapshots are
+  not implemented yet.
 - No Revit/CSV/IFCGUID import and export workflow is implemented yet.
 - Persistence currently targets local SQLite; PostgreSQL is an architectural option, not an implemented runtime.
 - The global device library supports basic CRUD and copy operations, but has no

docs/current-architecture.md

@@ -108,8 +108,15 @@ schema-versionierten Projektzustand mit SHA-256-Prüfwert. Enthalten sind
 Projekteinstellungen, Verteiler, Stromkreislisten, Bereiche, Stromkreise und
 Gerätezeilen sowie Projektgeräte, Geschosse und Räume. Globale Geräte,
 Legacy-Consumer und Migrationsberichte sind nicht Teil des Projekt-Snapshots.
-Create/List verändern weder Projektrevision noch Undo-/Redo-Stapel; Restore ist
-noch nicht implementiert.
+Create/List verändern weder Projektrevision noch Undo-/Redo-Stapel.
+`POST /api/projects/:projectId/snapshots/:snapshotId/restore` prüft Payload,
+Prüfsumme, erwartete Revision und den unmittelbar zuvor gelesenen
+Projektzustand. Der Restore ersetzt alle unterstützten Projektdaten in einer
+Transaktion und schreibt dabei eine neue Revision mit Quelle `restore` sowie
+ein vollständiges inverses Kommando. Undo und Redo können deshalb auch einen
+Restore nach einem Neustart exakt zurücknehmen oder wiederholen. Kompatible
+Upgrade-only-Verknüpfungen und Migrationsnachweise bleiben erhalten, obwohl sie
+nicht Bestandteil des logischen Snapshots sind.
 `circuit-device-row.move` verschiebt oder sortiert eine oder mehrere Zeilen
 zwischen vorhandenen Stromkreisen derselben Liste. Erwartete und neue
 Stromkreis-/Sortierpositionen machen Forward und Inverse deterministisch;

docs/project-history-and-external-model-architecture.md

@@ -88,6 +88,15 @@ Implemented named-snapshot foundation:
 - snapshot creation/listing does not create a project revision or affect
   undo/redo eligibility
 - public Create/List endpoints expose metadata but not the logical payload
+- restore verifies the stored checksum and a hash of the complete current
+  state before replacing supported project data in one transaction
+- restore records a new `restore` revision containing both the selected target
+  state and the complete pre-restore inverse; undo/redo therefore remains
+  available after application restarts
+- compatible upgrade-only Consumer links, mappings and reports are preserved
+  separately and are never imported into the logical snapshot payload
+- arbitrary restore payloads are rejected by the generic user-command
+  endpoint; only server-stored snapshots can initiate a forward restore
 
 ## Revit / CSV / IFCGUID Round-Trip Direction
 
@@ -243,7 +252,7 @@ Completed foundation:
 
 Remaining constraints before completing project version history:
 
-- add a browsable timeline/snapshot UI, periodic snapshot policy and restore
+- add a browsable timeline/snapshot UI and periodic snapshot policy
 - extend project-scoped commands only when further project mutations are
   deliberately added to history; the generic versioned envelope is complete
 - do not model IFCGUID as an overloaded circuit equipment identifier

docs/spec/07-implementation-phases-todo.md

@@ -369,7 +369,8 @@ Tasks:
 - [x] add explicitly named logical project snapshots with schema-versioned
   payloads and integrity checksums
 - add periodic logical project snapshots
-- restore a historical snapshot as a new revision
+- [x] restore a historical snapshot as a new auditable revision with
+  persistent undo/redo
 - keep database backups separate from logical history
 
 Implemented foundation: