Changesets

Changesets

Language: English · 简体中文

A changeset stages several related Wiki mutations in an isolated sparse draft, validates them against the live Wiki, and publishes them atomically. Use it when one logical update must not expose partial knowledge.

Single source, page, or tag commands are already transactional. A changeset is useful only when several commands must succeed together.

Good use cases

• add several Sources and integrate them into shared Pages;
• revise a Page and its strong-tag policy together;
• update Purpose, Schema, and dependent Pages as one contract change;
• publish several linked Pages without temporary broken links;
• prepare a broad replacement with one exact rollback boundary.

Do not create a changeset for a one-command write. The draft lifecycle would add review overhead without improving atomicity.

Sparse overlay model

live Wiki remains readable and unchanged
          +
small draft with touched entities and base fingerprints
          =
overlay reads used for draft validation

changeset begin does not copy or checkpoint the full live Wiki. It creates a small sparse database bound to the live store identity and base revision. Draft reads see staged changes over the live baseline, while live SQLite and Markdown stay unchanged.

Each draft has its own database, Work directory, and graph sidecar. Work IDs and graph nodes cannot leak between drafts.

Begin and stage

lwc --scope project changeset begin architecture-refresh
lwc --scope project --changeset architecture-refresh source add-manifest sources.json
lwc --scope project --changeset architecture-refresh ingest claim <source-id>

Keep every dependent read and write under the same --changeset selector. Do not interleave direct live writes to entities the draft will touch.

Project and global changesets are separate. --scope all is invalid for mutation.

Supported sparse mutations

The current exact patch set supports:

• Source add;
• ingest claim, analyze, complete, fail, and retry;
• Page put and remove;
• Purpose and Schema replacement;
• tag set, remove, delete, and autoload policy;
• recorded search operations.

Other canonical mutations require an exact inverse and merge rule before they can be published safely. Unsupported actions return changeset_sparse_unsupported or a command-specific changeset_command_not_supported instead of producing a partial commit.

Deployment-local configuration, init, maintenance, checkpoints, and nested changeset commands cannot run inside a draft. Apply independently transactional unsupported mutations outside the changeset only when that separation matches the intended atomic boundary.

Validate the draft

lwc --scope project --changeset architecture-refresh lint
lwc --scope project --changeset architecture-refresh search "expected answer" --limit 5
lwc --scope project --changeset architecture-refresh search "natural paraphrase" --limit 5
lwc --scope project changeset show architecture-refresh

show reports base and draft revisions, staged operation counts, action counts, status, and conflict metadata. It does not run lint.

Sparse lint evaluates live baseline + draft delta. A draft Page can keep a valid link to an unchanged live Page, and a tag-only draft does not need to copy the Page body, dependencies, or search index.

Validation should include:

• zero issues introduced by the draft;
• original and paraphrased retrieval returning the expected Page in the top five;
• complete citations and provenance;
• draft graph Work at succeeded and graph verify ok=true when graph state is relevant.

Publish atomically

lwc --scope project changeset commit architecture-refresh

Commit:

1. rejects an empty draft;
2. verifies the draft's binding and integrity;
3. checks fingerprints for every touched Page, meta record, tag, and Source path;
4. lints the overlay;
5. freezes the reviewed draft;
6. creates a checksummed inverse patch for touched entities;
7. applies the merge under the live write lock;
8. queues live graph projection when enabled;
9. removes draft state and refreshes generated Markdown.

Unrelated live writes survive. If a touched entity changed after the draft first observed it, commit returns changeset_conflict and overwrites neither side. There is no force merge.

Source identifiers allocated independently by draft and live writes are remapped during commit when paths are unrelated. Page citations, ingest state, path heads, graph documents, fingerprints, and rollback data follow that remap.

Lint override

Do not use --allow-lint-issues to hide draft mistakes. It exists only for audited, pre-existing live debt that the changeset did not introduce, and it requires a reason:

lwc --scope project changeset commit architecture-refresh \
  --allow-lint-issues \
  --reason "Reviewed pre-existing debt; this draft introduces no new issue"

Prefer repairing the issue. A reason records the exception; it does not make broken knowledge valid.

Frozen drafts and retry

Commit freezes the reviewed draft before live publication. Later staged writes return changeset_frozen.

If a structured error says canonical commit succeeded but graph queueing, cleanup, or materialization failed, do not repeat the knowledge mutations. Run the exact recovery_command in error details. Repeating the same changeset commit <name> is idempotent and can requeue graph projection before cleanup, including recovery from older commit metadata.

Discard

lwc --scope project changeset discard architecture-refresh

Discard deletes one uncommitted draft and its isolated Work/graph runtime. It never touches live knowledge. Do not discard a failed draft until its content is no longer needed for diagnosis or recovery.

Roll back a committed changeset

Commit returns a stable changeset_id and pre-commit checkpoint name:

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

Rollback restores only the inverse patch's touched entities. It refuses when a later live write changed one of them, preserving that newer work. Source path heads, remapped IDs, Page citations, tags, and document-graph projection are restored consistently.

Rollback is idempotent. If canonical rollback succeeded but later materialization or graph queueing failed, repeat the same rollback command from the structured recovery details.

After publication

Repeat the same acceptance against live state:

lwc --scope project lint
lwc --scope project search "expected answer" --limit 5
lwc --scope project search "natural paraphrase" --limit 5
lwc --scope project graph verify

A clean draft is not proof that live materialization and graph projection completed.

Completion evidence

A changeset lifecycle is complete when:

• all dependent operations used one draft selector;
• overlay lint and predeclared retrieval checks passed;
• commit returned one stable changeset ID and inverse checkpoint;
• any graph Work reached succeeded and live graph verification passed;
• live retrieval repeated the draft acceptance;
• conflict or partial-success errors were handled through their typed recovery contract;
• the draft runtime was cleaned only after canonical publication or explicit discard.

Next: Work system