Versions and snapshots

Explanation

This page explains how the version and snapshot mechanism in the MaShop workspace actually behaves, grounded in the code that ships. A snapshot is a stored copy of every file in your project at one moment. Restoring a snapshot rewrites your project files back to that copy. The section ends by naming the parts of the version surface that exist in code but are not yet wired, so you do not rely on behavior that is not there.

What a snapshot is

A snapshot is one row in the file_snapshots table plus one file_snapshot_entries row per file. Each entry stores the file path, its full content, and its language. The snapshot row also records a message (a short label), a file_count, an optional tokens_used count, and an optional badge.

Snapshots are stored in MaShop's own database, separate from your GitHub repository. They are tied to the project files the workspace edits, not to your git history. The version timeline in the workspace reads this table newest first.

When a snapshot is created

One event creates a snapshot: a restore. Before the workspace replaces your files with an older snapshot, it first captures the current state as a new snapshot, labelled Avant restauration de <message>. This is a safety copy so the state you are leaving is itself recoverable.

There is no automatic per-turn capture. The AI does not snapshot after each message, and there is no snapshot on project creation or on deploy. The database defines a capture routine (create_store_snapshot), but no part of the shipped workspace calls it. The practical consequence is direct: a brand new project shows an empty timeline that reads Aucun snapshot encore (no snapshot yet), and the first snapshot only appears after you run your first restore.

How restore works

Restore is the wired capability. You open the version timeline, pick a snapshot, and choose its Restaurer (Restore) action. The workspace opens a confirmation dialog titled Revenir à cette version ? (Return to this version?) that warns unsaved changes in the session will be lost. Confirming sends a request to POST /api/projects/[projectId]/snapshots/[snapshotId]/restore.

The route runs in two steps:

1. It reads your current project files and writes them into a fresh pre-restore snapshot, so the state you are about to leave is saved.
2. It calls the restore_store_snapshot database function, which deletes the current project files and re-inserts the snapshot's files in a single transaction. Because both happen inside one function body, a failure rolls back and your files are left intact rather than half-replaced.

The response reports restoredFileCount, the number of files written back. The workspace then reloads the in-memory file tree so the editor and preview show the restored files without a page reload, closes any open editor tabs whose paths no longer exist, and refreshes the timeline so the new pre-restore snapshot appears.

Who can restore

Restore requires the editor role on the project, because it rewrites files. Viewers can list and compare snapshots but cannot restore. The database function re-checks the role itself, so a request from a user without edit access is rejected. Roles are covered in Collaborators.

Comparing two snapshots

From a snapshot you can open Voir diff (View diff) to compare it against the previous snapshot in the list. The diff lists each file as added, removed, or modified, with the before and after content. Two limits keep the comparison bounded: if the two snapshots hold more than 500 files combined, the workspace refuses the diff and returns snapshot_too_large; any single file larger than 100 KB is reported as changed but without its content shown inline.

Limits and failure modes

The endpoints are rate limited per IP address: listing snapshots and diffs allow 60 requests per minute, restore allows 10 per minute. Past those, the request returns HTTP 429 with the message Trop de requêtes. Réessayez dans une minute.

Pre-restore snapshots are pruned. A daily job deletes snapshots with no badge that are older than 30 days, and keeps at most the 100 most recent per project. Because the safety snapshot the restore route creates carries no badge, it is subject to this pruning. A pre-restore snapshot is a short-term recovery aid, not a permanent archive.

Behavior	Value
Role required to restore	editor
List / diff rate limit	60 per minute per IP
Restore rate limit	10 per minute per IP
Diff file ceiling	500 files combined
Diff per-file content cap	100 KB
Pre-restore snapshot pruning	deleted after 30 days; max 100 kept per project

What is not wired

Some pieces of the version surface exist in code but are not active. Do not depend on them:

• Automatic snapshots. Nothing captures a snapshot after an AI turn, on project creation, or on deploy. The only snapshot ever written is the pre-restore safety copy.
• Badges. The timeline can render a small label such as init or deploy, but no code ever sets a badge value. Snapshots arrive without one.
• A running version history. Because there is no automatic capture and pre-restore snapshots are pruned, the timeline is not a complete record of your project over time. Your GitHub repository is the durable history.