# Web Blender Modeler V1 Release Recovery

Use this procedure for `0.1.0-rc.1` upgrades and failed deployments. The complete installation,
upgrade and rollback contract remains [DEPLOYMENT.md](DEPLOYMENT.md). Never clear Chromium site data,
delete a browser profile, overwrite a release directory or downgrade a storage schema as a recovery
shortcut.

## Verify the delivery

The delivery directory must contain `blender-web-offline.tar.gz`,
`blender-web-corresponding-source.tar.gz`, `SHA256SUMS.txt`, `RC_MANIFEST.json` and
`RC_MANIFEST.json.sha256`. Verify bytes before extracting:

```bash
cd /absolute/path/to/delivery
sha256sum --check SHA256SUMS.txt
sha256sum --check RC_MANIFEST.json.sha256
```

Both commands must report `OK`. Check that the manifest identity is
`web-blender-0.1.0-rc.1`, its commit and `engineReleaseId` match the release record, and its binary,
source and SBOM hashes match the delivered files. In a corresponding source checkout, independently
run:

```bash
npm --prefix web ci --ignore-scripts
npm --prefix web run test:rc-manifest
npm --prefix web run test:binary-archive
npm --prefix web run test:source-archive
node tools/web/check-ci-report.mjs release/ci-reports/quick.json \
  release/ci-reports/chromium.json release/ci-reports/release.json
```

Do not deploy when any command fails or when a report is not `READY` and bound to the manifest commit,
lockfile, ledger, engine and archive hashes.

## Back up projects before upgrade

1. Record the exact public origin, including scheme, host and port. Upgrades must retain that origin
   because IndexedDB and OPFS data are origin-bound.
2. For every critical project, finish active edits and use the top-bar **Save Project** action. Wait
   for the committed/saved state and retain the downloaded `blender-web.blend` outside the browser
   profile and outside the deployment install root.
3. Record the project's displayed SceneIR revision and calculate the external backup hash with
   `sha256sum blender-web.blend`. Reopen the downloaded file with the current release and confirm the
   expected objects before entering the maintenance window.
4. Record `readlink current`, the old binary archive SHA-256 and both old/new
   `release-metadata.json` files. Keep the old content-hash release directory, new staged directory,
   external project backups and browser profile through the rollback window.

A backup is not complete merely because OPFS still contains a project. The external `.blend`, revision,
SHA-256, origin and active release identity form the recovery record.

## Upgrade failure before the switch

If checksum, archive path, header, MIME, range, engine hash, Worker or cold-start preflight fails before
`current` changes, leave `current` on the old release. Remove only the incomplete staging directory
after diagnostics are captured. Do not change IndexedDB, OPFS, browser caches or the old release.

Repeat the delivery checks and the loopback preflight from [DEPLOYMENT.md](DEPLOYMENT.md). A failed
candidate remains uninstalled until its binary hash and all preflight evidence pass.

## Upgrade failure after the switch

Stop new sessions and require active saves to finish. Capture the active origin, `current` target,
both release metadata files, failing URL/headers, error code, project revision and project SHA-256.

Compare the browser's opened IndexedDB and OPFS schema versions with the old target:

- If the IndexedDB versions match and the OPFS project manifest versions match, validate the complete
  old release on a loopback port. Atomically repoint `current` to that old content-hash directory using
  the rollback commands in [DEPLOYMENT.md](DEPLOYMENT.md). Revalidate transport and engine identity,
  reopen the same project, and require the recorded revision and blend SHA-256 before allowing an edit.
- If the old IndexedDB schema is lower, rollback is `BLOCKED` with
  `INDEXEDDB_SCHEMA_DOWNGRADE_UNSUPPORTED`. Do not open, delete or recreate the database with the old app.
- If the OPFS schema differs without an exact tested reverse reader, rollback is `BLOCKED` with
  `OPFS_REVERSE_MIGRATION_UNDECLARED`. V1 does not claim a general reverse OPFS migration.

For a blocked rollback, keep or restore the newer compatible app release. Deploy a forward-compatible
repair using the current storage schemas, or start the old release on a separate recovery origin/profile
and import an external pre-upgrade `.blend` backup. Never point the old app at newer incompatible site
data.

## Restore and prove project integrity

After a compatible rollback or repair:

1. Open the recorded origin in a new Chromium tab and confirm the expected release/engine identity.
2. Use **Recover Project** for unchanged compatible origin storage. If that fails or a separate recovery
   origin is required, use **Open .blend** and select the external backup.
3. Confirm the recorded objects and revision, use **Save Project**, then hash the new downloaded
   `blender-web.blend`. The hash must equal the recorded backup unless a deliberate post-recovery edit
   was made.
4. Keep the failed release, logs, diagnostics and external backup until the recovery record contains the
   final origin, release ID, revision and SHA-256.

The automated rehearsal command is:

```bash
npm --prefix web run test:operations-rehearsal
```

It verifies delivery, fresh install, HTTP preflight, project revision/SHA-256 preservation, upgrade,
compatible rollback and cleanup in one new temporary root. It does not replace real project exports or
authorize a schema downgrade.