Research: estates and atomic station saves (stage 6b)

projects/Research/README.md

@@ -10,7 +10,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 Research builds with Java **21** against
 `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
-`2.3.0` and RPCharacters `2.16.0` release artifacts with the shared dependency
+`2.6.0` and RPCharacters `2.16.0` release artifacts with the shared dependency
 installer. The build also prepares checksum-verified MMOCore `1.13.1-SNAPSHOT` and
 MythicLib `1.7.1-SNAPSHOT` inputs from the private ServerAssets repository.
 

projects/Research/overview.md

@@ -142,7 +142,29 @@ open station menus before changing `labels` titles or `colors.inventory_title`.
 - **TLibs.** TLibs builds and matches every item path, formats text, and supplies
   shared character identity and session events through RPCharacters' provider.
   Research needs TLibs 2.3.0 or newer; with an older TLibs it logs a severe
-  error and disables itself.
+  error and disables itself. Estates need TLibs 2.6.0 (see below); on 2.3.0 to
+  2.5.0 Research runs normally and logs that stations of dead characters stay
+  with them.
+- **Estates.** With TLibs 2.6.0, Research is the `research` participant in
+  RPCharacters estates. When a dead character's estate is decided, every station
+  whose recorded character is the dead one goes to the estate's property
+  recipient (the will heir, or the death guild's leader): the station file's
+  owner account and character are both rewritten, so the recipient's character
+  carries on the project with its progress. A recipient on the same account keeps
+  the account and takes the character. Waiting or frozen property leaves the
+  stations with the dead character, unusable, until staff assign it. Moves happen
+  only while the character is still dead with that death and the estate is
+  decided at the current revision; a revived character keeps what had not moved.
+  Before changing any station, Research writes
+  `plugins/Research/data/estates/<deathId>.json` listing the stations it will move
+  and the recipient, and marks each one moved; a crash between stations is
+  finished at the next settle. The outcome sent to the estate lists every moved
+  station's `<world>_<x>_<y>_<z>` key, which `/estate show` displays; to undo a move
+  by hand, give those stations whose owner is still the recipient back to the dead
+  character. A station that fails to save keeps its old owner and is retried. The
+  will screen and `/estate show` list the character's stations. Research settles
+  decided estates on the first tick after start-up and every hour, and reports
+  only changed answers. Stations without a recorded character are never moved.
 - **`ResearchCompleteEvent`.** Listen for
   `net.tfminecraft.research.event.ResearchCompleteEvent`, which fires
   synchronously after the result spawns and cannot be cancelled. It exposes
@@ -157,7 +179,9 @@ open station menus before changing `labels` titles or `colors.inventory_title`.
   the owner account and character, input, output, result path, product
   reveal, aspect points and states, tested items, and row order.
 - Station files are written when a project starts, after each confirmed
-  experiment, and on a normal plugin disable. They are deleted when a project
+  experiment, when an estate moves the station, and on a normal plugin disable.
+  Each write goes to a temporary file that is flushed and then moved over the
+  station file, so a crash leaves the old or the new file whole. They are deleted when a project
   completes, is scrapped, or its block is broken.
 - On start, files that reference an unknown input, output, or world are skipped
   with a warning and left on disk. A missing or stale row order is reshuffled.
@@ -166,8 +190,28 @@ open station menus before changing `labels` titles or `colors.inventory_title`.
   or Research's event listeners have stopped, and then saves the stations.
 - The station JSON schema is unchanged. New ownership uses the canonical character
   UUID; existing UUID strings compare without regard to letter case and are not
-  rewritten. Projects without a recorded character are claimed only by a ready
-  character on their owner account.
+  rewritten.
+- **Heir backfill (once per server).** Stations saved before characters were
+  recorded go to their account's reviewed heir, as locks and vehicles did in stage
+  6a. On a start-up where TLibs reports reviewed heirs ready, Research inventories
+  the persisted station files independently of recipe and world loading. Valid
+  ownership metadata with no recorded character goes to its account's legacy heir,
+  including stations skipped for an unknown input, output or world. The plan at
+  `plugins/Research/data/backfill-character-v1/plan.json` records each station's
+  original account and fixed heir before any change. An heir on another account
+  is refused. The original station file is backed up durably to `backup/` in that
+  folder (never overwritten); only the ownership field is then written atomically,
+  preserving recipe, progress and extension fields. Loaded stations receive the
+  same ownership change.
+  `done.json` records the filled count, stations whose account had no heir, and
+  invalid, missing or changed station files skipped for staff review. These lists
+  are also logged. Once the marker exists, later starts do nothing. If heirs are
+  not ready, or a planned station cannot be read, backed up or saved, no marker is
+  written and the next start reuses the same plan. Replay checks the file's location
+  and original account and leaves a station claimed by another character alone;
+  incomplete or unreadable plans are refused. Stations whose account has no heir
+  stay unassigned: the first ready character on their owner account claims them
+  when it opens them. Stations the backfill filled belong to the heir only.
 
 Back up the complete `plugins/Research/` directory before renaming identifiers
 or migrating configuration, and stop the server cleanly before copying live