fix: auth error

migrations/versions/f6a7b8c9d0e1_seed_role_permissions_and_fix_scope.py

@@ -13,12 +13,30 @@ and common/auth/membership.py::resolve_is_system_admin). This migration:
   3. INSERT role_permissions join rows: admin gets all 12, developer
      gets the 6 `*.own` / personal-resource codes.
 
-permission_id values are deterministic (sha256 of code) so a
-downgrade → upgrade cycle is idempotent on the uk_permissions_code
-unique index. Downgrade soft-deletes (is_deleted=1, deleted_at=now)
-the rows this migration inserted; it does NOT revert role_scope
-because that fix is not safely reversible once app code has touched
-the rows.
+Caveats (read before re-running):
+
+* ``permission_id`` is derived from a sha256 of the code with the salt
+  prefix ``model-platform-permission-v1:``. The legacy
+  ``migrations/data/migrate_system_json.py`` script uses a different
+  salt (``model-platform-v1:permission:``), so the same
+  ``permission_code`` maps to a DIFFERENT ``permission_id`` between the
+  two paths. The legacy script's ``existing.get(permission_code)`` check
+  keeps the row count correct (it reuses the live row by code), so this
+  is not a crash; the IDs only matter if a downstream system ever
+  cross-references by deterministic ID, which nothing does today.
+
+* ``downgrade()`` is a SOFT delete (``is_deleted=1``). Running
+  ``alembic downgrade`` followed by ``alembic upgrade`` will collide on
+  the ``permission_id`` PRIMARY KEY — downgrade is a one-way trip on
+  any environment that has run this migration. The role_scope fix is
+  not reverted on downgrade (app code already keys off `platform`).
+
+* If the legacy one-off ``migrations/data/migrate_system_json.py`` is
+  ever run AFTER this migration on the same database, its
+  ``existing.get(permission_code)`` check will keep counts correct but
+  reuses our rows; running it BEFORE this migration would cause
+  ``uk_permissions_code`` collisions on upgrade. Run this migration
+  first on a fresh database.
 
 Revision ID: f6a7b8c9d0e1
 Revises: e5f6a7b8c9d0 (ensure_demo_login)