Before upgrading
Record source revision/distribution version, lockfile, SDK versions, migration inventory, and deployment configuration. A local build is not automatically a named public release. Settle Runs, close Sessions, and confirm cleanup. Reconcile unknown outcomes first. Create an offline matching backup and retain the corresponding old code. Do not assume a new worker can resume arbitrary historical invocations. Credential-boundary, Runtime-protocol, or Harness changes can require fresh Sessions; read their migration instructions.Apply the update
Prepare new code independently while retaining the old distribution. Install its locked dependencies. Managed local startup performs migrations:npm run db:migrate before starting; the hosted deployment prerequisites for identity and keys still apply. Do not improvise a mixed-version rollout over the same deployment.
Migrations run under a database transaction/advisory lock. Changed applied SQL checksums are rejected. Unknown newer migrations produce database_schema_newer_than_code. Do not delete migration records or edit historical SQL to bypass protection.
Verify afterward
Confirm identity/database/key alignment and working management/credential ingress. Read historical initialization, Runs, events, and artifacts. Complete a fresh task using the intended combination. Check affected contracts in both SDKs and run each full cloud journey when the change requires it. Review previews, authorization/approval, and cleanup according to impact. Type checking alone does not prove migration or cloud recovery. Record actual commands, versions, successes, and failures.Preserve an exact upgrade pair
Record both source and destination distribution fingerprints, theirrelease.json metadata when available, lockfile hashes, applied migration names/checksums, SDK package versions and the backup manifest. A content fingerprint is not a Git revision or a signed release. Keep the old artifact itself; a directory name alone cannot reproduce it.
The November 18 local distribution drill documents a restored database started with a newer compiled distribution, retained history/decryption and subsequent independent cloud tasks. It does not define a universal supported release-to-release upgrade matrix. Until the running source/destination build pair is tied to its verification results, use this as a scoped process example and record your own pair.
The retained build manifests identify the following unpublished build fingerprints in that drill:
The restored-workspace Python and TypeScript records both report artifact verification and confirmed cleanup. Their cloud work preceded the final build; the TypeScript journey started at 13:04:39 UTC. Therefore those tasks must not be reported as execution of
beta-delivery. The matrix does not attest the serving process’s exact build fingerprint. This is a verified installation/restore/upgrade process example, with 27 restored tables matching their original counts and hashes, not an independently certified final-build release pair. For a new upgrade, record the actual running source/destination fingerprint alongside the new task results before claiming that exact pair passed.