Branch migration and recovery

This upgrade changes content API paths and database constraints. Apply it as a controlled maintenance operation, not during application startup. Local verification is separate from approval to deploy a production environment.

Before upgrading

1. Back up the application database and private transfer storage with environment-appropriate tools. Keep the previous application build and migration version.
2. Stop API and worker writers. Wait for open transactions to finish. Keep the panel unavailable for mutations until the new API and worker are ready.
3. Record per-project counts and content checksums for languages, keys, values, tags, bindings, history and pending jobs. Verify restoration of the backup in an isolated database.
4. Run pnpm db:migrate, then pnpm db:queue separately. Start only the upgraded processes.

The migration creates one main branch per project and attaches existing content and transfer jobs. Existing record IDs, values, versions and history are retained. New foreign keys and required branch scope prevent old branchless writers from continuing to insert content.

Afterward, compare counts, identities and checksums, check API/worker readiness, and verify sign-in, a content edit, fork, compare and export in an isolated test project. Never send test mail through production SMTP.

API changes

Content paths now include the branch UUID:

/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys
/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/languages
/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/tags
/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/imports
/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/exports
/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/transfers

Branchless content API routes are removed. Fetch the project’s mainBranchId or select a branch from /branches, and explicitly include it in each content request. Header browser preferences are not server authorization. Old panel bookmarks redirect to the migrated main branch; this browser compatibility behavior does not apply to API writes.

Project names and archives retain project versions. Language configuration uses its selected branch’s version. Key metadata and individual values keep their independent versions. Existing API reference operation links remain stable while their documented paths change.

Worker and recovery

The existing worker also consumes a separate branch queue with concurrency one; transfer concurrency remains independently configured. Queue migration creates both queues. The worker requires the updated application schema and retains its restricted application and queue roles.

Do not start an old writer against the new schema to roll back. Restore the pre-upgrade database and matching private files into an isolated environment, validate them with the retained build, then use an explicitly approved recovery procedure. Writes accepted after the backup need a separate recovery/export decision; an automatic downgrade never deletes their tables or data.