Maintenance and Diagnostics

Maintenance and Diagnostics

Language: English · 简体中文

Diagnostics identifies whether a defect belongs to canonical knowledge, durable Work, or a derived projection. Maintenance rebuilds or compacts derived artifacts without changing Source or Page knowledge; recovery restores an intended state after failure. Start with the narrowest command that repairs the demonstrated problem.

Recovery ladder

Use this order:

1. Wait or resume Work when canonical state is correct and execution stopped.
2. Rebuild one derived projection when Markdown, FTS, document graph, or CodeGraph is stale.
3. Changeset rollback to undo one committed logical update while preserving unrelated later writes.
4. Checkpoint restore to return the complete Wiki database to an earlier point.

Do not jump to full restore for a missing generated file or stale graph edge.

Inspect before repair

lwc --scope project lint --limit 100
lwc --scope project work list
lwc --scope project graph status
lwc --scope project graph verify
lwc --scope project cg status
lwc --scope project checkpoint list

Record current revision, operation ID, active Work, graph engine, and the exact inconsistent artifact. A repair without a precondition and acceptance check is not auditable.

Materialize Markdown

Use when .lwc/wiki/, .lwc/raw/, schema.md, purpose.md, index.md, overview.md, or log.md is missing or stale while SQLite reads are correct:

lwc --scope project maintenance materialize
lwc --scope project work watch <work-id>
lwc --scope project lint

Materialization rebuilds the complete owned projection. It replaces or removes only manifest-owned artifacts; user files and raw assets outside LWC ownership are preserved.

Never edit generated files as the repair.

Reindex search

Use only when lint reports missing, duplicate, or orphan FTS rows, or after a documented tokenizer migration:

lwc --scope project maintenance reindex
lwc --scope project work watch <work-id>
lwc --scope project lint
lwc --scope project search "known answer" --limit 5 --explain

Reindex transactionally recreates document FTS and span indexes from immutable Sources and current Pages, then refreshes the Markdown operation log. It does not rewrite Page knowledge or retrieval adjustments.

Compact SQLite

Run during an idle maintenance window:

lwc --scope project maintenance compact
lwc --scope project work watch <work-id>

Compaction optimizes FTS and attempts a WAL TRUNCATE checkpoint. Inspect busy, before_bytes, and after_bytes in the Work result. busy=true means an active reader prevented complete truncation; it is not permission to kill the reader or delete WAL files.

Reproject the document graph

When canonical Wiki and search are healthy but graph verify reports drift, set the intended engine explicitly to queue a full projection:

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph verify

Use surrealdb in all three decisions if that is the selected engine. Do not switch engines merely to repair one; rebuild and verify the intended engine.

Draft graph recovery must keep the same changeset selector. Live and draft Work roots and graph sidecars are intentionally isolated.

Resume Work

lwc --scope project work status <work-id>
lwc --scope project work resume <work-id>
lwc --scope project work watch <work-id>

Resume only after fixing the cause. It is allowed for failed, cancelled, or stale interrupted Work. Succeeded or fresh active Work returns work_not_resumable.

If the parent command returned a canonical partial-success recovery command, follow that command instead of resuming blindly. It may need to reconstruct missing graph documents or finish cleanup before Work can proceed.

Changeset recovery

A failed commit can be in one of two broad states:

• no canonical merge: fix conflict or draft issue, then commit again;
• canonical_committed=true: do not restage writes; repeat the documented idempotent commit recovery and retain the draft until cleanup succeeds.

For an already committed update:

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

Rollback refuses touched entities changed by later writes. There is no force option. If rollback reports canonical partial success, repeat the exact rollback command from details.

Checkpoint recovery

Use checkpoint restore only when the whole database must return to a known boundary:

lwc --scope project checkpoint restore <checkpoint-name>
lwc --scope project work watch <graph-work-id>
lwc --scope project lint
lwc --scope project graph verify

Restore first creates a pre-restore-* safety checkpoint. Keep it until canonical, Markdown, retrieval, and graph acceptance all pass.

A prepared checkpoint that is invalid returns checkpoint_restored=false. If canonical restore succeeds but projection fails, details contain checkpoint_restored=true, safety checkpoint, and exact recovery commands.

CodeGraph recovery

lwc --scope project cg status
lwc --scope project cg sync

Use cg sync for normal project-file changes. If the project index was never initialized, use cg init with explicit consent. LWC reuses the verified global runtime and keeps project index ownership local.

Do not invoke blocked CodeGraph global lifecycle commands through lwc cg, move .codegraph state into the project, or register CodeGraph as a separate MCP server.

Schema migration

Opening an older supported Store may queue or run a migration before the requested operation. Long migrations use shadow-copy Work and preserve a safety checkpoint.

Watch the returned Work and inspect its result. An unknown newer format returns unsupported_store_version; use a compatible LWC version rather than editing PRAGMA user_version.

Recovery acceptance

Every recovery should finish with the checks relevant to the incident:

lwc --scope project lint
lwc --scope project search "expected wording" --limit 5
lwc --scope project search "natural paraphrase" --limit 5
lwc --scope project graph verify
lwc --scope project work list

Also read back the affected Page, Source path head, tag membership, or checkpoint state directly. A command exit status is not enough when the incident involved partial success.

Prohibited shortcuts

• deleting wiki.db-wal or wiki.db-shm;
• editing SQLite, FTS, Work JSON, graph sidecars, or generated Markdown;
• discarding a failed draft before diagnosis;
• using lint override to hide new issues;
• force-copying one draft's runtime into another;
• restoring a checkpoint without preserving and recording the automatic safety checkpoint;
• running repeated full rebuilds without identifying the drift source.

Next: Security and privacy