Skip to content

Commit 047569e

Browse files
authored
docs: clarify Recycler recovery phases and Cooking provider requirement (#239)
* docs(recycler): gate delivered legacy recovery by journal phase * docs(cooking): require patched transaction provider for ownership migration
1 parent 06038bf commit 047569e

2 files changed

Lines changed: 26 additions & 12 deletions

File tree

‎projects/Cooking/docs/husbandry.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -145,10 +145,15 @@ reviewed heir remains the migration recipient. One SQLite transaction copies all
145145
legacy owner columns into the immutable archive, verifies its count, writes the
146146
fixed plan, inserts resolved character slots and writes completion. The archive
147147
includes committed WAL content through SQLite itself and cannot cascade away
148-
when an animal dies. SQL failures and runtime exceptions roll back the archive,
149-
plan and ownership publication together. Under TLibs 2.6.0, a JVM `Error` inside
150-
the transaction can commit partial rows instead; an unfinished migration then
151-
requires staff repair using the preserved archive and legacy rows.
148+
when an animal dies. TLibs **2.6.1** rolls back the archive, plan and ownership
149+
publication together on any transaction body failure, including a JVM `Error`.
150+
An uncertain rollback discards the connection; a clean server restart reopens
151+
husbandry storage.
152+
Verify that TLibs 2.6.1 is loaded before running ownership migrations; Cooking's
153+
compilation pin remains 2.6.0, with the same public API. Under TLibs **2.6.0 and
154+
earlier**, a JVM `Error` inside the transaction can commit partial rows instead.
155+
An unfinished migration written under those providers still requires staff repair
156+
using the preserved archive and legacy rows; upgrading TLibs does not repair it.
152157
Missing heirs, malformed identities, unknown roles and
153158
conflicting slots remain recorded for staff; another character never claims them
154159
by opening a menu. Animal rows, snapshots, care, genes, timers and unknown columns
@@ -185,8 +190,11 @@ and character references must agree with the recorded decision.
185190
Completed IDs must also agree with the preserved source archive for that
186191
death/revision; missing or changed receipt IDs cannot authorize another transfer.
187192

188-
SQL failures, runtime exceptions and process interruption roll back the
189-
transaction. The TLibs 2.6.0 JVM-error boundary above also applies to estates.
193+
TLibs **2.6.1** rolls back transaction body failures, including a JVM `Error`;
194+
process interruption rolls back uncommitted SQLite work. An uncertain rollback
195+
also requires a clean server restart. Under TLibs **2.6.0 and earlier**,
196+
a JVM `Error` can leave partial estate rows; upgrading the provider does not
197+
repair those existing rows.
190198
A retained incomplete intent
191199
or conflicting same-revision receipt is BLOCKED for review; affected ownership
192200
writers refuse changes while resolved co-owners can still care for or ride their

‎projects/Recycler/docs/OWNERSHIP.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -147,12 +147,18 @@ refunds, deliveries and restart recovery are held, and the tool refuses
147147
migration rollback. Estate settlement and other legacy migrations can continue;
148148
follow the operation ID through estate receipts to its current character copy.
149149
After confirming that no older JAR delivered it, restore its exact bytes from
150-
`ownership/backups/<before-hash>.bin`. If an older JAR did deliver it, stop Paper,
151-
archive the current copy and its receipts, record that delivery and set any
152-
undelivered character copy to `cancelled` with a reason before restoring the
153-
legacy bytes. Reconcile already delivered copies manually. The restored legacy
154-
file is inert in this version and must stay outside the old queue on downgrade.
155-
The backup alone cannot prove that another delivery is safe.
150+
`ownership/backups/<before-hash>.bin`. If an older JAR did deliver it, stop Paper
151+
and inspect `phase` in `ownership/migration/<operation UUID>.json` before
152+
restoring anything. Only for a `moved` journal, archive the current copy and its
153+
receipts, record that delivery and set any undelivered character copy to
154+
`cancelled` with a reason before restoring the legacy bytes. Reconcile already
155+
delivered copies manually. For `planned` or `published`, keep the legacy file
156+
absent, preserve the journal, any character copy and receipts, and reconcile them
157+
manually with Paper stopped. Restoring a `planned` source can publish a fresh
158+
pending return; cancelling a `published` copy and restoring its source leaves the
159+
heir held. Do not reset the phase or delete history to force recovery. The
160+
restored legacy file is inert in this version and must stay outside the old queue
161+
on downgrade. The backup alone cannot prove that another delivery is safe.
156162

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

0 commit comments

Comments
 (0)