0.9.8: session attribution, guide screenshots, source list tooling #117

Merged
ethan-hann merged 37 commits from integration-102 into main 2026-10-25 03:15:47 -05:00
Owner

Version 0.9.8.

  • After a switch, the after-play dialog and the save list name the profile the session really started from, and Replace after a normal session follows the D14 rule (join, amend only the profile's own unreached tip, otherwise keep as new). Closes #105.
  • The user guide shows the app with 10 real screenshots, and the wiki sync rewrites relative image links to raw URLs on main. Closes #80.
  • The package scripts read build/msys2-sources.json and build/git-manifest.json through tools/PackageSources, so a reformatted list reads the same, and package sources the pin list no longer names are removed before download. Closes #60. Closes #61.
  • build/fetch-git.sh reads the manifest through tools/PackageSources (new bundle command) instead of awk. Closes #113.
  • build/msys2-sources.ps1 regenerates msys2-sources.json from a MinGit bundle and checks every archive's signature with gpg against a pinned key (MSYS2 development key 5F944B027F7FE2091985AA2EFA11531AA0AA7F57 and Git for Windows release key E8325679DFFF09668AD8D7B67115A57376871B1C, both cross-checked against the projects' published keyring lists). A real run reproduces the checked-in list byte for byte. Closes #53. Closes #52.
  • One test drives every job kind against the real backend and fails if a job line shows a git folder. Closes #55.
  • Bring back of a snapshot recorded in one folder only, whose other folder's commit with the same id a live profile still holds, copies the recorded commit under a new snapshot id and moves its Recently removed record onto the copy in the same git step that creates the branch, so History shows the new profile's point on its own and the snapshot is never lost. Closes #111.
  • The Replace tests state the current D14 rule (a folder without a commit of the snapshot joins it), with a new test for a replacement kept as new.

The build with warnings as errors and the format check pass locally.

