@bongos/core 1.19.170 → 1.19.172

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.170",
+  "version": "1.19.172",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.170",
+      "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.170",
+  "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/scripts/hall-preview/server.js

@@ -81,6 +81,7 @@ const FIXTURE_FALLBACKS = [
   [/^blockers\/\d+$/, 'blockers__detail'],
   [/^analytics\/builder\/\d+$/, 'analytics__builder'],
   [/^builders\/\d+\/active-claims$/, 'builders__active-claims'],
+  [/^builders\/\d+\/profile$/, 'builders__profile'],
 ];
 
 function loadFixture(name) {

package/src/module-api.js

@@ -767,8 +767,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.168 with no explicit bump. run 31964702865. (task 1002620)
 //   1.19.170 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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.170'; // 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(() => {});
+}