Work System

Work System

Language: English · 简体中文

LWC runs long or recoverable state changes as durable Work. The initiating command returns quickly with a Work ID; a detached worker records progress, result, and errors for later inspection.

Work is an execution receipt, not proof of completion. When a command returns graph.work, work, or graph_work, follow that Work to a terminal state before accepting the operation.

What uses Work

Current Work kinds include:

• document-graph projection;
• schema migration;
• maintenance reindex;
• Markdown materialization;
• SQLite compaction.

Ordinary searches and canonical Page or Source reads do not become Work. They remain available while an unrelated background operation runs.

Lifecycle

queued -> running -> succeeded
                  -> failed -----> resume -> queued
                  -> cancelled --> resume -> queued
stale interrupted -------------> resume -> queued

succeeded, failed, and cancelled are terminal states. A successful state contains the operation result. Failure and cancellation states contain a typed error.

A Work record also exposes its phase, completed and total counts when known, percentage, throughput, estimated time remaining, update sequence, timestamps, process ID while running, and cancellation flag. Treat these fields as progress telemetry; the terminal state and result are authoritative.

Inspect a Work

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

list returns recent Work for the selected Wiki, newest update first. status reads one current snapshot. watch polls until the Work becomes terminal and then returns that final record.

The Work ID is a 64-character hexadecimal identifier. It is scoped to the selected Wiki and, for draft operations, to the selected changeset runtime.

Acceptance rule

Do not stop at queued or running:

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

For graph projection, require both:

1. Work state succeeded;
2. graph verify reports ok=true.

The first proves the worker completed. The second proves the derived graph matches canonical Wiki state.

For maintenance Work, inspect the terminal result and then run the acceptance check for the repaired subsystem, such as lint, retrieval, materialized Markdown, or graph verification.

Cooperative cancellation

lwc --scope project work cancel <work-id>
lwc --scope project work watch <work-id>

Cancellation is cooperative. cancel records a request; the worker observes it at a safe progress boundary and finishes as cancelled with error code work_cancelled. If the Work already reached a terminal state, cancel returns that state without rewriting the outcome.

Do not assume the first cancel response is already cancelled. Watch it to the terminal state.

Resume

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

Resume is allowed for failed, cancelled, or stale interrupted Work. It clears the cancellation request, queues the same durable request, and preserves the Work ID. A recently queued or running Work and a succeeded Work return work_not_resumable.

Resume is safe only after correcting the failure's cause. For example, restore filesystem access or repair configuration before resuming a failed maintenance operation.

Concurrency and coalescing

Each Wiki runtime permits one active state-changing Work. Starting a different kind while one is active returns work_busy.

Document-graph projection is coalesced. New dirty document keys join a durable pending set; an active graph-project Work drains additional batches before it finishes. Callers can therefore receive the same active Work instead of creating one worker per Page mutation.

If more graph documents arrive at the completion boundary, LWC starts the next projection Work. Always verify the graph after the last relevant Work completes.

Draft isolation

Use the same changeset selector that produced the Work:

lwc --scope project --changeset architecture-refresh work list
lwc --scope project --changeset architecture-refresh work watch <work-id>
lwc --scope project --changeset architecture-refresh graph verify

Each draft owns a separate Work root and graph sidecar. A Work ID from draft A is work_not_found under draft B. Live Work is likewise separate from draft Work.

Commit, rollback, and discard clean draft runtime state only after their canonical recovery contract permits cleanup. Do not manually move Work files or graph sidecars between stores.

Durable state and interrupted processes

Work requests and state snapshots are stored below the selected Wiki runtime. Writes use replace-on-write state files, restricted directory permissions where supported, and path checks that reject symlinks or mismatched database scopes.

The worker runs independently of the initiating terminal. If a process disappears without writing a terminal state, the heartbeat eventually becomes stale and resume can restart it after 30 seconds.

Do not edit Work JSON, delete the active marker, or launch the hidden worker command yourself. Use status, cancel, and resume so LWC can preserve ownership and recovery guarantees.

Failure handling

Use the typed error and the current Work state:

• work_not_found: the ID does not belong to the selected live or draft Wiki;
• work_busy: another state-changing Work owns the runtime;
• work_not_resumable: the Work is succeeded or still active and fresh;
• work_cancelled: cancellation reached a safe boundary;
• work_invalid: persisted state, path ownership, or Work kind is invalid.

If the command that created Work also reports canonical partial success, follow its exact recovery_command. Do not invent a replacement from the Work error alone.

Completion evidence

A Work-backed operation is complete when:

• the Work ID was recorded with the initiating operation;
• watch returned a terminal state;
• the terminal state is succeeded and its result was inspected;
• the subsystem-specific validation passed;
• any failed or cancelled attempt was resumed only after its cause was addressed;
• draft Work was queried under the correct changeset selector.

Next: Checkpoints and rollback