Skip to content

docs: clarify Recycler recovery phases and Cooking provider requirement #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanbarlow97 merged 2 commits into from
Oct 14, 2026
Merged

docs: clarify Recycler recovery phases and Cooking provider requirement #239

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
142c3b5
docs(recycler): gate delivered legacy recovery by journal phase
ryanbarlow97 Oct 14, 2026
c8716fb
docs(cooking): require patched transaction provider for ownership mig…
ryanbarlow97 Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions projects/Cooking/docs/husbandry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,10 +145,15 @@ reviewed heir remains the migration recipient. One SQLite transaction copies all
legacy owner columns into the immutable archive, verifies its count, writes the
fixed plan, inserts resolved character slots and writes completion. The archive
includes committed WAL content through SQLite itself and cannot cascade away
when an animal dies. SQL failures and runtime exceptions roll back the archive,
plan and ownership publication together. Under TLibs 2.6.0, a JVM `Error` inside
the transaction can commit partial rows instead; an unfinished migration then
requires staff repair using the preserved archive and legacy rows.
when an animal dies. TLibs **2.6.1** rolls back the archive, plan and ownership
publication together on any transaction body failure, including a JVM `Error`.
An uncertain rollback discards the connection; a clean server restart reopens
husbandry storage.
Verify that TLibs 2.6.1 is loaded before running ownership migrations; Cooking's
compilation pin remains 2.6.0, with the same public API. Under TLibs **2.6.0 and
earlier**, a JVM `Error` inside the transaction can commit partial rows instead.
An unfinished migration written under those providers still requires staff repair
using the preserved archive and legacy rows; upgrading TLibs does not repair it.
Missing heirs, malformed identities, unknown roles and
conflicting slots remain recorded for staff; another character never claims them
by opening a menu. Animal rows, snapshots, care, genes, timers and unknown columns
Expand Down Expand Up @@ -185,8 +190,11 @@ and character references must agree with the recorded decision.
Completed IDs must also agree with the preserved source archive for that
death/revision; missing or changed receipt IDs cannot authorize another transfer.

SQL failures, runtime exceptions and process interruption roll back the
transaction. The TLibs 2.6.0 JVM-error boundary above also applies to estates.
TLibs **2.6.1** rolls back transaction body failures, including a JVM `Error`;
process interruption rolls back uncommitted SQLite work. An uncertain rollback
also requires a clean server restart. Under TLibs **2.6.0 and earlier**,
a JVM `Error` can leave partial estate rows; upgrading the provider does not
repair those existing rows.
A retained incomplete intent
or conflicting same-revision receipt is BLOCKED for review; affected ownership
writers refuse changes while resolved co-owners can still care for or ride their
Expand Down
18 changes: 12 additions & 6 deletions projects/Recycler/docs/OWNERSHIP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,12 +147,18 @@ refunds, deliveries and restart recovery are held, and the tool refuses
migration rollback. Estate settlement and other legacy migrations can continue;
follow the operation ID through estate receipts to its current character copy.
After confirming that no older JAR delivered it, restore its exact bytes from
`ownership/backups/<before-hash>.bin`. If an older JAR did deliver it, stop Paper,
archive the current copy and its receipts, record that delivery and set any
undelivered character copy to `cancelled` with a reason before restoring the
legacy bytes. Reconcile already delivered copies manually. The restored legacy
file is inert in this version and must stay outside the old queue on downgrade.
The backup alone cannot prove that another delivery is safe.
`ownership/backups/<before-hash>.bin`. If an older JAR did deliver it, stop Paper
and inspect `phase` in `ownership/migration/<operation UUID>.json` before
restoring anything. Only for a `moved` journal, archive the current copy and its
receipts, record that delivery and set any undelivered character copy to
`cancelled` with a reason before restoring the legacy bytes. Reconcile already
delivered copies manually. For `planned` or `published`, keep the legacy file
absent, preserve the journal, any character copy and receipts, and reconcile them
manually with Paper stopped. Restoring a `planned` source can publish a fresh
pending return; cancelling a `published` copy and restoring its source leaves the
heir held. Do not reset the phase or delete history to force recovery. The
restored legacy file is inert in this version and must stay outside the old queue
on downgrade. The backup alone cannot prove that another delivery is safe.

If apply fails after restoring some records, the report's `applied` paths name
the completed actions alongside the original error. Preserve the backup and
Expand Down