Checkpoints and Rollback

Checkpoints and Rollback

Language: English · 简体中文

LWC provides two recovery boundaries:

• a checkpoint is a named, full SQLite snapshot of one live Wiki;
• a changeset rollback is a conflict-aware inverse of only the entities touched by one committed changeset.

Choose the smallest boundary that matches the failure. Use changeset rollback for one published logical change; use a checkpoint before a broad operation whose exact inverse is not otherwise available.

When to create a checkpoint

Create one before:

• a broad replacement of existing Pages;
• a multi-source ingest performed outside a changeset;
• a manual recovery or migration with a large blast radius;
• an operational experiment that may require restoring the complete Wiki database.

Do not create checkpoints around every transactional command. Single mutations already commit atomically, and routine snapshots add storage without improving their safety.

Create and list

lwc --scope project checkpoint create before-architecture-refresh
lwc --scope project checkpoint list

Creation uses SQLite's online backup API and does not change Wiki knowledge. Names are validated as safe local identifiers. An existing checkpoint is never overwritten.

list returns checkpoints in deterministic name order with their paths and sizes.

Checkpoint commands operate on one live project or global Wiki. They reject --scope all and cannot run inside a draft changeset.

What a checkpoint contains

A checkpoint captures the complete canonical Wiki database at one committed point: Sources, ingest state, Pages, provenance, tags, search state, feedback, operation history, and other SQLite-backed records.

It does not copy deployment-local configuration, the generated Markdown directory, the document-graph sidecar, or the CodeGraph runtime. Those are outside wiki.db:

• current graph configuration remains in effect;
• generated Markdown is materialized after restore;
• the enabled document graph is fully reprojected from restored canonical state;
• CodeGraph remains an independent index of project source files.

Restore safely

lwc --scope project checkpoint restore before-architecture-refresh

Restore performs these safety steps:

1. opens the named checkpoint read-only and validates its schema and integrity;
2. prepares and validates a private restore candidate before touching live data;
3. creates a fresh pre-restore-* checkpoint of the current live database;
4. obtains the live write lock and rejects the restore if live revision advanced during preparation;
5. replaces the live database through SQLite backup;
6. queues full document-graph projection when a graph engine is enabled;
7. regenerates materialized Markdown.

The response includes the restored checkpoint and the generated safety_checkpoint. Keep that name with the incident record; it is the recovery point for the state that existed immediately before restore.

Restore waits only for canonical database replacement. Graph projection remains Work and must be watched separately.

Verify a restore

lwc --scope project checkpoint restore before-architecture-refresh
lwc --scope project work watch <graph-work-id>
lwc --scope project lint
lwc --scope project search "known answer" --limit 5
lwc --scope project graph verify

If graph support is disabled, restore returns no graph_work; skip only the Work and graph checks. Still verify canonical Pages, search, lint, and materialized Markdown.

Verify both absence and presence. Confirm the unwanted post-checkpoint state disappeared and the expected checkpoint state returned.

Partial-success errors

Canonical restore can succeed before a later projection fails. LWC reports these cases explicitly with details such as:

• checkpoint_restored=true;
• the source checkpoint name;
• the generated safety checkpoint;
• graph_work when graph queueing succeeded;
• one exact recovery_command or a list of recovery_commands.

Run those commands exactly. Do not retry the original knowledge mutations, and do not assume a generic error means the database stayed unchanged.

Typical follow-up commands are:

lwc --scope project maintenance materialize
lwc --scope project config set --graph grafeo

The graph recovery command uses the restored Wiki's scope, even when its graph setting was inherited from global configuration.

If restore cannot safely prepare or acquire a stable live revision, it returns checkpoint_restored=false. A busy conflict is retryable; a structurally invalid checkpoint is not.

Changeset rollback

Use the stable changeset ID returned by commit:

lwc --scope project changeset rollback <changeset-id>
lwc --scope project work watch <graph-work-id>
lwc --scope project graph verify

Changeset rollback is narrower than checkpoint restore. It uses a checksummed inverse patch and restores only touched entities. If a later write changed one of them, rollback returns changeset_rollback_conflict instead of overwriting newer work.

It also restores Source path heads, remapped Source IDs, Page citations, tags, and document-graph projection. Repeating the same rollback is idempotent and is the recovery path when canonical rollback succeeded but later cleanup or projection failed.

Choosing the boundary

Need	Use
Undo one committed multi-command knowledge update	Changeset rollback
Preserve later unrelated live writes	Changeset rollback
Return the entire Wiki database to an earlier point	Checkpoint restore
Protect a broad non-changeset ingest or migration	Checkpoint create before the operation
Repair only derived Markdown, search, or graph state	Maintenance or graph reprojection, not restore

Safety rules

• Never edit a checkpoint database or graph sidecar manually.
• Never copy a live WAL-mode wiki.db file as an ad hoc backup; use checkpoint create.
• Record the exact scope, checkpoint name, and acceptance checks before restore.
• Treat database_busy as a concurrency signal; do not bypass the revision guard.
• Keep the automatic safety checkpoint until live acceptance is complete.
• Do not use checkpoint restore to switch graph engines or deployment configuration.

Completion evidence

Recovery is complete when:

• the chosen boundary matches the intended blast radius;
• the restore or rollback response identifies its recovery artifact;
• canonical Pages, Sources, tags, and retrieval match the expected state;
• materialized Markdown is current;
• any returned graph Work reached succeeded;
• graph verify reports ok=true when enabled;
• partial-success recovery commands were executed and rechecked;
• the pre-recovery state remains available until acceptance finishes.

Next: Read-only Viewer