platform/deploy/2026.08.23.05.md

2026.08.23.05

Five languages instead of one, roles become real database rows with a foreign key behind them, and Minesweeper leaves the platform to become the first plugin with its own websocket.

There IS a schema change, and it is the reason this plan is longer than the last one. Two foreign keys and one dropped CHECK, on users and role_permissions. Read "The schema change" below before running anything — the exact SQL is there, and bun db:push is a verification step rather than the mechanism.

No dependency change. bun.lock is untouched. Do not run bun install.

What is in it

• Five locales, complete and in step. en-GB, pt-PT, es-ES, de-DE, fr-FR — 1,129 keys each. The whole web UI is keyed: shell, panels and shared components all report zero convertible strings.
• Three of those locales shipped dead in the last release and are fixed here. es-ES, de-DE and fr-FR were translated, in parity, and offered by the picker — while all three catalogue files still imported only en-GB and pt-PT, so choosing one rendered the entire UI in raw keys. The parity tests could not have caught it: they compare JSON files to each other, and a file nobody imports is as parity-correct as one that is loaded. lib/catalogues.test.ts is now the thing that knows.
• Roles are a table with a foreign key, not a TypeScript union. USER_ROLES is gone, UserRole is string, and the compile-time guard moves to a runtime check at every write path that takes a role from outside. Renaming a role now moves its holders and grants atomically, as Postgres's job.
• Minesweeper is a plugin (gitea.officer.dev/plugins/minesweeper), not part of the platform. The permission registry drops from 22 entries to 21 — execution goes 4 to 3.
• Plugins can have websockets. /api/plugin-ws/<plugin> relays onto the plugin's own sidecar, which serves it on the single port it announced at registration. Authorisation is the plugin's own permission, so there is no second grant to forget.
• A plugin can declare the architecture its packages need. multiarch: 'i386' runs dpkg --add-architecture and apt-get update before installing, on apt hosts, skipped when already enabled. A closed enum rather than a command, because it runs as root.
• Foreign keys are named explicitly across the fleet's plugins, ending the db:push churn where Postgres truncated an over-long generated name and drizzle-kit re-created the constraint every run.

The schema change

Both foreign keys reference roles.name, so every value in users.role and role_permissions.role must already exist as a row in roles, or the constraint cannot be created.

That was checked on every host before this tag was cut. All five are on deploy/2026.08.23.04, which is the release that created and seeded roles; alpha, fofos, production-pertento-bridge and deadpool-rezio-bridge each report roles = 4 and 0 orphans. macbookpro was NOT verified — it has no psql client, so only its tag could be read. Check it there before running the SQL, by whatever means that host offers.

Run this first, before bun db:push. It is idempotent and safe to run twice.

-- Refuse to proceed if any role in use is not a real row. Raises rather than half-applying.
DO $$
DECLARE bad int;
BEGIN
  SELECT count(*) INTO bad FROM (
    SELECT u.role FROM users u LEFT JOIN roles r ON r.name = u.role WHERE r.name IS NULL
    UNION ALL
    SELECT p.role FROM role_permissions p LEFT JOIN roles r ON r.name = p.role WHERE r.name IS NULL
  ) x;
  IF bad > 0 THEN
    RAISE EXCEPTION 'STOP: % role value(s) have no matching roles row. Do not continue; report this.', bad;
  END IF;
END $$;

ALTER TABLE role_permissions DROP CONSTRAINT IF EXISTS ck_role_permissions_role;

DO $$ BEGIN
  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_users_role') THEN
    ALTER TABLE users ADD CONSTRAINT fk_users_role
      FOREIGN KEY (role) REFERENCES roles(name) ON UPDATE CASCADE;
  END IF;
END $$;

DO $$ BEGIN
  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_role_permissions_role') THEN
    ALTER TABLE role_permissions ADD CONSTRAINT fk_role_permissions_role
      FOREIGN KEY (role) REFERENCES roles(name) ON UPDATE CASCADE;
  END IF;
END $$;

ck_role_permissions_not_owner stays. It is a different constraint and this release does not touch it.

Then verify by querying, not by reading an exit code:

SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint
WHERE conname IN ('fk_users_role','fk_role_permissions_role',
                  'ck_role_permissions_role','ck_role_permissions_not_owner');

Both fk_ rows must be present and say ON UPDATE CASCADE with no ON DELETE. ck_role_permissions_role must be absent. ck_role_permissions_not_owner must be present. Put that output in the report — for this release it is the evidence, and "schema ✓" without it is a guess.

Every host

1. git fetch origin --tags then git merge --ff-only deploy/2026.08.23.05
2. The SQL above, then the verification query. Stop on the RAISE EXCEPTION and report it.
3. bun db:push — expect no changes. If it still wants to alter something after step 2, the SQL was incomplete; stop and report rather than letting it improvise.
4. bun run plugins:update
5. pm2 restart officer

officer only at step 5. Step 4 restarts each plugin's own sidecar, which belongs in the report.

macbookpro: append /opt/homebrew/bin to PATH for the bun commands, run pm2 separately.

What to check, this release

The language picker in profile settings should offer five languages — English (UK), Português (Portugal), Español, Deutsch, Français. Pick one that is not English and look at a panel, not just the shell: the last release's defect was invisible in the shell and total in the panels.

A host still offering two languages did not pick up the frontend bundle.

Minesweeper should be absent from the dock and /minesweeper should 404. It is a plugin now and no host has it installed. That is correct, and installing it is not part of this release.

Hosts

• edge-pertento-bridge — skipped, per docs/servers.md. Name it and spend nothing on it.
• macbookpro — the one host whose roles table could not be verified before the tag. Check it, then proceed; do not skip it on that account.
• All five others were on deploy/2026.08.23.04 when this was cut, so each is exactly one release behind.

officer-dev — skip it

The schema change is already applied there, verified by query, and the second db:push emitted no DDL. Restarting officer on the host running the rollout ends the rollout. Name it as skipped and say it is current.