jjcat: Safety UX for Mutable Version-Control History
Why a Jujutsu desktop client should bind intent to exact repository state before making history mutation convenient.
CENTRAL QUESTION
What should confirmation mean when the target history is mutable, the working copy is a commit, and the safest recovery path is often another operation?
WORKING THESIS
Safety in a version-control client comes from making target state, expected effect, and recovery concrete—not from placing the same confirmation dialog in front of every command.
PUBLICATION BOUNDARY
What this piece can honestly claim.
GROUNDED IN
The public jjcat product architecture, local and SSH repository drivers, preview-token design, operation queue, bounded projections, and current implementation stage.
DOES NOT CLAIM
jjcat is not presented as a mature replacement for established clients, and designs that remain roadmap work will be labeled rather than described as shipped behavior.
DRAFT ARCHITECTURE
The argument, section by section.
- 01
Show where Git-client metaphors stop helping
A mutable operation graph and working-copy commit change what users need to see before acting.
EVIDENCECompare familiar labels and flows with their Jujutsu state transitions.
- 02
Make preview a state-bound contract
A preview is useful only if execution can prove that repository identity, current operation, target, and intended effect are still the same.
EVIDENCEFollow an opaque preview token through stale and duplicate rejection.
- 03
Serialize mutation and verify postconditions
Command success does not prove that the repository now projects the state the user approved.
EVIDENCEShow the repository queue, fresh operation identity, re-query, and expected projection.
- 04
Match friction to reversibility
Undoable local shaping, destructive workspace removal, and remote publication deserve different interaction costs.
EVIDENCEBuild a friction matrix and apply it to representative operations.
- 05
Keep local and SSH behavior coherent
The conceptual workflow should remain stable while credentials, latency, caching, and failure reporting stay transport-specific.
EVIDENCECompare typed driver contracts and identify where parity must intentionally stop.
- 06
Label roadmap as roadmap
A case study earns trust by distinguishing implemented behavior from design intent and by naming the next falsifiable milestone.
EVIDENCEClose with a shipped/planned table and the test that would promote each claim.
EDITORIAL GATE
Evidence required before publication.
State model
A comparison of Git-client assumptions with Jujutsu working-copy commits, operations, bookmarks, and workspaces.
Mutation trace
Preview, state binding, stale rejection, serialized execution, fresh projection, and recovery for one change.
Friction matrix
Confirmation strength derived from reversibility, remote effect, data loss, and target ambiguity.
Implementation status
A visible split between shipped read paths, implemented safety primitives, and unimplemented mutation workflows.