@bongos/core 1.19.171 → 1.19.172

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.171",
-  "core_contract": "1.19.171",
-  "source_commit": "d102a0205fd62edcc81a804a8c439af4cde60606",
+  "core_version": "1.19.172",
+  "core_contract": "1.19.172",
+  "source_commit": "d488f4a69b30ec2fe81f95cc1ec652c25af8fc68",
   "source_ref": "HEAD",
-  "built_at": "2026-08-16T19:20:36.950Z",
+  "built_at": "2026-08-16T19:39:18.102Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 305,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1269,
+    "functional_verbatim": 1271,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1595,
-  "tree_sha256": "1596294ffbb9fe146a18ced51823d4b074c23b5dd47601619bcd16752c5eaf04",
+  "file_count": 1597,
+  "tree_sha256": "c7aad1a023cefa6bce6c0403ed5d0bf9c1e5a28b4e38e14a85f1cfc697d5edb3",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -347,12 +347,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "d6d6163164f98c96a8e25dfe84825669bf8324f1f1b98adb0674781ad235ad10"
+      "sha256": "a13c27a7d671408579dedf417b7f28486bebc52b7a685ba3900cd4eca843957c"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "386706d0ef3d09c5e074bdc45bfc0de869d732eb1cb2a2280472f02f797f2b74"
+      "sha256": "7b6abb75150b8fdc9fba1e0d765c049979da7cdd1d6a20eeeb6f3d5e3886ebc7"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -362,17 +362,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "7d462b5b80c9db9159981406398fc62c5ba71043c6a3b9433852d06d612bf2b0"
+      "sha256": "a4a864366450b849bafc096807f37cd16c8ed624470473aaf4907b24ab104778"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "4acb1dde6f894ba37cff7e27e0110f12ae30c7cb6e4d972d6e85d2877489b6d0"
+      "sha256": "c032e9796a9feeee86929323992511d5ed1cb448975481f98f86cee1b3790d50"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "4c7679ef258644ab12db1b8fe412b388f96f4296c6aae45d6ab637a8f3b9a037"
+      "sha256": "cc177720f5f3b0971edac3f03464e3dd5930b48d12811cd9ab39a7b6ceaaeb9c"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1347,12 +1347,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "ccf59372e0456f36d83154d6dff4dbf5382e8d69023bee82b318b8e9cfb2c50b"
+      "sha256": "d1595faad24aafba420199b3115b11ee5387de7c97c7f4fe7fe4f138f43dd79a"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "4deac83a1d7c12e1a24109e856d9a6fef6b539afafdca55a525ab6786fe4e235"
+      "sha256": "1435287ef26983d7088555abc9f18df97ceb4a8676be091ff49076e54a4366ab"
     },
     {
       "path": "docs/architecture.md",
@@ -2662,7 +2662,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "7d462b5b80c9db9159981406398fc62c5ba71043c6a3b9433852d06d612bf2b0"
+      "sha256": "a4a864366450b849bafc096807f37cd16c8ed624470473aaf4907b24ab104778"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -3789,6 +3789,11 @@
       "mode": "0000644",
       "sha256": "cce2f971f030aa628f9d7855f2e421595ea71cb314e90965206dbe970b7beded"
     },
