features saved work

Saved work

Active contributors: Douwe de Vries

Purpose

Saved work has two separate formats with different jobs:

• Pair-order files save reusable setup selections for the currently loaded CSV structure.
• Comparison snapshots save a completed result set and reload it in read-only mode.

This split keeps repeat setup work editable while keeping reopened results consistent with the files, mappings, normalization, rows, and summary that produced them.

See also features index, backend workflow, frontend workflow, and API.

Directory layout

Area	Source paths
Pair-order persistence	/Users/vriesd/projects/csv-align/src/backend/pair_order.rs
Snapshot workflow	/Users/vriesd/projects/csv-align/src/backend/comparison_snapshot.rs
Snapshot persisted model	/Users/vriesd/projects/csv-align/src/backend/persistence/v1/mod.rs
Shared workflow wrappers	/Users/vriesd/projects/csv-align/src/backend/workflow.rs
Frontend save/load actions	/Users/vriesd/projects/csv-align/frontend/src/hooks/useWorkflowPersistenceActions.ts
Frontend read-only state	/Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.reducer.ts, /Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.ts
Desktop dialogs and file I/O	/Users/vriesd/projects/csv-align/src-tauri/src/commands.rs

Key abstractions

• PairOrderSelection contains key_columns_a, key_columns_b, comparison_columns_a, and comparison_columns_b.
• Pair-order files also persist headers_a and headers_b so load can validate the current files.
• SnapshotV1 is the persisted snapshot structure. Its current version constant is 2.
• A comparison snapshot stores file metadata, virtual headers, selected columns, mappings, normalization config, results, and summary.
• snapshotReadOnly in frontend state blocks follow-on editing workflows after a snapshot is loaded.

How it works

Pair-order files

1. The user loads File A and File B, chooses row keys, and chooses comparison columns.
2. Save pair order calls /Users/vriesd/projects/csv-align/src/backend/pair_order.rs.
3. The backend validates that selected columns exist and that File A/File B key and comparison counts match.
4. The saved JSON includes a format version, current physical headers for both files, and the selection.
5. Load pair order requires File A and File B to already be loaded in the session.
6. The backend validates the saved version, compares saved headers to currently loaded headers, and returns the selection.
7. The frontend applies the selection in configure mode and clears existing results and summary.

Pair-order files do not include comparison results, mappings, normalization settings, or source CSV rows.

Comparison snapshots

1. The user runs a comparison.
2. Save comparison snapshot calls /Users/vriesd/projects/csv-align/src/backend/comparison_snapshot.rs.
3. SnapshotV1::from_session reads loaded CSV metadata, the current ComparisonConfig, stored results, and a generated summary.
4. The saved JSON includes file names, headers, virtual headers, columns, row counts, selected columns, mappings, normalization config, results, and summary.
5. Load comparison snapshot validates the version, file metadata, selections, mappings, and summary.
6. The backend writes the snapshot data into the session as stored results and config, but it does not restore csv_a or csv_b row data.
7. The frontend enters the results step with snapshotReadOnly: true.

Read-only reload behavior

Loaded snapshots are read-only because they represent a finished comparison rather than editable CSV inputs. The frontend blocks file loading, compare, auto-pair, pair-order save/load, and step navigation back into editable setup. The user can still inspect, filter, search, and export the loaded results. Reset creates a fresh session and returns to an editable workflow.

The read-only behavior is enforced in /Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.ts through blockSnapshotFollowOnWorkflow and in /Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.reducer.ts through the snapshotLoaded state transition.

Integration points

• Browser and desktop transports expose the same save/load concepts through API.
• /Users/vriesd/projects/csv-align/frontend/src/hooks/useWorkflowPersistenceActions.ts coordinates stale-request guards so older in-flight work cannot overwrite newly loaded pair-order or snapshot state.
• /Users/vriesd/projects/csv-align/src-tauri/src/commands.rs provides desktop file picker and save dialogs for .txt, .json, .csv, and .html outputs.
• Results export can run against a loaded snapshot because the session stores results and comparison config even though raw CSV rows are not restored.
• Snapshot result shapes reuse comparison results.

Entry points for modification

• Change pair-order format or validation in /Users/vriesd/projects/csv-align/src/backend/pair_order.rs.
• Change snapshot persisted fields or validation in /Users/vriesd/projects/csv-align/src/backend/persistence/v1/mod.rs.
• Change save/load workflow wrappers in /Users/vriesd/projects/csv-align/src/backend/workflow.rs.
• Change frontend read-only behavior in /Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.ts and /Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.reducer.ts.
• Change desktop file dialog behavior in /Users/vriesd/projects/csv-align/src-tauri/src/commands.rs.

Key source files

File	Purpose
/Users/vriesd/projects/csv-align/src/backend/pair_order.rs	Saves and loads reusable pair-order selections with current-header validation.
/Users/vriesd/projects/csv-align/src/backend/comparison_snapshot.rs	Version probe plus snapshot save/load workflow entry points.
/Users/vriesd/projects/csv-align/src/backend/persistence/v1/mod.rs	Snapshot schema, conversion, validation, and session rehydration.
/Users/vriesd/projects/csv-align/frontend/src/hooks/useWorkflowPersistenceActions.ts	Frontend actions for CSV export, HTML export, pair order, and snapshots.
/Users/vriesd/projects/csv-align/frontend/src/hooks/useComparisonWorkflow.reducer.ts	State transitions for loaded pair orders and read-only snapshots.
/Users/vriesd/projects/csv-align/src-tauri/src/commands.rs	Desktop file save/load command implementations.