UX-WSF-004 — Define version-comparison semantics
| Field | Value |
|---|---|
| Status | Open; source-verified |
| Severity | Medium |
| Components | sparqd/oqullus, sparqd/workspace-file-management-backend |
| Associated issues | Not opened |
Concrete observed case
File history is returned newest first. For every non-latest row, Oqullus sends the selected history entry as the comparison base and the first history row as the comparison target. View Changes therefore shows a cumulative difference between the selected entry and the newest recorded entry; it does not show the change introduced by the selected revision.
The newest history row is also labelled Current Version, although history contains content changes and metadata events such as rename, move, restore, and delete. Consecutive rows can consequently reference identical content. A simple row-to-row comparison would not by itself define content-revision semantics.
This semantic issue is separate from the missing-version fallback in
REL-WSF-004.
Expected condition
The UI exposes two unambiguous operations:
- View changes in this version compares the nearest preceding distinct content version with the selected content version.
- Compare with current compares the selected content version with the actual current file version, not merely whichever event occupies row zero.
The comparison identifies both sides by timestamp and version and states the direction of additions and removals. Metadata-only events are labelled and do not masquerade as new content revisions.
Why it matters
Users cannot tell whether a displayed difference was introduced by the selected save or accumulated across several later saves. This makes review, incident investigation, and restore decisions error-prone. Empty comparisons for metadata-only rows further suggest that a revision contained no changes without explaining that its content version was unchanged.
Existing controls and workarounds
The current comparison is useful as a restore preview if interpreted as selected-versus-latest. Users must currently infer that meaning from the result; the control and diff dialog do not state it.
Alternatives considered
- Recommended: provide View changes in this version and Compare with current as separate, explicitly labelled operations.
- Keep only the existing comparison and rename it Compare with current—a valid smaller change, but it does not support per-revision investigation.
- Add an arbitrary two-version picker—flexible, but unnecessary until the two common comparisons are reliable.
Component involvement
- Oqullus selects the intended comparison mode, labels both sides, and skips metadata-only duplicates when choosing the preceding content revision.
- The workspace file backend resolves an explicit current version and immutable history versions, validates both inputs, and returns their identities with the diff result.
Reproduction and verification
Follow WSF-S005 with at least three distinct notebook saves and one rename or move between saves. For each row, record the two content-version identities and verify that the displayed labels and diff direction match the selected operation.
Resolution conditions
Close when UI and integration tests prove adjacent-distinct and current comparison modes independently, metadata-only events are handled explicitly, both sides are labelled, and missing versions fail closed.
Validation and blockers
Newest-first ordering and selected-versus-first-row behavior are
source-confirmed. Accurate deployed content comparison is blocked by the
missing-version condition recorded in REL-WSF-001 and REL-WSF-004.