+    {
+      "path": "modules/platform-identity/migrations/platform_identity_008_handle.sql",
+      "mode": "0000644",
+      "sha256": "f78eb8f7b6ee1ea3ddd789d6019b9715ae193ff0cb7890aeb24d8473033a911a"
+    },
     {
       "path": "modules/platform-identity/module.json",
       "mode": "0000644",
@@ -3797,7 +3802,7 @@
     {
       "path": "modules/platform-identity/platform-identity.js",
       "mode": "0000644",
-      "sha256": "96907af1af78c472118ecf5ed9f269d6d2ce940b09535aae3b3df4de4d2337c1"
+      "sha256": "115be49e667716d760610f8a9b167eeea4e0e6b61c40c7b9a439703847b61dcd"
     },
     {
       "path": "modules/platform-identity/pollers/code-sweep.js",
@@ -3817,7 +3822,7 @@
     {
       "path": "modules/platform-identity/routes/profile.js",
       "mode": "0000644",
-      "sha256": "6ea29b4f07417fa925b7987dd7fbe8a0262b7fec83ceffade9fccbc220289bba"
+      "sha256": "29e7f6304b4215fd79c35662c48370a04a5a9ffa2c3c4ae3d1fabf277d407eb2"
     },
     {
       "path": "modules/platform-identity/routes/projects.js",
@@ -3837,7 +3842,7 @@
     {
       "path": "modules/platform-identity/tests/platform-identity.mjs",
       "mode": "0000644",
-      "sha256": "18bf8d0cb42d76bc5413c760b13837fe439a6e719b88a84db96f143b829e67d5"
+      "sha256": "4b7f13effc33d5d16a5f87d0915ed31e107f138ef135822745774f90192ad327"
     },
     {
       "path": "modules/platform-identity/ui/.gitkeep",
@@ -4212,12 +4217,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "90e1fc07f655eb2874620b5a85f965e4f32cc20aeddb552dbc8885c4681150d9"
+      "sha256": "3da96cec73d1af6c4f1470d29cc26187cc949eba5b6fb7291b89da3da4c7eae7"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2b1408849261b93418e448820da8081a7ec83fa6b5c2a51b9e1aa5dca7456efb"
+      "sha256": "dbf95e145339c9e8d52b1e532e452eb2d344c0c0f06a28f58c6e19366e256dd6"
     },
     {
       "path": "public-docs/index.html",
@@ -5822,7 +5827,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "17202c8572c75ca1af5cd2eee1c8dd1ba4b6ea4c5fd7cd757eaf97907d26a268"
+      "sha256": "bc1f9966a0040b5239664c1a5d993c302b1fa9c56d2080c97b168115a4da847a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6904,6 +6909,11 @@
       "mode": "0000644",
       "sha256": "82bf1cc68150c247c108308d360d6408511f31a7af11d5e7a4721e7ea282f2bb"
     },
+    {
+      "path": "tests/handle_machinery.mjs",
+      "mode": "0000644",
+      "sha256": "755f49404e97c60c8c264f5f4c9d563a7c4ee4f51b43afe96fd10acce52ebe7b"
+    },
     {
       "path": "tests/helpers.mjs",
       "mode": "0000644",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 273 operations across 45 resource groups
+- 274 operations across 45 resource groups
 
 ## Install
 

package/clients/bongos-client/bongos-client.global.js

@@ -423,6 +423,8 @@ function createClient(opts = {}) {
       getMeEventSoundPrefs: (args) => request("GET", "/me/event-sound-prefs", { hasBody: false }, args),
       // PATCH /me/event-sound-prefs — rank: any-builder — PATCH /me/event-sound-prefs
       patchMeEventSoundPrefs: (args) => request("PATCH", "/me/event-sound-prefs", { hasBody: true }, args),
+      // PATCH /me/handle — rank: any-builder — PATCH /me/handle
+      patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/clients/bongos-client/index.cjs

@@ -422,6 +422,8 @@ function createClient(opts = {}) {
       getMeEventSoundPrefs: (args) => request("GET", "/me/event-sound-prefs", { hasBody: false }, args),
       // PATCH /me/event-sound-prefs — rank: any-builder — PATCH /me/event-sound-prefs
       patchMeEventSoundPrefs: (args) => request("PATCH", "/me/event-sound-prefs", { hasBody: true }, args),
+      // PATCH /me/handle — rank: any-builder — PATCH /me/handle
+      patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/clients/bongos-client/index.d.ts

@@ -51,7 +51,7 @@ export interface GetInboxResponse { ideas: unknown; open_count: unknown }
 export interface GetLeaderboardResponse { leaderboard: unknown; page: unknown }
 export interface GetLearningsResponse { learnings: unknown }
 export interface GetMeAchievementsResponse { unlocked: unknown }
-export interface GetMeCrossProjectResponse { hide_stats: boolean; profile_state: unknown; cross_project: unknown }
+export interface GetMeCrossProjectResponse { hide_stats: boolean; profile_state: unknown; handle: unknown; cross_project: unknown }
 export interface GetMeDisplayNameResponse { display_name: unknown; max_length: unknown }
 export interface GetMeEventSoundPrefsResponse { prefs: unknown; effective: unknown; effective_wav: unknown; events: unknown }
 export interface GetMeRecentShipsResponse { ships: unknown }
@@ -131,6 +131,8 @@ export interface PatchMeDisciplinesRequest { preferred_disciplines: string[] }
 export interface PatchMeDisciplinesResponse { builder: unknown; onboarding: unknown }
 export interface PatchMeDisplayNameResponse { display_name: unknown; max_length: unknown }
 export interface PatchMeEventSoundPrefsResponse { prefs: unknown; effective: unknown; effective_wav: unknown; events: unknown }
+export interface PatchMeHandleRequest { handle: string }
+export interface PatchMeHandleResponse { handle: unknown; previous_handle: unknown }
 export interface PatchMeSkillPrefsResponse { prefs: unknown; effective: unknown; defaults: unknown; known_skills: unknown; allowed_models: unknown }
 export interface PatchMeSoundPrefsResponse { prefs: unknown; effective: unknown; effective_map: unknown; volume: unknown; defaults: unknown; known_sounds: unknown }
 export interface PatchProjectsIdFeaturedRequest { featured: boolean }
@@ -662,6 +664,8 @@ export interface BongosClient {
     getMeEventSoundPrefs(args?: RequestArgs): Promise<GetMeEventSoundPrefsResponse>;
     /** PATCH /me/event-sound-prefs — rank: any-builder */
     patchMeEventSoundPrefs(args?: RequestArgs): Promise<PatchMeEventSoundPrefsResponse>;
+    /** PATCH /me/handle — rank: any-builder */
+    patchMeHandle(args: RequestArgs & { body: PatchMeHandleRequest }): Promise<PatchMeHandleResponse>;
     /** GET /me/interaction — rank: any-builder */
     getMeInteraction(args?: RequestArgs): Promise<ApiResponse>;
     /** PATCH /me/interaction — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -419,6 +419,8 @@ export function createClient(opts = {}) {
       getMeEventSoundPrefs: (args) => request("GET", "/me/event-sound-prefs", { hasBody: false }, args),
       // PATCH /me/event-sound-prefs — rank: any-builder — PATCH /me/event-sound-prefs
       patchMeEventSoundPrefs: (args) => request("PATCH", "/me/event-sound-prefs", { hasBody: true }, args),
+      // PATCH /me/handle — rank: any-builder — PATCH /me/handle
+      patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/docs/api/openapi.json

@@ -6575,6 +6575,55 @@
         ]
       }
     },
+    "/me/handle": {
+      "patch": {
+        "operationId": "patch_me_handle",
+        "tags": [
+          "me"
+        ],
+        "summary": "PATCH /me/handle",
+        "description": "rename the caller's OWN handle (own data, keyed on the authenticated github_id). Rules live in setAccountHandle: canonical form, reserved words refused, one rename per window, previous handle kept for the 301 window. Upsert-first (the setAccountHideStats precedent) so a hub builder who never federated can still claim a handle — never demotes consent.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/profile.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchMeHandleRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchMeHandleResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/me/interaction": {
       "get": {
         "operationId": "get_me_interaction",
@@ -12942,11 +12991,13 @@
             "type": "boolean"
           },
           "profile_state": {},
+          "handle": {},
           "cross_project": {}
         },
         "required": [
           "hide_stats",
           "profile_state",
+          "handle",
           "cross_project"
         ]
       },
@@ -13984,6 +14035,31 @@
           "events"
         ]
       },
+      "PatchMeHandleRequest": {
+        "type": "object",
+        "properties": {
+          "handle": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39
+          }
+        },
+        "required": [
+          "handle"
+        ],
+        "additionalProperties": false
+      },
+      "PatchMeHandleResponse": {
+        "type": "object",
+        "properties": {
+          "handle": {},
+          "previous_handle": {}
+        },
+        "required": [
+          "handle",
+          "previous_handle"
+        ]
+      },
       "PatchMeSkillPrefsResponse": {
         "type": "object",
         "properties": {
@@ -17222,9 +17298,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 273,
-  "x-schema-count": 306,
+  "x-endpoint-count": 274,
+  "x-schema-count": 308,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 207,
+  "x-response-schemas": 208,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 273 endpoints across 45 route files.
+> **Generated from the live route files** — the route file is authoritative. 274 endpoints across 45 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -282,7 +282,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
 | POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
 
-## `me` (23)
+## `me` (24)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -296,6 +296,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | PATCH | `/api/bongos/me/display-name` | `any-builder` | _undocumented_ | PATCH the display name. |
 | GET | `/api/bongos/me/event-sound-prefs` | `any-builder` | — | Per-builder per-event sound variant selection (task 582, migration 164). |
 | PATCH | `/api/bongos/me/event-sound-prefs` | `any-builder` | _undocumented_ | PATCH a partial set of event sound overrides. |
+| PATCH | `/api/bongos/me/handle` | `any-builder` | `handle` | rename the caller's OWN handle (own data, keyed on the authenticated github_id). |
 | GET | `/api/bongos/me/interaction` | `any-builder` | — | Per-builder INTERACTION PROFILE (task 2010, shares the behavior_prefs jsonb / migration 119). |
 | PATCH | `/api/bongos/me/interaction` | `any-builder` | _undocumented_ | PATCH the interaction profile. |
 | GET | `/api/bongos/me/model-allocation` | `any-builder` | — |  |

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -422,6 +422,8 @@ function createClient(opts = {}) {
       getMeEventSoundPrefs: (args) => request("GET", "/me/event-sound-prefs", { hasBody: false }, args),
       // PATCH /me/event-sound-prefs — rank: any-builder — PATCH /me/event-sound-prefs
       patchMeEventSoundPrefs: (args) => request("PATCH", "/me/event-sound-prefs", { hasBody: true }, args),
+      // PATCH /me/handle — rank: any-builder — PATCH /me/handle
+      patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/modules/platform-identity/migrations/platform_identity_008_handle.sql

@@ -0,0 +1,70 @@
+-- platform_identity_008_handle.sql — the builder handle (P01, task 1002797 /
+-- goal 1000045; profile-page spec Decision 3, ratified ADR 0171 D8).
+--
+-- The canonical profile URL must not hang on github_login: a login is mutable,
+-- so every GitHub rename would silently 404 the builder's shared links. The
+-- handle is presentation only — github_id stays the join key everywhere.
+--
+--   handle            — unique case-insensitively; seeded from github_login.
+--   previous_handle   — the single-slot 301 window: kept on rename until the
+--                       next rename. R05's resolver 301s it to the current
+--                       handle (an exact current-handle match always wins).
+--   handle_changed_at — set on RENAME only, never on seed; the low rate limit
+--                       reads it (one rename per window — setAccountHandle).
+--
+-- Seeding walks accounts oldest-first with exactly the go-forward JS algorithm
+-- (ensureHandle in platform-identity.js): lowercase the login, strip anything
+-- outside [a-z0-9-], trim hyphens; empty → builder-<github_id>; reserved or
+-- taken → numeric suffix -2, -3, … . Sequential plpgsql on purpose: a set-based
+-- ROW_NUMBER pass can manufacture collisions against its own suffixes (a
+-- literal foo-2 login vs foo's second seed), and a failed prod migration costs
+-- more than a slow loop over a small table. The reserved list below mirrors
+-- RESERVED_HANDLES in platform-identity.js — keep them in lockstep.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent: the
+-- handle IS NULL guard makes a re-run a no-op.
+
+BEGIN;
+
+ALTER TABLE platform_identity_accounts
+  ADD COLUMN IF NOT EXISTS handle text,
+  ADD COLUMN IF NOT EXISTS previous_handle text,
+  ADD COLUMN IF NOT EXISTS handle_changed_at timestamptz;
+
+CREATE UNIQUE INDEX IF NOT EXISTS platform_identity_accounts_handle_uniq
+  ON platform_identity_accounts (lower(handle)) WHERE handle IS NOT NULL;
+
+-- The 301-window lookup path (R05 resolves previous handles too).
+CREATE INDEX IF NOT EXISTS platform_identity_accounts_prev_handle_idx
+  ON platform_identity_accounts (lower(previous_handle)) WHERE previous_handle IS NOT NULL;
+
+DO $$
+DECLARE
+  r RECORD;
+  base text;
+  cand text;
+  n int;
+BEGIN
+  FOR r IN
+    SELECT github_id, github_login
+      FROM platform_identity_accounts
+     WHERE handle IS NULL
+     ORDER BY created_at, id
+  LOOP
+    base := trim(both '-' from regexp_replace(lower(coalesce(r.github_login, '')), '[^a-z0-9-]', '', 'g'));
+    IF base = '' THEN
+      base := 'builder-' || r.github_id;
+    END IF;
+    cand := base;
+    n := 1;
+    WHILE cand IN ('me', 'new', 'edit', 'settings', 'admin', 'api', 'u')
+       OR EXISTS (SELECT 1 FROM platform_identity_accounts WHERE lower(handle) = lower(cand))
+    LOOP
+      n := n + 1;
+      cand := base || '-' || n;
+    END LOOP;
+    UPDATE platform_identity_accounts SET handle = cand WHERE github_id = r.github_id;
+  END LOOP;
+END $$;
+
+COMMIT;

package/modules/platform-identity/platform-identity.js

@@ -117,10 +117,13 @@ async function upsertAccount({ githubId, githubLogin, displayName, avatarUrl, ac
        avatar_url   = EXCLUDED.avatar_url,
        profile_state = CASE WHEN $5::boolean THEN 'active' ELSE platform_identity_accounts.profile_state END,
        updated_at   = now()
-     RETURNING id, github_id, github_login, display_name, avatar_url, profile_state`,
+     RETURNING id, github_id, github_login, display_name, avatar_url, profile_state, handle`,
     [githubId, githubLogin, displayName ?? null, avatarUrl ?? null, !!activate],
   );
-  return rows[0];
+  const row = rows[0];
+  // Seed the handle on first sight (spec Decision 3); a no-op once set.
+  if (row && !row.handle) row.handle = await ensureHandle({ githubId, githubLogin }, { pool });
+  return row;
 }
 
 // Resolve the platform account for a github_login (for invitations by handle). A
@@ -138,7 +141,8 @@ async function getAccountByLogin(githubLogin, { pool = defaultPool } = {}) {
 
 async function getAccount(githubId, { pool = defaultPool } = {}) {
   const { rows } = await pool.query(
-    `SELECT id, github_id, github_login, display_name, avatar_url, profile_state, hide_stats, created_at, updated_at
+    `SELECT id, github_id, github_login, display_name, avatar_url, profile_state, hide_stats,
+            handle, previous_handle, handle_changed_at, created_at, updated_at
        FROM platform_identity_accounts WHERE github_id = $1`,
     [githubId],
   );
@@ -615,10 +619,133 @@ async function setAccountHideStats({ githubId, githubLogin, displayName, avatarU
      ON CONFLICT (github_id) DO UPDATE SET
        hide_stats = EXCLUDED.hide_stats,
        updated_at = now()
-     RETURNING github_id, github_login, profile_state, hide_stats`,
+     RETURNING github_id, github_login, profile_state, hide_stats, handle`,
     [githubId, githubLogin, displayName ?? null, avatarUrl ?? null, !!hide],
   );
-  return rows[0];
+  const row = rows[0];
+  // This upsert can CREATE the account row (hide-before-federating) — seed the
+  // handle then, same as upsertAccount.
+  if (row && !row.handle) row.handle = await ensureHandle({ githubId, githubLogin }, { pool });
+  return row;
+}
+
+// -------------------------------------------------------------------------
+// Builder handle (P01, task 1002797 — profile-page spec Decision 3, ADR 0171 D8)
+// -------------------------------------------------------------------------
+//
+// The canonical profile URL key (cloudbongos.com/u/<handle>). github_id stays
+// the join key everywhere — the handle is presentation only, unique
+// case-insensitively, seeded from github_login (which is mutable and therefore
+// unfit to hang a URL on).
+
+// Route words the /u namespace uses (or will) — a handle may never shadow them.
+// Mirrored by the seeding list in migrations/platform_identity_008_handle.sql;
+// keep the two in lockstep.
+const RESERVED_HANDLES = ['me', 'new', 'edit', 'settings', 'admin', 'api', 'u'];
+
+// One rename per window — low by design: a handle is a shared URL, and churning
+// it breaks links faster than the single-slot 301 window can cover.
+const HANDLE_RENAME_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Canonical form: lowercase, 1–39 chars of [a-z0-9-], no leading/trailing
+// hyphen (github_login's charset, lowercased). Returns the normalized handle,
+// or null when the input can't be one.
+function normalizeHandle(raw) {
+  if (typeof raw !== 'string') return null;
+  const h = raw.trim().toLowerCase();
+  return /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/.test(h) ? h : null;
+}
+
+function isReservedHandle(handle) {
+  return RESERVED_HANDLES.includes(handle);
+}
+
+// The seed base for an account: its login squeezed into the handle charset; a
+// login that contributes nothing falls back to builder-<github_id>.
+function handleSeedBase({ githubId, githubLogin }) {
+  const squeezed = String(githubLogin || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/^-+|-+$/g, '');
+  return normalizeHandle(squeezed) || `builder-${githubId}`;
+}
+
+// Seed the handle for an account that has none (new accounts at upsert; legacy
+// rows were seeded by migration 008 with the same algorithm). First free of
+// base, base-2, base-3, … wins; reserved words are never handed out bare. The
+// unique index is the arbiter — losing a race just moves to the next suffix,
+// and a concurrent seeder winning the row (handle no longer NULL) ends the loop.
+async function ensureHandle({ githubId, githubLogin }, { pool = defaultPool } = {}) {
+  if (!isNumericGithubId(githubId)) return null;
+  const base = handleSeedBase({ githubId, githubLogin });
+  let cand = isReservedHandle(base) ? `${base}-2` : base;
+  let next = isReservedHandle(base) ? 3 : 2;
+  for (let tries = 0; tries < 50; tries++) {
+    try {
+      const { rows, rowCount } = await pool.query(
+        `UPDATE platform_identity_accounts
+            SET handle = $2, updated_at = now()
+          WHERE github_id = $1 AND handle IS NULL
+          RETURNING handle`,
+        [githubId, cand],
+      );
+      if (rowCount === 0) break; // seeded concurrently (or no row) — read below
+      return rows[0].handle;
+    } catch (err) {
+      if (err && err.code === '23505') { cand = `${base}-${next++}`; continue; }
+      throw err;
+    }
+  }
+  const acct = await getAccount(githubId, { pool });
+  return acct ? acct.handle : null;
+}
+
+// The rename path (own-scoped; callers key by the AUTHENTICATED github_id).
+// Canonical form only, reserved words refused, one rename per
+// HANDLE_RENAME_WINDOW_MS, uniqueness arbitrated by the index (23505 → taken).
+// On success the old handle drops into previous_handle — the single-slot 301
+// window R05 resolves — and handle_changed_at starts the rate-limit clock
+// (seeding never sets it, so the first rename is always free). Renaming to the
+// current handle is a no-op that burns nothing. Returns { handle,
+// previous_handle } or { error: 'invalid_handle' | 'reserved_handle' |
+// 'no_account' | 'rate_limited' (+ retry_at) | 'handle_taken' }.
+async function setAccountHandle({ githubId, handle }, { pool = defaultPool } = {}) {
+  if (!isNumericGithubId(githubId)) return { error: 'no_account' };
+  const norm = normalizeHandle(handle);
+  if (!norm) return { error: 'invalid_handle' };
+  if (isReservedHandle(norm)) return { error: 'reserved_handle' };
+  const acct = await getAccount(githubId, { pool });
+  if (!acct) return { error: 'no_account' };
+  if (acct.handle === norm) return { handle: acct.handle, previous_handle: acct.previous_handle || null };
+  const rateLimited = (a) => ({
+    error: 'rate_limited',
+    retry_at: new Date(new Date(a.handle_changed_at).getTime() + HANDLE_RENAME_WINDOW_MS).toISOString(),
+  });
+  const changedAt = acct.handle_changed_at ? new Date(acct.handle_changed_at).getTime() : 0;
+  if (changedAt && Date.now() - changedAt < HANDLE_RENAME_WINDOW_MS) return rateLimited(acct);
+  try {
+    // The window is re-checked IN the UPDATE so the read above can't race a
+    // concurrent rename past the rate limit — the DB arbitrates, exactly as the
+    // unique index arbitrates collisions.
+    const { rows, rowCount } = await pool.query(
+      `UPDATE platform_identity_accounts
+          SET previous_handle = handle, handle = $2, handle_changed_at = now(), updated_at = now()
+        WHERE github_id = $1
+          AND (handle_changed_at IS NULL
+               OR handle_changed_at <= now() - ($3::bigint * interval '1 millisecond'))
+        RETURNING handle, previous_handle`,
+      [githubId, norm, HANDLE_RENAME_WINDOW_MS],
+    );
+    if (rowCount) return rows[0];
+    // 0 rows: the account vanished, or a concurrent rename consumed the window
+    // between our read and this write — re-read to answer honestly.
+    const fresh = await getAccount(githubId, { pool });
+    if (!fresh) return { error: 'no_account' };
+    return fresh.handle_changed_at ? rateLimited(fresh) : { error: 'no_account' };
+  } catch (err) {
+    if (err && err.code === '23505') return { error: 'handle_taken' };
+    throw err;
+  }
 }
 
 // -------------------------------------------------------------------------
@@ -721,6 +848,14 @@ module.exports = {
   getPublicProfileExtras,
   getOwnProfileExtras,
   setAccountHideStats,
+  // builder handle (P01)
+  RESERVED_HANDLES,
+  HANDLE_RENAME_WINDOW_MS,
+  normalizeHandle,
+  isReservedHandle,
+  handleSeedBase,
+  ensureHandle,
+  setAccountHandle,
   // codes
   mintAuthCode,
   redeemAuthCode,

package/modules/platform-identity/routes/profile.js

@@ -13,6 +13,9 @@
 //                             /scouting): enforcement lives in the module's read
 //                             functions (D2) and the hub profile response is
 //                             no-store (D5), so there is no cache to outwait.
+//   PATCH /me/handle        — rename the caller's own handle (P01, task 1002797;
+//                             spec Decision 3). Low rate limit, previous handle
+//                             kept for the 301 window.
 //
 // Reaches core only through the doorway (ADR 0083).
 'use strict';
@@ -32,7 +35,7 @@ module.exports = function profileRoutes() {
       // Core builders include system:* principals whose github_id is not numeric;
       // they have no platform identity — answer the empty shape, not a 500.
       if (!pi.isNumericGithubId(req.builder.github_id)) {
-        return res.json({ hide_stats: false, profile_state: null, cross_project: null });
+        return res.json({ hide_stats: false, profile_state: null, handle: null, cross_project: null });
       }
       const [acct, extras] = await Promise.all([
         pi.getAccount(req.builder.github_id, { pool }),
@@ -41,6 +44,7 @@ module.exports = function profileRoutes() {
       res.json({
         hide_stats: !!(acct && acct.hide_stats),
         profile_state: acct ? acct.profile_state : null,
+        handle: (acct && acct.handle) || null,
         cross_project: extras,
       });
     } catch (err) {
@@ -73,5 +77,47 @@ module.exports = function profileRoutes() {
     }
   });
 
+  // rank: any-builder — rename the caller's OWN handle (own data, keyed on the
+  // authenticated github_id). Rules live in setAccountHandle: canonical form,
+  // reserved words refused, one rename per window, previous handle kept for the
+  // 301 window. Upsert-first (the setAccountHideStats precedent) so a hub
+  // builder who never federated can still claim a handle — never demotes consent.
+  router.patch('/me/handle', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      handle: { required: true, type: 'string', minLength: 1, maxLength: 39 },
+    })) return;
+    try {
+      if (!pi.isNumericGithubId(req.builder.github_id)) {
+        return res.fail('no_platform_identity', 400);
+      }
+      await pi.upsertAccount({
+        githubId: req.builder.github_id,
+        githubLogin: req.builder.github_login,
+        displayName: req.builder.display_name,
+        avatarUrl: req.builder.avatar_url,
+      }, { pool });
+      const out = await pi.setAccountHandle({ githubId: req.builder.github_id, handle: req.body.handle }, { pool });
+      if (out.error === 'invalid_handle') {
+        return res.fail('invalid_handle', { status: 400, message: 'a handle is 1–39 characters of a–z, 0–9, and hyphens (not at the ends)' });
+      }
+      if (out.error === 'reserved_handle') {
+        return res.fail('reserved_handle', { status: 400, message: 'that handle is a reserved word' });
+      }
+      if (out.error === 'handle_taken') {
+        return res.fail('handle_taken', { status: 409, message: 'that handle is already in use' });
+      }
+      if (out.error === 'rate_limited') {
+        return res.fail('handle_rate_limited', { status: 429, message: `handles change at most once per ${Math.round(pi.HANDLE_RENAME_WINDOW_MS / 86400000)} days — try again after ${out.retry_at}` });
+      }
+      if (out.error) {
+        return res.fail('handle_write_failed', { status: 500, message: 'internal error' });
+      }
+      res.json({ handle: out.handle, previous_handle: out.previous_handle || null });
+    } catch (err) {
+      console.error('[platform-identity] PATCH /me/handle', err);
+      res.fail('handle_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };

package/modules/platform-identity/tests/platform-identity.mjs

@@ -141,7 +141,9 @@ await ta('upsertAccount upserts on github_id and returns the row (default: NOT a
 });
 
 await ta('upsertAccount consent upgrade is one-way (ADR 0171 D3): activate flips to active, default preserves the stored state', async () => {
-  const pool = mockPool([{ rows: [{ id: '1' }] }, { rows: [{ id: '1' }] }]);
+  // handle present on the returned rows → the P01 seeding hook stays quiet, so
+  // the two upserts are the only two calls.
+  const pool = mockPool([{ rows: [{ id: '1', handle: 'octocat' }] }, { rows: [{ id: '1', handle: 'octocat' }] }]);
   await P.upsertAccount({ githubId: 42, githubLogin: 'octocat', activate: true }, { pool });
   await P.upsertAccount({ githubId: 42, githubLogin: 'octocat' }, { pool });
   const sql = pool.calls[0].text;
@@ -581,5 +583,141 @@ await ta('sweepExpiredCodes deletes expired + long-consumed rows', async () => {
   assert.match(pool.calls[0].text, /expires_at < now\(\)/);
 });
 
+console.log('\nbuilder handle (P01, task 1002797):');
+
+// A pool that throws queued errors (code-carrying) or returns queued responses —
+// for the unique-violation retry paths mockPool can't express.
+function throwingPool(script) {
+  const calls = [];
+  let i = 0;
+  return {
+    calls,
+    query: async (text, params) => {
+      calls.push({ text: String(text), params: params || [] });
+      const step = script[i++] || { rows: [], rowCount: 0 };
+      if (step.throwCode) { const e = new Error(`pg error ${step.throwCode}`); e.code = step.throwCode; throw e; }
+      return step;
+    },
+  };
+}
+
+t('normalizeHandle: canonical form only', () => {
+  assert.equal(P.normalizeHandle(' Jaxri '), 'jaxri');
+  assert.equal(P.normalizeHandle('a'), 'a');
+  assert.equal(P.normalizeHandle('a-b-1'), 'a-b-1');
+  assert.equal(P.normalizeHandle('has_underscore'), null);
+  assert.equal(P.normalizeHandle('-lead'), null);
+  assert.equal(P.normalizeHandle('trail-'), null);
+  assert.equal(P.normalizeHandle('x'.repeat(39)), 'x'.repeat(39));
+  assert.equal(P.normalizeHandle('x'.repeat(40)), null);
+  assert.equal(P.normalizeHandle(''), null);
+  assert.equal(P.normalizeHandle(42), null);
+});
+
+t('the reserved list is exactly the spec Decision 3 set', () => {
+  assert.deepEqual([...P.RESERVED_HANDLES].sort(), ['admin', 'api', 'edit', 'me', 'new', 'settings', 'u'].sort());
+  assert.equal(P.isReservedHandle('me'), true);
+  assert.equal(P.isReservedHandle('jaxri'), false);
+});
+
+t('handleSeedBase squeezes the login; contributes-nothing → builder-<id>', () => {
+  assert.equal(P.handleSeedBase({ githubId: 7, githubLogin: 'Jax_Ri!' }), 'jaxri');
+  assert.equal(P.handleSeedBase({ githubId: 7, githubLogin: '-Wrapped-' }), 'wrapped');
+  assert.equal(P.handleSeedBase({ githubId: 7, githubLogin: '___' }), 'builder-7');
+  assert.equal(P.handleSeedBase({ githubId: 7, githubLogin: null }), 'builder-7');
+});
+
+await ta('ensureHandle takes the bare base when free', async () => {
+  const pool = throwingPool([{ rows: [{ handle: 'jaxri' }], rowCount: 1 }]);
+  const h = await P.ensureHandle({ githubId: 7, githubLogin: 'jaxri' }, { pool });
+  assert.equal(h, 'jaxri');
+  assert.match(pool.calls[0].text, /SET handle = \$2/);
+  assert.match(pool.calls[0].text, /handle IS NULL/, 'seed must never clobber an existing handle');
+  assert.equal(pool.calls[0].params[1], 'jaxri');
+});
+
+await ta('ensureHandle dedupes a collision with the numeric suffix', async () => {
+  const pool = throwingPool([{ throwCode: '23505' }, { rows: [{ handle: 'jaxri-2' }], rowCount: 1 }]);
+  const h = await P.ensureHandle({ githubId: 7, githubLogin: 'jaxri' }, { pool });
+  assert.equal(h, 'jaxri-2');
+  assert.equal(pool.calls[1].params[1], 'jaxri-2');
+});
+
+await ta('ensureHandle never hands out a reserved word bare', async () => {
+  const pool = throwingPool([{ rows: [{ handle: 'admin-2' }], rowCount: 1 }]);
+  const h = await P.ensureHandle({ githubId: 7, githubLogin: 'admin' }, { pool });
+  assert.equal(h, 'admin-2');
+  assert.equal(pool.calls[0].params[1], 'admin-2', 'a reserved base starts at -2');
+});
+
+await ta('ensureHandle: non-numeric github_id (system:*) → null, no query', async () => {
+  const pool = throwingPool([]);
+  assert.equal(await P.ensureHandle({ githubId: 'system:bfg', githubLogin: 'bfg' }, { pool }), null);
+  assert.equal(pool.calls.length, 0);
+});
+
+await ta('setAccountHandle refuses invalid + reserved before touching the DB', async () => {
+  const pool = throwingPool([]);
+  assert.deepEqual(await P.setAccountHandle({ githubId: 7, handle: 'bad_handle' }, { pool }), { error: 'invalid_handle' });
+  assert.deepEqual(await P.setAccountHandle({ githubId: 7, handle: 'settings' }, { pool }), { error: 'reserved_handle' });
+  assert.equal(pool.calls.length, 0);
+});
+
+await ta('setAccountHandle renames: previous handle kept, clock started', async () => {
+  const acct = { github_id: 7, handle: 'old', previous_handle: null, handle_changed_at: null };
+  const pool = throwingPool([
+    { rows: [acct], rowCount: 1 },
+    { rows: [{ handle: 'newname', previous_handle: 'old' }], rowCount: 1 },
+  ]);
+  const out = await P.setAccountHandle({ githubId: 7, handle: 'NewName' }, { pool });
+  assert.deepEqual(out, { handle: 'newname', previous_handle: 'old' });
+  const upd = pool.calls[1];
+  assert.match(upd.text, /previous_handle = handle/, 'the old handle drops into the 301 slot');
+  assert.match(upd.text, /handle_changed_at = now\(\)/);
+  assert.match(upd.text, /handle_changed_at IS NULL\s+OR handle_changed_at <= now\(\)/,
+    'the window is re-checked IN the UPDATE — the rate limit must not be check-then-write');
+  assert.equal(upd.params[1], 'newname', 'stored lowercased');
+  assert.equal(upd.params[2], P.HANDLE_RENAME_WINDOW_MS);
+});
+
+await ta('setAccountHandle: losing the window race → rate_limited, not a silent write', async () => {
+  // The read sees a free window, but the guarded UPDATE matches 0 rows (a
+  // concurrent rename consumed it) — the re-read answers rate_limited.
+  const before = { github_id: 7, handle: 'old', previous_handle: null, handle_changed_at: null };
+  const after = { ...before, handle: 'stolen', handle_changed_at: new Date().toISOString() };
+  const pool = throwingPool([
+    { rows: [before], rowCount: 1 },
+    { rows: [], rowCount: 0 },
+    { rows: [after], rowCount: 1 },
+  ]);
+  const out = await P.setAccountHandle({ githubId: 7, handle: 'newname' }, { pool });
+  assert.equal(out.error, 'rate_limited');
+  assert.ok(out.retry_at);
+});
+
+await ta('setAccountHandle: a rename inside the window is rate-limited', async () => {
+  const acct = { github_id: 7, handle: 'old', previous_handle: null, handle_changed_at: new Date().toISOString() };
+  const pool = throwingPool([{ rows: [acct], rowCount: 1 }]);
+  const out = await P.setAccountHandle({ githubId: 7, handle: 'newname' }, { pool });
+  assert.equal(out.error, 'rate_limited');
+  assert.ok(out.retry_at, 'carries when the window reopens');
+  assert.equal(pool.calls.length, 1, 'no UPDATE fired');
+});
+
+await ta('setAccountHandle: renaming to the current handle is a free no-op', async () => {
+  const acct = { github_id: 7, handle: 'same', previous_handle: 'older', handle_changed_at: new Date().toISOString() };
+  const pool = throwingPool([{ rows: [acct], rowCount: 1 }]);
+  const out = await P.setAccountHandle({ githubId: 7, handle: 'Same' }, { pool });
+  assert.deepEqual(out, { handle: 'same', previous_handle: 'older' });
+  assert.equal(pool.calls.length, 1, 'read only — no clock burn');
+});
+
+await ta('setAccountHandle: a taken handle → handle_taken', async () => {
+  const acct = { github_id: 7, handle: 'old', previous_handle: null, handle_changed_at: null };
+  const pool = throwingPool([{ rows: [acct], rowCount: 1 }, { throwCode: '23505' }]);
+  const out = await P.setAccountHandle({ githubId: 7, handle: 'wanted' }, { pool });
+  assert.deepEqual(out, { error: 'handle_taken' });
+});
+
 console.log(`\nplatform-identity: ${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.171",
+  "version": "1.19.172",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.171",
+      "version": "1.19.172",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.171",
+  "version": "1.19.172",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -769,8 +769,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.169 with no explicit bump. run 31965483417. (task 1002620)
 //   1.19.171 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.170 with no explicit bump. run 31967255167. (task 1002620)
+//   1.19.172 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.171 with no explicit bump. run 31968188738. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.171'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.172'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/handle_machinery.mjs

@@ -0,0 +1,115 @@
+// tests/handle_machinery.mjs — P01, task 1002797 (goal 1000045; real DB).
+//
+// Proves migration 008's seeding + the go-forward handle machinery against real
+// SQL (the plpgsql seeding loop and the partial unique index cannot run on
+// pg-mem — the tests/profile_rollup_consent.mjs precedent):
+//   1. seeding dedupes case-colliding logins oldest-first with -2, -3 suffixes;
+//      reserved logins never seed bare; an unusable login → builder-<github_id>
+//   2. upsertAccount seeds a NEW account's handle, suffixing past taken ones
+//   3. ensureHandle never clobbers a seeded handle
+//   4. setAccountHandle: rename keeps the old handle in previous_handle and
+//      starts the rate-limit clock; a second rename inside the window is
+//      refused; an expired window allows; a case-insensitive collision → taken;
+//      reserved words are refused
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set so the default DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/handle_machinery.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const pi = require('../modules/platform-identity/platform-identity.js');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIG_DIR = join(here, '..', 'modules', 'platform-identity', 'migrations');
+const migrationSql = (f) => readFileSync(join(MIG_DIR, f), 'utf8');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`handle_machinery.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+// High-numbered fixture ids so a shared DB can never collide with real data.
+const TWIN_A = 9002797001, TWIN_B = 9002797002, RESV = 9002797003, JUNK = 9002797004, FRESH = 9002797005;
+const ALL_IDS = [TWIN_A, TWIN_B, RESV, JUNK, FRESH];
+
+const q = (sql, params) => pool.query(sql, params);
+async function cleanup() {
+  await q(`DELETE FROM platform_identity_accounts WHERE github_id = ANY($1::bigint[])`, [ALL_IDS]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+const handleOf = async (id) => (await pi.getAccount(id, { pool })).handle;
+
+try {
+  // The module's actual migrations (idempotent). 008 runs AFTER the fixture
+  // rows exist so its seeding loop has NULL handles to seed — exactly the
+  // legacy-rows-at-deploy shape.
+  await q(migrationSql('platform_identity_001_tables.sql'));
+  await q(migrationSql('platform_identity_007_profile_consent.sql'));
+  // On a DB where 008 already ran the columns exist and the raw inserts below
+  // simply land with handle NULL — the re-run seeds only those. Idempotence is
+  // part of what this proves.
+  await q(migrationSql('platform_identity_008_handle.sql')).catch(() => {});
+  await cleanup();
+
+  await q(
+    `INSERT INTO platform_identity_accounts (github_id, github_login, created_at)
+     VALUES ($1, 'P01SeedTwin', now() - interval '10 minutes'),
+            ($2, 'p01seedtwin', now() - interval '9 minutes'),
+            ($3, 'admin',       now() - interval '8 minutes'),
+            ($4, '___',         now() - interval '7 minutes')`,
+    [TWIN_A, TWIN_B, RESV, JUNK],
+  );
+  await q(migrationSql('platform_identity_008_handle.sql'));
+
+  // --- 1. seeding ----------------------------------------------------------
+  ok((await handleOf(TWIN_A)) === 'p01seedtwin', 'oldest of a case-colliding pair seeds the bare handle');
+  ok((await handleOf(TWIN_B)) === 'p01seedtwin-2', 'the younger twin gets the -2 suffix');
+  ok((await handleOf(RESV)) === 'admin-2', 'a reserved login never seeds bare — suffixed from -2');
+  ok((await handleOf(JUNK)) === `builder-${JUNK}`, 'a login that contributes nothing seeds builder-<github_id>');
+
+  // --- 2. go-forward seeding via upsertAccount ------------------------------
+  const fresh = await pi.upsertAccount({ githubId: FRESH, githubLogin: 'P01SeedTwin' }, { pool });
+  ok(fresh.handle === 'p01seedtwin-3', 'a new account collides past every taken suffix');
+
+  // --- 3. ensureHandle never clobbers ---------------------------------------
+  const again = await pi.ensureHandle({ githubId: FRESH, githubLogin: 'renamed-login' }, { pool });
+  ok(again === 'p01seedtwin-3', 'ensureHandle on a seeded account returns the existing handle untouched');
+
+  // --- 4. renames -----------------------------------------------------------
+  const r1 = await pi.setAccountHandle({ githubId: FRESH, handle: 'P01-Renamed' }, { pool });
+  ok(r1.handle === 'p01-renamed' && r1.previous_handle === 'p01seedtwin-3',
+    'rename lowercases, keeps the old handle in the 301 slot');
+
+  const r2 = await pi.setAccountHandle({ githubId: FRESH, handle: 'p01-again' }, { pool });
+  ok(r2.error === 'rate_limited' && !!r2.retry_at, 'a second rename inside the window is refused with retry_at');
+  ok((await handleOf(FRESH)) === 'p01-renamed', 'the refused rename changed nothing');
+
+  await q(`UPDATE platform_identity_accounts SET handle_changed_at = now() - interval '8 days' WHERE github_id = $1`, [FRESH]);
+  const r3 = await pi.setAccountHandle({ githubId: FRESH, handle: 'p01-again' }, { pool });
+  ok(r3.handle === 'p01-again' && r3.previous_handle === 'p01-renamed', 'an expired window allows the rename; the 301 slot rolls forward');
+
+  await q(`UPDATE platform_identity_accounts SET handle_changed_at = now() - interval '8 days' WHERE github_id = $1`, [FRESH]);
+  const r4 = await pi.setAccountHandle({ githubId: FRESH, handle: 'P01SEEDTWIN' }, { pool });
+  ok(r4.error === 'handle_taken', 'a case-insensitive collision with a live handle is refused');
+
+  const r5 = await pi.setAccountHandle({ githubId: FRESH, handle: 'u' }, { pool });
+  ok(r5.error === 'reserved_handle', 'reserved words are refused on rename');
+
+  console.log(`\nhandle_machinery: ${pass} assertions passed`);
+} finally {
+  await cleanup();
+  await pool.end().catch(() => {});
+}