Add named project snapshots

docs/circuit-list-editor-api.md

@@ -32,6 +32,18 @@ this value for optimistic concurrency checks.
   - body: `{ "expectedRevision": 1 }`
   - executes the eligible inverse or forward command as a new auditable
     revision
+- `GET /projects/:projectId/snapshots`
+  - lists named logical snapshot metadata without returning payload JSON
+- `POST /projects/:projectId/snapshots`
+  - body:
+    `{ "expectedRevision": 12, "name": "Vor Ausschreibung", "description": "Optional" }`
+  - atomically captures the complete project-scoped runtime state at the
+    expected revision
+  - returns `201` with source revision, schema version, SHA-256 and creation
+    metadata
+  - snapshot creation does not increment the project revision or alter
+    undo/redo stacks
+  - duplicate names and stale revisions return `409`
 
 The public dispatcher currently supports `circuit.update`, `circuit.insert`,
 `circuit.delete`, `circuit-device-row.update`,

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

@@ -7,7 +7,8 @@
 - 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 and restore are not implemented yet.
+- Named logical project snapshots can be created and listed through the API,
+  but snapshot UI, periodic snapshots and restore 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

@@ -100,6 +100,16 @@ Stromkreis-Reorders und die explizite Neunummerierung im Grid verwenden die
 persistenten Kommandos. Die Toolbar leitet ihre Undo-/Redo-Verfügbarkeit direkt
 aus den serverseitigen Stack-Tiefen ab, sodass ein Reload die Bedienbarkeit
 nicht unterbricht.
+
+Benannte logische Projektstände werden in `project_snapshots` getrennt von
+Datenbank-Backups gespeichert. `POST /api/projects/:projectId/snapshots`
+erzeugt bei passender erwarteter Revision transaktional einen vollständigen,
+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.
 `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

@@ -75,6 +75,20 @@ Project history must use logical project data, not copies of the SQLite database
 
 Large snapshots may later be compressed or stored in object storage, with metadata and checksums retained in the database.
 
+Implemented named-snapshot foundation:
+
+- `project_snapshots` stores project ownership, source revision, schema
+  version, name, optional description, logical payload, SHA-256 and creation
+  metadata
+- snapshot creation requires the expected current revision and reads plus
+  stores the complete project state in one SQLite transaction
+- the versioned payload contains project settings, distribution boards,
+  circuit lists, sections, circuits with device rows, project devices, floors
+  and rooms while excluding global and upgrade-only data
+- 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
+
 ## Revit / CSV / IFCGUID Round-Trip Direction
 
 External model exchange should use explicit staging and link entities instead of writing imported rows directly into circuits.
@@ -229,7 +243,7 @@ Completed foundation:
 
 Remaining constraints before completing project version history:
 
-- add a browsable timeline UI plus named logical snapshots and restore
+- add a browsable timeline/snapshot UI, periodic snapshot policy and restore
 - 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

@@ -366,7 +366,9 @@ Tasks:
   update command types
 - [x] expose a cursor-paginated, read-only revision metadata timeline without
   command payloads
-- add named and periodic logical project snapshots
+- [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
 - keep database backups separate from logical history
 
@@ -391,6 +393,9 @@ Implemented foundation:
   change-set ids
 - a separate read-only timeline endpoint exposes immutable revision metadata
   in descending, cursor-paginated pages without forward/inverse payloads
+- named snapshot Create/List endpoints persist complete project-scoped runtime
+  state with the source revision and SHA-256 without changing revision or
+  undo/redo stacks
 - a central application dispatcher reconstructs persisted commands and exposes
   optimistic command, undo and redo endpoints for Circuit and CircuitDeviceRow
   field updates