[rmcdaniel]

Part of #325: the backup-first in-place upgrade gate. Stacked on #529 (and #523); review those first. Implements the SQLite part of the design in #517.

Takeover

upgrade-takeover (development command; SQLite only for now) takes over a stopped PHP SQLite database in one BEGIN EXCLUSIVE transaction:

1. Runs the inventory, queue and payload inspections and requires their qualified results. External payloads and service calls are refused, since native cannot represent them yet.
2. Recomputes the fingerprint and refuses unless it equals DW_UPGRADE_BACKUP_FINGERPRINT, the digest the operator matched against the restored backup. Any write after the backup stops the takeover.
3. Adds the native relations and converts the recorded PHP release layout (frozen, php-2.8.0, php-2.9.7):
   • copies PHP's registration incarnations and tokens into native's table, so a running SDK worker's fenced deregistration still matches, and creates one for any active registration without it;
   • drops the PHP-only incarnation table and columns.
4. Records the native migration in the ledger and runs native's own startup verification (marker, ledger and full catalog) before committing.

A refusal or interruption leaves the PHP file byte-identical. A committed takeover is a database native opens and PHP 2.5.14+ refuses. rust/README.md documents the procedure.

History written by PHP

The resume check found that native presented PHP-written history differently from PHP. PHP stores encoded values as bare strings beside their codec and wraps them into {codec, blob} envelopes when reading. It also lifts the command's principal to each public event and keeps only neutral fields of an activity failure. Native stores envelopes, so command.payload and activity.arguments came back as strings and principal was missing.

history_presentation.rs ports those rules (ExternalPayloadEnvelopeService::historyPayload, HistoryController::eventPrincipal) into native's history rendering. It applies to public history and worker task history. Only bare strings are wrapped, so native's own envelopes are unchanged.

Checks

• Unit tests (SQLite).
  • A 2.9.7-shaped database with PHP incarnations is taken over and opened by native: the PHP token is kept, retired incarnations keep their state, and a registration without one gets one.
  • The frozen layout is taken over.
  • A wrong or stale fingerprint, a malformed one, a service call and an external payload are each refused with the file unchanged.
  • Presentation tests cover envelopes, principals, failure redaction, and unsupported codecs and references.
• Upgrade source cohort (SQLite; both the default 2.8.0 run and the labeled 2.9.7 run). Takes over a copy of the stopped published-PHP source and starts native on it. The PHP-written originals then resume:
  • the PHP-leased activity completes with its original attempt, and a replay records nothing;
  • the PHP-completed workflow task is refused with 409 task_not_leased;
  • the PHP-scheduled timer fires at its original deadline;
  • both workflows complete, and their PHP-written events read exactly as PHP returned them, payloads and principals included;
  • PHP then refuses the upgraded file with php_database_refused.
• Local results. Both cohort runs passed (timer fired 0.012 s and 0.102 s after its deadline). Full native suite on SQLite, PostgreSQL and MySQL: unit and execution tests passed on all three, apart from two execution tests that rebuild control history from worker events and lacked the new principal field. With the projection corrected, both pass, and the upgrade tests (40) pass on all three after merging Fingerprint a stopped PHP source database for backup proof #523's latest head.

CI

This branch contains #523 and #529, so its Shared Server fixtures run qualifies the whole stack; #529's own run is cancelled to save runners.

Not covered yet

PostgreSQL and MySQL/MariaDB takeover (transaction and exclusion per the design), nested payload columns the inspection does not scan yet, takeover with external payloads or service calls, and multi-node qualification. The takeover report keeps stored_representation_compatibility_verified: false.

🤖 Generated with Claude Code