Version 0.9.8. - After a switch, the after-play dialog and the save list name the profile the session really started from, and Replace after a normal session follows the D14 rule (join, amend only the profile's own unreached tip, otherwise keep as new). Closes #105. - The user guide shows the app with 10 real screenshots, and the wiki sync rewrites relative image links to raw URLs on main. Closes #80. - The package scripts read build/msys2-sources.json and build/git-manifest.json through tools/PackageSources, so a reformatted list reads the same, and package sources the pin list no longer names are removed before download. Closes #60. Closes #61. - build/fetch-git.sh reads the manifest through tools/PackageSources (new bundle command) instead of awk. Closes #113. - build/msys2-sources.ps1 regenerates msys2-sources.json from a MinGit bundle and checks every archive's signature with gpg against a pinned key (MSYS2 development key 5F944B027F7FE2091985AA2EFA11531AA0AA7F57 and Git for Windows release key E8325679DFFF09668AD8D7B67115A57376871B1C, both cross-checked against the projects' published keyring lists). A real run reproduces the checked-in list byte for byte. Closes #53. Closes #52. - One test drives every job kind against the real backend and fails if a job line shows a git folder. Closes #55. - Bring back of a snapshot recorded in one folder only, whose other folder's commit with the same id a live profile still holds, copies the recorded commit under a new snapshot id and moves its Recently removed record onto the copy in the same git step that creates the branch, so History shows the new profile's point on its own and the snapshot is never lost. Closes #111. - The Replace tests state the current D14 rule (a folder without a commit of the snapshot joins it), with a new test for a replacement kept as new. The build with warnings as errors and the format check pass locally.
Ten screens taken on the Ubuntu test VM from a clean SavePoint with a
real game (Grounded): first run, adding a game, the first snapshot,
the profile list, the check before playing, the after-play choices,
History with Recently removed, Activity, and Settings. Each image has
alt text describing what it shows.
The after-play "Replace ... with this session" choice named the newest point on
the played profile's saves branch. A profile made with New profile while another
was loaded starts its saves branch on that profile's tip, so the dialog offered
to replace the other profile's snapshot (and the rewritten point took its name).
The target is now the newest point the played profile owns in the saves folder,
else in the install folder, with ownership decided as History decides it (the
first profile in catalog order whose history holds the point). A profile that
owns no point, such as a fresh duplicate, is no longer offered Replace.

Tests added for the other reported symptoms, which pass without a code change:
files rewritten with the same bytes are not changes in status, in a save's file
count, or in the after-play count; a profile made from another offers the saves
it started with; a kept session updates the profile's snapshot count.

Observed red (before the fix):
LaunchUpdateExistingTests.The_replace_choice_names_a_point_of_the_played_profile_not_the_one_whose_saves_it_started_with
  Assert.NotEqual() Failure: Strings are equal (the target was the other
  profile's save point id).
Mutation checks (each failed for the expected reason, then restored):
- ownership as "exclusive to this profile" fails The_profile_another_was_made_from_still_replaces_its_own_point
- no ownership filter fails the duplicate, the replace-result and the App
  journey tests
- diff-index (stat only) in the status listing fails the status test and the
  session count test (expected 0, actual 2)
- a staging listing that includes unchanged tracked files fails the capture
  count test
Replace after play is now offered for the newest point History lists under the
played profile (same grouping and ownership as History, reused from
HistoryReader), and only when, in every folder the save will write (a folder
with something unsaved), that point's commit is the profile's tip there and no
other profile's branch reaches it. Otherwise the dialog offers Keep as a new
snapshot and Not now. This removes the cases where an amend split one capture id
across two commits (a duplicate or a profile made from another continuing from
the rewritten commit), where the offered point was another profile's, and where
a folder was written without the point's commit being its tip (which produced
the "didn't end with the snapshot you chose" card). The target is the newest by
date across both folders rather than the saves folder first.

ListCommitsOnlyOnAsync takes an optional max count; the check reads one commit.

Observed reds (before the change, assertion failures):
- A_replace_is_not_offered_after_a_duplicate_holds_the_snapshot...: Assert.DoesNotContain() Failure: Item found in collection
- In_a_chain_of_profiles_made_from_one_another...: Assert.DoesNotContain() Failure: Item found in collection
- The_profile_another_was_made_from_is_not_offered_a_replace...: Assert.Null() Failure (target Vanilla)
- A_profile_whose_saves_are_another_profile_s_is_not_offered...: Assert.Null() Failure (target Heavy mods)
- The_snapshot_offered_is_the_newest_the_profile_owns_in_either_folder...: Assert.Null() Failure (target Second save)
The D31 test that replaced a saves point while the install changed now asserts
the choice is not offered and is refused.

Mutation checks (each failed the named tests, then restored): other branches
empty fails the duplicate, chain and base-profile tests; oldest instead of
newest fails the "newest" and result tests; skipping a folder without the
point's commit fails the chain, install-only and Heavy tests; reporting kept-as-new
for every amend fails the result-card test; dropping the started-with saves from
the target list fails A_profile_made_from_another_offers_the_saves_it_started_with.
The three "rewritten with the same bytes" tests were mutation-checked earlier:
diff-index in the status listing fails the status and launch tests (expected 0,
actual 2); a staging listing of every tracked file fails the capture count test.
The wiki has no docs/images, so a guide's relative image or link
(images/x.png, ./images/x.png) would not render there. The page transform
now rewrites such targets to <server>/<owner>/<repo>/raw/branch/main/docs/images/x.png,
taking server and repository from the same variables as the source note
(with the same defaults). Alt text and titles are kept; absolute URLs,
anchors, code spans and fenced code are left alone.

Also asserts every relative image a guide shows exists under docs/, and
lists the new pwsh-based tests as may-skip where pwsh is missing.

Observed reds before the change:
- A_relative_image_or_link_into_docs_becomes_a_raw_address_on_main_and_keeps_its_alt_text:
  Assert.Contains() Failure: Sub-string not found (Not found: "![First run screen](https://git.tortal.tech/ethan-...")
- The_raw_address_follows_the_server_and_repository_the_job_sets:
  Assert.EndsWith() Failure (page ended with "![a](images/x.png)")
Mutation checks (first-run passes): dropping the code-span exclusion failed
Code_blocks_code_spans_and_absolute_addresses_keep_their_image_text; a guide
linking images/missing-shot.png failed Every_relative_image_a_guide_shows_exists_under_docs.
Replace after play is judged by one rule (ReplaceRule), at the end of the
session and again inside the capture job under the game's lock. For each folder
with something unsaved: if the snapshot has no commit there, the files join it
as a new commit and nothing is rewritten; if it has one, that commit must be the
profile's newest there and no other profile may reach it, and then it is
rewritten; otherwise it is refused. Replace is offered, and carried out, only
when no folder refuses and at least one is rewritten; with nothing unsaved it is
not offered. If the rule fails when the save runs, every folder is saved as a new
snapshot and reported as kept as new (only then). This restores replacing a
saves-only snapshot in a session that also wrote the install.

The lineage reads behind the newest-owned lookup are throttled to the existing
parallelism limit, and nothing is grouped when nothing is unsaved.
ListCommitsOnlyOnAsync takes maxCount before the cancellation token.

Observed reds (before the change, assertion failures):
- Nothing_unsaved_at_exit_offers_no_replace: Assert.DoesNotContain() Failure: Item found in collection
- A_change_only_to_files_the_game_ignores_offers_no_replace: same
- A_folder_that_changes_after_exit_and_whose_snapshot_another_profile_holds_is_saved_as_a_new_snapshot_and_says_so: Assert.All() Failure (folders not kept as new)
- An_update_leaves_an_install_only_point_alone_when_the_install_changed_during_play (restored original flow): Assert.Contains() Failure: Item not found in collection
- A_single_profile_can_replace_a_saves_only_snapshot_and_then_one_that_also_wrote_the_install: Assert.Contains() Failure: Item not found in collection
Guards that passed without the change: saves folder gone at exit, replace after a
duplicate once the original has its own snapshot.

Mutation checks (failed for the expected reason, then restored): skipping the
save-time check fails the changes-after-exit test; treating a missing commit as
refuse fails the restored D31 flow and the single-profile test; the empty-written
early return is only a shortcut (the at-least-one-rewrite requirement already
refuses), so its tests are guards.

Existing tests updated deliberately: the LaunchLeftFolder update case (nothing
unsaved at exit, so Replace is refused), the held-file update case (the file is
held when the game closes), the start test (Vanilla's saves are Modded's, so no
Replace), the contract story (both backends offer no replace after a play with
nothing unsaved).
The release source step reused archives already in source/packages when they
matched their pin but never removed ones an older pin list named, so after a
MinGit update stale sources could be published. Both package scripts now delete
the regular files directly inside that folder that build/msys2-sources.json
does not list (links, folders and their contents stay), say which, and refuse an
empty list. The cleanup runs before any download.

package.sh read the list with awk, which depended on the JSON's exact line
layout. It now reads it through the new tools/PackageSources tool (run with the
SDK the script already needs), so reformatting the JSON cannot change what is
read. The helpers moved to build/package-sources.sh and build/package-sources.ps1
so the tests can run them without downloading anything.

Observed reds (PackageSourceScriptTests, run before the implementation):
- Remove-StalePackageSources removes ...: "an archive an older list named goes"
  (assertion failure, file still there)
- The_powershell_script_given_an_empty_list_removes_nothing: "Assert.ThrowsAny()
  Failure: No exception was thrown"
- Each_package_script_cleans_the_folder_before_it_downloads_anything_into_it:
  "package.sh has to clean the packages folder before its first download."
- The_bash_script_no_longer_reads_the_package_list_with_awk: awk found in the script
- Bash reader on a minified list (run by hand in Git Bash, bash tests skip on
  Windows): the old awk read 0 archives, the new reader 50.
The pwsh reader tests passed on first run (existing behavior moved); mutation
check: returning the file name as the url and not lowercasing the hash failed
all four layout cases and the real-list test.
The save-time check judged a replacement folder by folder but did not keep the
result: a retry of a save that half worked started from the original plans and
judged only the folders left, so a first try saved as new could be followed by a
retry that rewrote, and a folder that only joins could be reported as kept as
new. The judgment is now kept by capture id until the save fully works, and a
retry uses it. Each folder's verdict is written into its plan: only a folder
judged to be rewritten keeps its replacement; a folder that only joins, or that
the check skipped as clean and that is written before it is saved, is saved as a
plain commit and never rewrites anything.

Observed reds (before the change, assertion failures):
- A_retry_of_a_replacement_that_was_saved_as_new_stays_new_and_does_not_rewrite_the_folder_that_failed: Assert.All() Failure, the retried folder was not kept as new
- A_retry_of_the_folder_that_only_joins_a_replacement_is_not_reported_as_kept_as_new: Assert.All() Failure, Assert.False() Failure, expected False, actual True
- A_folder_the_check_skipped_as_clean_is_not_rewritten_if_it_is_written_before_it_is_saved: Assert.Equal() Failure, the shared install commit had been rewritten
package.sh still read the "sources" of build/git-manifest.json with awk, which
only worked for one exact line layout. tools/PackageSources now has two
subcommands (archives, tags) and package.sh reads both files through it, so no
awk reads JSON in the packaging scripts. package.ps1 reads the tags through a
new Get-TagSourcePins in build/package-sources.ps1; both readers sort by key and
lowercase the hash, and the notices check stays in package.ps1.

Observed reds, run on the Linux test VM before the change (bash helper still
awk): The_bash_script_reads_the_same_tag_sources_whatever_the_layout_of_the_manifest
failed for Minified, FourSpaces, Tabs and ReorderedWithExtras, and
The_bash_script_no_longer_reads_the_package_list_with_awk failed because awk was
still in the script. The pwsh tag tests passed on first run (existing reader
moved); mutation check: not lowercasing the hash failed all four layout cases.

Linux results after the change, run one class at a time: PackageSourceScriptTests
25 total, 12 passed, 13 skipped (pwsh is not installed there; every bash test
ran, including the symlink case), PackageSourcesTests 7 total, 6 passed,
1 skipped (the Windows-bundle list check).
The fetch step on Linux and macOS matched the manifest line by line with awk, so
minified, tab-indented or reordered JSON made it find nothing. It now asks
tools/PackageSources (new "bundle" command) for the runtime id's url, version,
sha256, archive, layout, entry and its layout's prune patterns, the way
package.sh already reads its lists. The build has the .NET SDK by definition;
python3 and jq are not in the documented prerequisites (bash, tar, curl or wget).

Several projects can reach the fetch at once and each would build the tool, so the
read takes a short lock of its own in .tools/downloads. DOTNET_HOST_PATH (set by
MSBuild) is preferred over dotnet on the path. The read only runs when the stamp
is stale, since MSBuild skips the script otherwise.

Observed reds (Linux VM, FetchGitManifestLayoutTests, before the change):
- The_bash_script_prunes_with_the_list_of_the_runtimes_layout_whatever_the_layout_of_the_manifest
  (Minified, FourSpaces, Tabs, ReorderedWithExtras): Assert.True failed with
  "fetch-git: no bundled git for runtime id 'win-x64'"
- The_bash_script_no_longer_reads_the_manifest_with_awk (Windows and VM):
  Assert.DoesNotContain() Failure: Sub-string found "awk"
Passed on first run, so mutation-checked: refuses_a_manifest_that_is_not_json
(tool made tolerant: NotEqual(0) failed with 0) and names_a_runtime_id (id dropped
from both messages: "linux-riscv" not found).
build/msys2-sources.ps1 reads etc/package-versions.txt from the extracted
bundle, finds each package's source archive the way build-extra/get-sources.sh
does (Git for Windows pacman-repo release for the exact version first, then
repo.msys2.org as .src.tar.zst then .src.tar.gz), downloads it to a cache
folder, hashes it and writes the list in the existing format. Packages built
from another package's source (libatomic from gcc, curl-winssl from curl) are
looked up under that source. Packages without an archive are reported with the
addresses tried and nothing is written. The network is two injectable
scriptblocks, so the tests never touch it.

Each archive's .sig is verified with gpg in a private home holding only the
keys pinned in build/keys (MSYS2 development key for repo.msys2.org, Git for
Windows release key for the pacman-repo releases). A bad, missing or foreign
signature stops the run and removes what the run downloaded.

Observed reds (Msys2SourcesScriptTests): all 29 first tests failed with
"build/msys2-sources.ps1 does not exist."; the 13 signature tests failed on
the pwsh exit-code assertion ("term not recognized") and on Assert.Contains
"Sub-string not found" for the Find-PackageSources cases; the gitk case
failed on Assert.StartsWith (it was looked up as mingw-w64-gitk, not
mingw-w64-git). Mutation checks: deliberate breakages of the script (dedupe,
alias table, extension order, tag/version match, text cache, failed-url set,
cache reuse, sort orders, missing report, BOM, bundle check, shorter-name
fallback, malformed line, BADSIG, primary fingerprint, signature check,
pinned host, missing signature) each failed at least one test; all restored.
The catalog lint cannot see message arguments, so a job line passing a git
folder path as an argument went unchecked for capture, optimize and launch
lines. One test now drives every JobKind against the real backend with real
git (capture, compact for one and all games, switch, launch, storage move,
clear) and fails on any file path or text argument that has a .git segment
or, in a step argument, an engine folder name (objects, refs, pack, info,
logs, index, HEAD, hooks, packed-refs). Kinds come from the enum, so a new
kind without coverage fails. The checker moved out of the move/clear tests
into a shared helper both use.

The test passed on its first run: no real leaks were found. Mutation checks,
each failing with the expected assertion and then restored:
- compact step game arg set to Play\install.git\objects\pack: "a Compact job
  shows the engine's folders"
- capture step path arg set to "pack": "a Capture job shows the engine's folders"
- launch step game arg set to x/install.git/refs: "a Launch job shows the engine's folders"
# Conflicts:
#	docs/developer-guide.md
Version 0.9.8
Some checks failed
Gate / linux (pull_request) Failing after 11m14s
Gate / windows (pull_request) Has been cancelled
8dc5a95465
A Replace that changed only the saves leaves the snapshot's install commit on the
profile under capture id X and records the old saves commit, also X, as removed.
Bringing that back gave the new profile a saves commit carrying X, which History
folded into the original profile's point X (first profile in catalog order owns it),
so the new profile showed no point for it.

Bring back now copies the recorded commit onto the new profile under a fresh
capture id (same files, parents, name, capture time) when the other folder only
reaches the snapshot through the profile it left and carries the same id, and
drops the superseded record so the snapshot leaves Recently removed. Recently
removed itself is unchanged: such a snapshot is listed as a saves-only snapshot
under its own name.

Observed red: BringBackTests.A_partly_replaced_snapshot_brought_back_is_its_own_point_...
failed with "Assert.Single() Failure: The collection was empty" (the new profile's
History had no point). The listing test passed on its first run; mutation check:
making the saves-only kind VersionAndMods failed it (Expected SaveOnly, Actual
VersionAndMods), and skipping the record drop failed the round trip test
(Assert.Empty: Collection was not empty).

The existing delete-preview test for a snapshot recorded in one folder now expects
the split point counts (4 only here, 2 saves points).
Bring back copied the recorded commit under a new capture id and then cleared
the old record, so nothing named the brought-back saves once the new profile was
deleted, and a failed clear could leave a profile row with no branches.

The copy's branch and the record's move (create the copy's record, delete the
old one) are now one ref transaction, so branch creation is the commit point and
the copy is listed in Recently removed again if its profile is deleted. The copy
keeps the original's author and committer dates. The branch-exists check comes
before the commit object is written. The split fires for either folder and for a
saves-only continue as well as a replace, and only when a live profile's branch
(not a branch whose profile row is gone) holds the other folder's commit of the
same id.

Observed reds before the change: the delete-preview test expected 3 points only
here and got 4; "Deleting a profile brought back from a partly replaced snapshot
lists its saves again" failed with "Assert.Single() Failure: The collection was
empty"; the stray-branch test failed on the saves tip (a copy was made); the date
test failed on %aI (2026-10-25T01:19:08 vs 01:19:11); the record test and the
branch-exists test failed on the record staying on the old commit and a commit
object being written. Passing on first run, then mutation-checked: the
capture-id replacement and the marker check (engine tests), the held-by-a-profile
check (stray branch test), and the branch bookkeeping (fault tests) each made a
test fail when broken.

The delete preview now expects 2 snapshots going back to Recently removed (the
install one and the saves one), 3 points only here and 1 saves point.
Covers a failure after the copy folder's ref transaction (the other folder's
branch, and saving the profile) with the branches taken back and the snapshot
listed and brought back under its new id; a record deleted after it was read, so
the transaction's delete check refuses and nothing moves; a branch that appears
after the up-front check and is refused by the transaction's own create; and a
copy of a commit made with +09:00 and -03:30 offsets keeping both.

All of these passed on their first run, so each was mutation-checked: removing
the branch take-back failed both failure tests, dropping the delete line failed
the stale-record test, creating the branch with update instead of create failed
the race test, and normalizing the author date to UTC failed the offset test.
The old test expected the install folder to be kept as new when the replaced snapshot had no commit there. Under the Replace rule that folder joins (a new commit with the session's capture id) and the folder that holds the snapshot as its tip is amended, so nothing is kept as new.

Observed red before the change: A_folder_whose_newest_snapshot_is_not_the_one_replaced_... failed at the install KeptAsNew Assert.True (Expected True, Actual False), on integration-102 and on issue-105-session-attribution alone.

The kept-as-new case is now covered for real: replacing the first snapshot, which has a newer one behind it in both folders, is refused at save time, every folder is saved as a new snapshot and the save carries CaptureFolderKeptAsNew.

Both tests passed on first run. Mutation checks: ReplaceRule returning Refuse instead of Join for a missing commit fails the join test (Assert.False KeptAsNew); dropping Downgraded from the save-time downgrade fails the kept-as-new test (Assert.All KeptAsNew). Both restored.
Merge branch 'issue-111-partial-replace-removed' into integration-102
Some checks failed
Gate / linux (pull_request) Failing after 11m6s
Gate / windows (pull_request) Has been cancelled
6d58b9e066
Expect the MSYS2 source-list script tests to skip where pwsh is missing
Some checks failed
Gate / linux (pull_request) Successful in 11m46s
Gate / windows (pull_request) Failing after 25m11s
d0f767f617
The Linux CI container has no pwsh, so the 43 Msys2SourcesScriptTests skip there and the skip check failed the gate. They run on Windows. The names are copied from the skip check's own report.
Let the real-gpg test skip on Windows machines without gpg
Some checks failed
Gate / linux (pull_request) Successful in 12m29s
Gate / windows (pull_request) Successful in 26m47s
Wiki / publish (push) Successful in 50s
Release / linux (push) Failing after 1m34s
Gate / linux (push) Successful in 12m31s
Gate / windows (push) Successful in 27m19s
Release / windows (push) Successful in 2m38s
Release / checksums (push) Has been skipped
9af603939a
The Windows runner has no gpg, so the one test that runs the real gpg skips there and the skip check failed the gate. It runs where gpg is installed.
Sign in to join this conversation.
No reviewers
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ethan-hann/SavePoint!117
No description provided.