Migration and Compatibility

Migration and Compatibility

Language: English · 简体中文

LWC upgrades preserve canonical knowledge first, rebuild derived state when necessary, and migrate only integration fragments it can prove it owns. Compatibility does not mean that an older binary may safely write a newer Store.

Compatibility layers

Layer	Compatibility rule
CLI JSON	Existing codes and fields remain machine-readable; additive fields are allowed
SQLite Store	Supported older schemas migrate transactionally to the current format
Config	Older supported files are read and upgraded on a later write
Markdown, FTS, spans, graph	Derived state may be rebuilt from canonical SQLite
Changesets and checkpoints	Integrity metadata and inverse payloads remain verifiable across supported versions
Agent integration	Owned legacy fragments migrate; foreign content is preserved or reported as a conflict
CodeGraph	Pinned runtime upgrades are separate from project index compatibility

The running binary and current source tree are authoritative. Internal version numbers are implementation details; do not write automation that assumes them.

Before upgrading

Use the same project and user account that own the Wiki:

lwc --version
lwc --scope project lint
lwc --scope project work list
lwc --scope project graph verify
lwc --scope project checkpoint create pre-upgrade

Wait for active mutations before changing binaries. A checkpoint protects canonical SQLite, not external Sources or user-owned Agent configuration; back those up through their native systems when needed.

Upgrade the binary

Use the same distribution channel that installed LWC. Afterward:

lwc --version
lwc --scope project context --limit 1
lwc agent refresh --target auto --location global
lwc agent status --target all --location global

The first command that encounters a supported legacy Store coordinates one transactional writable migration before continuing. Read commands keep current Stores read-only; only the old format boundary opens the dedicated migration path.

Do not copy wiki.db between machines while WAL state or a write is active. Do not run two LWC versions against the same Store during migration.

Store migration guarantees

A successful migration must:

• validate the source schema before transforming it;
• commit all schema and metadata changes atomically;
• preserve immutable Source content and current Page knowledge;
• rebuild or invalidate derived indexes instead of treating them as canonical;
• record the current format only after every step succeeds;
• remain safe when two processes discover the same legacy Store.

If the Store is newer than the binary, LWC returns unsupported_store_version. Upgrade the binary; never force the older executable to write.

Source-path history

Older Stores may contain Sources without trustworthy tracked-path revision history. Migration deliberately keeps them untracked rather than guessing a filesystem origin. Add a current file as a new Source if future path status and diff behavior are required.

This can produce two immutable Source snapshots with related content. Preserve both IDs when they support different historical claims; do not rewrite old evidence to make the lineage look cleaner.

Config migration

Supported older config formats are parsed into the current layered model. A later config set or config unset writes the current format atomically.

lwc --scope global config show
lwc --scope project config show

Verify effective values and origin after migration. An inherited value and an explicit disabled value have different semantics.

Derived graph migration

Document-graph sidecars are rebuildable. A Store migration may remove obsolete inline graph tables or require a full projection. After any graph-affecting upgrade:

lwc --scope project graph status
lwc --scope project graph verify

If verification fails while canonical lint is clean, queue a full projection for the already selected engine and wait for its Work. Do not switch engines merely to make a check pass.

CodeGraph reports an obsolete project-local runtime but does not silently delete it. cg init installs or reuses the pinned user runtime and builds the current project index. Remove legacy files only after the new status and queries pass.

Agent integration migration

agent refresh recognizes prior LWC and standalone CodeGraph fragments only when they match known owned shapes. It consolidates CodeGraph MCP access behind the lwc server, updates marker-bounded Instructions and canonical Skills, and records a new receipt.

If a user or another tool has replaced the same entry, LWC reports a conflict instead of claiming ownership. Review with --print-config; do not delete the host's entire configuration file.

Changeset and checkpoint compatibility

Sparse inverse payloads use checksums. New optional fields remain absent when empty so older payload bytes continue to verify. A committed changeset retry can rebuild graph projection documents when an older operation record lacks the newer derived-work detail.

Keep failed drafts and pre-commit checkpoints until the upgraded binary completes the documented retry. Never edit their SQLite or JSON sidecars to make an integrity check pass.

Downgrade policy

LWC does not promise backward writes from an older binary into a newer Store. To return to an older release:

1. stop all LWC processes;
2. restore a checkpoint created by that compatible release, or restore a complete external backup;
3. restore matching Agent integration and optional index state when required;
4. verify with the older binary before resuming writes.

Installing an old executable over a new one is not a database downgrade.

Post-upgrade acceptance

lwc --scope project lint
lwc --scope project search "known project fact" --limit 5 --explain
lwc --scope project graph verify
lwc --scope project cg status
lwc agent status --target all --location global

Require canonical reads, one fixed retrieval, enabled graph verification, project CodeGraph status, and the intended Agent surfaces to pass independently. For the release pipeline itself, see Testing and release process.