@bongos/core 1.19.171 → 1.19.173

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,187 @@ 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;
+  }
+}
+
+// Resolve a public handle → its account (R05, task 1002281 — the /u/<handle>
+// resolution). Case-insensitive. An exact current-handle match always wins;
+// otherwise the single-slot previous_handle matches and answers a move to the
+// current handle (the 301 window from P01). Only publicly addressable accounts
+// resolve (profile_state = 'active', ADR 0171 D3) — provisional and unknown are
+// the same null (the 404, indistinguishable by design). hide_stats deliberately
+// does NOT gate resolution: hiding removes the rollup, not the page (D2 —
+// addressability and hide are different invariants).
+// Returns null | { moved_to } | { account: { github_id, github_login,
+// display_name, avatar_url, handle, created_at } }.
+async function resolveHandle(handle, { pool = defaultPool } = {}) {
+  const norm = normalizeHandle(handle);
+  if (!norm) return null;
+  const { rows } = await pool.query(
+    `SELECT github_id, github_login, display_name, avatar_url, handle, created_at,
+            (lower(handle) = $1) AS is_current
+       FROM platform_identity_accounts
+      WHERE profile_state = 'active'
+        AND (lower(handle) = $1 OR lower(previous_handle) = $1)
+      ORDER BY (lower(handle) = $1) DESC
+      LIMIT 1`,
+    [norm],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  if (!row.is_current) return { moved_to: row.handle };
+  const { is_current, ...account } = row;
+  return { account };
+}
+
+// The one public read the canonical /u/<handle> page consumes (R05; the page
+// itself is goal 1000048 R14, task 1002365 — exactly one page gets built, this
+// is its read). Whitelist-shaped INSIDE the module: the identity-band fields
+// plus the same cross_project payload the numeric instance profile route serves
+// (null = hidden / none, indistinguishable — D4). profile_state and github_id
+// never cross — a 200 IS the addressability signal, and the join key stays
+// internal.
+async function getPublicProfileByHandle(handle, { pool = defaultPool } = {}) {
+  const hit = await resolveHandle(handle, { pool });
+  if (!hit) return null;
+  if (hit.moved_to) return { moved_to: hit.moved_to };
+  const a = hit.account;
+  return {
+    account: {
+      handle: a.handle,
+      github_login: a.github_login,
+      display_name: a.display_name,
+      avatar_url: a.avatar_url,
+      member_since: a.created_at,
+    },
+    cross_project: await getPublicProfileExtras(a.github_id, { pool }),
+  };
 }
 
 // -------------------------------------------------------------------------
@@ -721,6 +902,16 @@ module.exports = {
   getPublicProfileExtras,
   getOwnProfileExtras,
   setAccountHideStats,
+  // builder handle (P01)
+  RESERVED_HANDLES,
+  HANDLE_RENAME_WINDOW_MS,
+  normalizeHandle,
+  isReservedHandle,
+  handleSeedBase,
+  ensureHandle,
+  setAccountHandle,
+  resolveHandle,
+  getPublicProfileByHandle,
   // 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/routes/public-profile.js

@@ -0,0 +1,49 @@
+// modules/platform-identity/routes/public-profile.js — the public handle-based
+// profile read (R05, task 1002281; profile-page spec Decisions 1/3, ADR 0171 D8).
+//
+//   GET /profiles/:handle — resolve a handle to the public profile payload the
+//   canonical /u/<handle> page consumes (goal 1000048 R14 / task 1002365 builds
+//   the PAGE; this is its read — exactly one page gets built). Answers:
+//     404 — unknown handle, or a provisional account (indistinguishable by
+//           design: fail-closed consent, ADR 0171 D3)
+//     301 — the request named a previous handle inside P01's single-slot
+//           window; Location + body point at the current handle
+//     200 — { account: identity-band fields, cross_project: … | null }
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pi = require('../platform-identity');
+
+const { pool, corsPublicGet } = api;
+
+module.exports = function publicProfileRoutes() {
+  const router = express.Router();
+
+  router.use('/profiles/:handle', corsPublicGet('/profiles/:handle'));
+
+  // rank: public — a handle-addressed public profile. Every field is already
+  // world-readable on the numeric profile route + the leaderboard; the handle is
+  // just the rename-proof address (spec Decision 3). Whitelisting happens inside
+  // the module (getPublicProfileByHandle); no-store because the payload embeds
+  // cross_project and hide must beat the cache (ADR 0171 D5).
+  router.get('/profiles/:handle', async (req, res) => {
+    try {
+      const out = await pi.getPublicProfileByHandle(req.params.handle, { pool });
+      res.set('Cache-Control', 'no-store');
+      if (!out) return res.fail('profile_not_found', 404);
+      if (out.moved_to) {
+        res.set('Location', req.originalUrl.replace(/\/profiles\/[^/?]+/, `/profiles/${encodeURIComponent(out.moved_to)}`));
+        return res.status(301).json({ moved_to: out.moved_to });
+      }
+      res.json({ account: out.account, cross_project: out.cross_project });
+    } catch (err) {
+      console.error('[platform-identity] GET /profiles/:handle', err);
+      res.fail('profile_read_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,194 @@ 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('\nhandle resolution (R05, task 1002281):');
+
+await ta('resolveHandle: active-only, current-beats-previous, lowercased lookup', async () => {
+  const row = { github_id: '7', github_login: 'x', display_name: 'X', avatar_url: null, handle: 'x', created_at: 'T', is_current: true };
+  const pool = mockPool([{ rows: [row], rowCount: 1 }]);
+  const out = await P.resolveHandle('X', { pool });
+  const c = pool.calls[0];
+  assert.match(c.text, /profile_state = 'active'/, 'provisional accounts are not addressable (ADR 0171 D3)');
+  assert.match(c.text, /ORDER BY \(lower\(handle\) = \$1\) DESC/, 'an exact current-handle match always wins over a previous one');
+  assert.doesNotMatch(c.text, /hide_stats/, 'hide gates the rollup, never addressability (D2)');
+  assert.equal(c.params[0], 'x', 'the lookup is lowercased');
+  assert.equal(out.account.handle, 'x');
+  assert.ok(!('is_current' in out.account), 'the SQL flag stays internal');
+});
+
+await ta('resolveHandle: a previous-handle hit answers the move to the current handle', async () => {
+  const row = { github_id: '7', github_login: 'x', display_name: 'X', avatar_url: null, handle: 'newname', created_at: 'T', is_current: false };
+  const pool = mockPool([{ rows: [row], rowCount: 1 }]);
+  assert.deepEqual(await P.resolveHandle('oldname', { pool }), { moved_to: 'newname' });
+});
+
+await ta('resolveHandle: an invalid handle → null without touching the DB', async () => {
+  const pool = mockPool([]);
+  assert.equal(await P.resolveHandle('not a handle!', { pool }), null);
+  assert.equal(await P.resolveHandle('', { pool }), null);
+  assert.equal(pool.calls.length, 0);
+});
+
+await ta('getPublicProfileByHandle: identity-band whitelist — github_id/profile_state never cross', async () => {
+  const row = { github_id: '7', github_login: 'x', display_name: 'X', avatar_url: 'a', handle: 'x', created_at: 'T', is_current: true };
+  const pool = mockPool([
+    { rows: [row], rowCount: 1 },
+    // getPublicProfileExtras' flags read: hidden → the extras stay null and no
+    // rollup query fires.
+    { rows: [{ profile_state: 'active', hide_stats: true }], rowCount: 1 },
+  ]);
+  const out = await P.getPublicProfileByHandle('x', { pool });
+  assert.deepEqual(Object.keys(out.account).sort(), ['avatar_url', 'display_name', 'github_login', 'handle', 'member_since'].sort());
+  assert.equal(out.cross_project, null, 'hidden → null, indistinguishable from none');
+  const text = JSON.stringify(out);
+  assert.doesNotMatch(text, /github_id/, 'the join key stays internal');
+  assert.doesNotMatch(text, /profile_state/, 'a 200 IS the addressability signal');
+  assert.doesNotMatch(text, /hide_stats/);
+});
+
+await ta('getPublicProfileByHandle: unknown → null; moved passes through', async () => {
+  const pool1 = mockPool([{ rows: [], rowCount: 0 }]);
+  assert.equal(await P.getPublicProfileByHandle('ghost', { pool: pool1 }), null);
+  const moved = { github_id: '7', github_login: 'x', display_name: 'X', avatar_url: null, handle: 'now', created_at: 'T', is_current: false };
+  const pool2 = mockPool([{ rows: [moved], rowCount: 1 }]);
+  assert.deepEqual(await P.getPublicProfileByHandle('then', { pool: pool2 }), { moved_to: 'now' });
+});
+
 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.173",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.171",
+      "version": "1.19.173",
       "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.173",
   "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,12 @@ 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)
+//   1.19.173 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.172 with no explicit bump. run 31968656001. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.171'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.173'; // 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');