@volter/twin-clerk 0.1.0

package/dist/src/clerk-capabilities.js

@@ -0,0 +1,1132 @@
+// Clerk capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what the Clerk Backend API actually does — NOT from what this twin has
+// built. This is the honest denominator: most entries start as `todo` and coverage reads
+// LOW until the twin truly reaches 100% of Clerk. `verify()` (required to count as done)
+// is ground truth; `expected: 'done'` only on capabilities we genuinely claim, so a broken
+// one shows as a regression. Grow this toward Clerk's *full* surface every cycle.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { checkCapabilities, uiDataCoupled, verifyBoundary, isInfrastructureError, harnessError } from '@volter/world-tooling';
+import { buildJwks, networklessVerifyToken, signJwt, verifyJwtHs256, verifyJwtWithJwks } from "./clerk-jwt.js";
+import { clearClerkWebhooks, computeSvixSignature, emitClerkEvent, registerClerkWebhook, verifyWebhook } from "./clerk-events.js";
+import { handleClerkTwinRequest } from "./clerk-twin.js";
+import { SECTIONS, CreateUserForm, ImpersonateButton, NestedLines, StatusPill } from "../client/clerk-mirror.js";
+import { flattenClerkValue, statusTone } from "./clerk-mirror-ui.js";
+/** Run a sequence of real Clerk requests against an isolated root; return all responses. */
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'clerk-cap-'));
+    const h = (s) => handleClerkTwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root, ...(s.at ? { occurredAt: s.at } : {}) });
+    try {
+        return await verifyBoundary('clerk.withRoot', () => steps(h));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const ok = (r) => r.status >= 200 && r.status < 300;
+const id = (r) => r.body?.id;
+const field = (r, k) => r.body?.[k];
+// A user with one email — the common fixture.
+const mkUser = (email = 'ada@twin.test') => ({ email_address: [email], first_name: 'Ada', last_name: 'Lovelace' });
+// The mirror's OWN per-section title()/subtitle() row-shaping closures (imported from the
+// client, exported as `SECTIONS`) — used by the UI verifies below to shape fetched rows
+// EXACTLY as the dashboard's row list would, instead of re-implementing the shaping.
+const section = (key) => SECTIONS.find((s) => s.key === key);
+// ── shorthands (mirror the stripe/linear manifests) ──
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const CLERK_CAPABILITIES = [
+    // ── Users ─────────────────────────────────────────────────────────────────────
+    done('clerk.users.create', 'users', 'Users: create with email + name', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        return ok(u) && field(u, 'object') === 'user' && Array.isArray(field(u, 'email_addresses')) && field(u, 'email_addresses')[0].email_address === 'ada@twin.test';
+    })),
+    done('clerk.users.retrieve', 'users', 'Users: retrieve by id', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const g = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        const missing = await h({ m: 'GET', p: '/v1/users/user_nope' });
+        return ok(g) && id(g) === id(u) && missing.status === 404;
+    })),
+    done('clerk.users.list', 'users', 'Users: list (bare array)', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/users', b: mkUser('a@twin.test') });
+        await h({ m: 'POST', p: '/v1/users', b: mkUser('b@twin.test') });
+        const l = await h({ m: 'GET', p: '/v1/users' });
+        return ok(l) && Array.isArray(l.body) && l.body.length === 2;
+    })),
+    done('clerk.users.update', 'users', 'Users: update name + metadata', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const upd = await h({ m: 'PATCH', p: `/v1/users/${id(u)}`, b: { first_name: 'Grace', public_metadata: { plan: 'pro' } } });
+        return ok(upd) && field(upd, 'first_name') === 'Grace' && field(upd, 'public_metadata').plan === 'pro';
+    })),
+    done('clerk.users.delete', 'users', 'Users: delete (then 404 + dropped from list)', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const del = await h({ m: 'DELETE', p: `/v1/users/${id(u)}` });
+        const gone = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        const l = await h({ m: 'GET', p: '/v1/users' });
+        return ok(del) && field(del, 'deleted') === true && gone.status === 404 && l.body.length === 0;
+    })),
+    done('clerk.users.ban', 'users', 'Users: ban / unban', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const banned = await h({ m: 'POST', p: `/v1/users/${id(u)}/ban` });
+        if (!ok(banned) || field(banned, 'banned') !== true)
+            return false;
+        const unbanned = await h({ m: 'POST', p: `/v1/users/${id(u)}/unban` });
+        return ok(unbanned) && field(unbanned, 'banned') === false;
+    })),
+    done('clerk.users.lock', 'users', 'Users: lock / unlock', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const locked = await h({ m: 'POST', p: `/v1/users/${id(u)}/lock` });
+        const unlocked = await h({ m: 'POST', p: `/v1/users/${id(u)}/unlock` });
+        return ok(locked) && field(locked, 'locked') === true && ok(unlocked) && field(unlocked, 'locked') === false;
+    })),
+    done('clerk.users.metadata', 'users', 'Users: merge metadata (PATCH /metadata)', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        await h({ m: 'PATCH', p: `/v1/users/${id(u)}/metadata`, b: { public_metadata: { a: 1 } } });
+        const merged = await h({ m: 'PATCH', p: `/v1/users/${id(u)}/metadata`, b: { public_metadata: { b: 2 } } });
+        const pm = field(merged, 'public_metadata');
+        return ok(merged) && pm.a === 1 && pm.b === 2;
+    })),
+    done('clerk.users.list_filter', 'users', 'Users: list filtered by email_address / username / external_id', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/users', b: { email_address: ['match@twin.test'], username: 'matcher' } });
+        await h({ m: 'POST', p: '/v1/users', b: { email_address: ['other@twin.test'] } });
+        const byEmail = await h({ m: 'GET', p: '/v1/users?email_address=match@twin.test' });
+        const byUser = await h({ m: 'GET', p: '/v1/users?username=matcher' });
+        return ok(byEmail) && byEmail.body.length === 1 && ok(byUser) && byUser.body.length === 1;
+    })),
+    done('clerk.users.validation', 'users', 'Users: rejects empty identifiers + duplicate email', 'api', 'core', () => withRoot(async (h) => {
+        const empty = await h({ m: 'POST', p: '/v1/users', b: {} });
+        await h({ m: 'POST', p: '/v1/users', b: mkUser('dup@twin.test') });
+        const dup = await h({ m: 'POST', p: '/v1/users', b: mkUser('dup@twin.test') });
+        return empty.status === 422 && dup.status === 422;
+    })),
+    done('clerk.users.count', 'users', 'Users: count endpoint', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/users', b: mkUser('c1@twin.test') });
+        await h({ m: 'POST', p: '/v1/users', b: mkUser('c2@twin.test') });
+        const c = await h({ m: 'GET', p: '/v1/users/count' });
+        return ok(c) && field(c, 'total_count') === 2;
+    })),
+    done('clerk.users.search_query', 'users', 'Users: full-text query param across name/email', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/users', b: { email_address: ['grace.hopper@twin.test'], first_name: 'Grace', last_name: 'Hopper' } });
+        await h({ m: 'POST', p: '/v1/users', b: mkUser('someone.else@twin.test') });
+        const byName = await h({ m: 'GET', p: '/v1/users?query=hopper' });
+        const byEmail = await h({ m: 'GET', p: '/v1/users?query=grace.hopper' });
+        const noMatch = await h({ m: 'GET', p: '/v1/users?query=zzz_nobody' });
+        return ok(byName) && byName.body.length === 1 && byEmail.body.length === 1 && noMatch.body.length === 0;
+    })),
+    done('clerk.users.oauth_accounts', 'users', 'Users: external OAuth account management', 'api', 'common', () => withRoot(async (h) => {
+        // seed a user that already has a linked external (OAuth) account
+        const u = await h({ m: 'POST', p: '/v1/users', b: { ...mkUser(), external_accounts: [{ id: 'eac_twin_1', object: 'external_account', provider: 'oauth_google', email_address: 'ada@twin.test', approved_scopes: ['email'], _access_token: 'ya29.token' }] } });
+        const tokens = await h({ m: 'GET', p: `/v1/users/${id(u)}/oauth_access_tokens/google` });
+        const tokenList = field(tokens, 'data');
+        if (!ok(tokens) || tokenList.length !== 1 || tokenList[0].token !== 'ya29.token')
+            return false;
+        const del = await h({ m: 'DELETE', p: `/v1/users/${id(u)}/external_accounts/eac_twin_1` });
+        const after = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        const missing = await h({ m: 'DELETE', p: `/v1/users/${id(u)}/external_accounts/eac_nope` });
+        return ok(del) && field(del, 'deleted') === true && field(after, 'external_accounts').length === 0 && missing.status === 404;
+    })),
+    done('clerk.users.totp', 'users', 'Users: TOTP / 2FA secret + backup codes', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const totp = await h({ m: 'POST', p: `/v1/users/${id(u)}/totp` });
+        const secret = field(totp, 'secret');
+        // a real base32 secret + a valid otpauth uri carrying it; the user flips totp_enabled
+        if (!ok(totp) || field(totp, 'object') !== 'totp' || !/^[A-Z2-7]+$/.test(secret) || !String(field(totp, 'uri')).includes(`secret=${secret}`))
+            return false;
+        const after = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        if (field(after, 'totp_enabled') !== true || field(after, 'two_factor_enabled') !== true)
+            return false;
+        const codes = await h({ m: 'POST', p: `/v1/users/${id(u)}/backup_codes` });
+        const list = field(codes, 'codes');
+        if (!ok(codes) || !Array.isArray(list) || list.length !== 10)
+            return false;
+        const del = await h({ m: 'DELETE', p: `/v1/users/${id(u)}/totp` });
+        const afterDel = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        const missing = await h({ m: 'POST', p: '/v1/users/user_nope/totp' });
+        return ok(del) && field(del, 'deleted') === true && field(afterDel, 'totp_enabled') === false && missing.status === 404;
+    })),
+    done('clerk.users.password', 'users', 'Users: set / verify password (real scrypt hash, never plaintext)', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: { ...mkUser(), password: 's3cret-pw' } });
+        if (!ok(u) || field(u, 'password_enabled') !== true || 'password' in u.body)
+            return false;
+        const good = await h({ m: 'POST', p: `/v1/users/${id(u)}/verify_password`, b: { password: 's3cret-pw' } });
+        const bad = await h({ m: 'POST', p: `/v1/users/${id(u)}/verify_password`, b: { password: 'wrong' } });
+        // a user without a password rejects verification too
+        const u2 = await h({ m: 'POST', p: '/v1/users', b: mkUser('nopass@twin.test') });
+        const noPw = await h({ m: 'POST', p: `/v1/users/${id(u2)}/verify_password`, b: { password: 'x' } });
+        return ok(good) && field(good, 'verified') === true && bad.status === 422 && noPw.status === 422;
+    })),
+    done('clerk.users.email_verification', 'users', 'Users: add + verify email address flow', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const add = await h({ m: 'POST', p: '/v1/email_addresses', b: { user_id: id(u), email_address: 'second@twin.test' } });
+        if (!ok(add) || field(add, 'object') !== 'email_address' || field(add, 'verification') !== null)
+            return false;
+        const eaid = id(add);
+        const ver = await h({ m: 'PATCH', p: `/v1/email_addresses/${eaid}`, b: { verified: true } });
+        const get = await h({ m: 'GET', p: `/v1/email_addresses/${eaid}` });
+        const del = await h({ m: 'DELETE', p: `/v1/email_addresses/${eaid}` });
+        const gone = await h({ m: 'GET', p: `/v1/email_addresses/${eaid}` });
+        return ok(ver) && field(ver, 'verification').status === 'verified' && field(get, 'verification').status === 'verified' && ok(del) && gone.status === 404;
+    })),
+    done('clerk.users.phone_verification', 'users', 'Users: add + verify phone number flow', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const add = await h({ m: 'POST', p: '/v1/phone_numbers', b: { user_id: id(u), phone_number: '+15551230000' } });
+        if (!ok(add) || field(add, 'object') !== 'phone_number')
+            return false;
+        const ver = await h({ m: 'PATCH', p: `/v1/phone_numbers/${id(add)}`, b: { verified: true } });
+        const onUser = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        const phones = field(onUser, 'phone_numbers');
+        return ok(ver) && field(ver, 'verification').status === 'verified' && phones.some((p) => p.phone_number === '+15551230000');
+    })),
+    done('clerk.users.profile_image', 'users', 'Users: upload / delete profile image', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        if (field(u, 'has_image') !== false)
+            return false;
+        const set = await h({ m: 'POST', p: `/v1/users/${id(u)}/profile_image`, b: { file: 'https://cdn.test/me.png' } });
+        if (!ok(set) || field(set, 'has_image') !== true || field(set, 'image_url') !== 'https://cdn.test/me.png')
+            return false;
+        const del = await h({ m: 'DELETE', p: `/v1/users/${id(u)}/profile_image` });
+        const missing = await h({ m: 'DELETE', p: '/v1/users/user_nope/profile_image' });
+        return ok(del) && field(del, 'has_image') === false && field(del, 'image_url') === '' && missing.status === 404;
+    })),
+    done('clerk.users.web3_wallets', 'users', 'Users: web3 wallet identifiers (add / verify / delete)', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const addr = '0xAbC0000000000000000000000000000000000000';
+        const w = await h({ m: 'POST', p: '/v1/web3_wallets', b: { user_id: id(u), web3_wallet: addr } });
+        if (!ok(w) || field(w, 'object') !== 'web3_wallet' || field(w, 'web3_wallet') !== addr || field(w, 'verification') !== null)
+            return false;
+        const ver = await h({ m: 'PATCH', p: `/v1/web3_wallets/${id(w)}`, b: { verified: true } });
+        const onUser = await h({ m: 'GET', p: `/v1/users/${id(u)}` });
+        const wallets = field(onUser, 'web3_wallets');
+        if (!ok(ver) || field(ver, 'verification').status !== 'verified' || !wallets.some((x) => x.web3_wallet === addr))
+            return false;
+        const del = await h({ m: 'DELETE', p: `/v1/web3_wallets/${id(w)}` });
+        const missingUser = await h({ m: 'POST', p: '/v1/web3_wallets', b: { user_id: 'user_nope', web3_wallet: addr } });
+        return ok(del) && field(del, 'deleted') === true && missingUser.status === 404;
+    })),
+    // ── Sessions ────────────────────────────────────────────────────────────────────
+    done('clerk.sessions.create', 'sessions', 'Sessions: create for a user', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        return ok(s) && field(s, 'object') === 'session' && field(s, 'status') === 'active' && field(s, 'user_id') === id(u);
+    })),
+    done('clerk.sessions.retrieve_list', 'sessions', 'Sessions: retrieve + list filtered by user', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const g = await h({ m: 'GET', p: `/v1/sessions/${id(s)}` });
+        const l = await h({ m: 'GET', p: `/v1/sessions?user_id=${id(u)}` });
+        return ok(g) && id(g) === id(s) && ok(l) && l.body.length === 1;
+    })),
+    done('clerk.sessions.revoke', 'sessions', 'Sessions: revoke → status revoked', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const rev = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/revoke` });
+        return ok(rev) && field(rev, 'status') === 'revoked';
+    })),
+    done('clerk.sessions.create_validation', 'sessions', 'Sessions: create rejects missing/unknown user', 'api', 'core', () => withRoot(async (h) => {
+        const noUser = await h({ m: 'POST', p: '/v1/sessions', b: {} });
+        const badUser = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: 'user_nope' } });
+        return noUser.status === 422 && badUser.status === 404;
+    })),
+    done('clerk.sessions.verify', 'sessions', 'Sessions: verify a signed token round-trip', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens` });
+        const jwt = field(tok, 'jwt');
+        const verified = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/verify`, b: { token: jwt } });
+        const badToken = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/verify`, b: { token: 'not.a.jwt' } });
+        return ok(verified) && badToken.status === 400;
+    })),
+    done('clerk.sessions.touch', 'sessions', 'Sessions: touch (refresh last_active_at)', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser(), at: '2026-01-01T00:00:00.000Z' });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) }, at: '2026-01-01T00:00:00.000Z' });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Touch Co' } });
+        const before = field(await h({ m: 'GET', p: `/v1/sessions/${id(s)}` }), 'last_active_at');
+        // touch with a later occurredAt bumps last_active_at and records last active org
+        const touched = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/touch`, b: { active_organization_id: id(o) }, at: '2026-01-01T01:00:00.000Z' });
+        if (!ok(touched) || field(touched, 'last_active_at') <= before || field(touched, 'last_active_organization_id') !== id(o))
+            return false;
+        // touching a revoked session is rejected; an unknown session 404s
+        await h({ m: 'POST', p: `/v1/sessions/${id(s)}/revoke` });
+        const onRevoked = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/touch` });
+        const missing = await h({ m: 'POST', p: '/v1/sessions/sess_nope/touch' });
+        return onRevoked.status === 400 && missing.status === 404;
+    })),
+    done('clerk.sessions.revoke_all_for_user', 'sessions', 'Sessions: revoke all of a user’s sessions (list → revoke each, the SDK pattern)', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const other = await h({ m: 'POST', p: '/v1/users', b: mkUser('other@twin.test') });
+        const s1 = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const s2 = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const sOther = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(other) } });
+        // The real backend has no bulk endpoint: list the user's active sessions, revoke each.
+        const list = await h({ m: 'GET', p: `/v1/sessions?user_id=${id(u)}&status=active` });
+        const active = list.body;
+        if (active.length !== 2)
+            return false;
+        for (const s of active)
+            await h({ m: 'POST', p: `/v1/sessions/${s.id}/revoke` });
+        const afterU = await h({ m: 'GET', p: `/v1/sessions?user_id=${id(u)}&status=active` });
+        const afterOther = await h({ m: 'GET', p: `/v1/sessions/${id(sOther)}` });
+        // the other user's session is untouched
+        return afterU.body.length === 0
+            && field(await h({ m: 'GET', p: `/v1/sessions/${id(s1)}` }), 'status') === 'revoked'
+            && field(await h({ m: 'GET', p: `/v1/sessions/${id(s2)}` }), 'status') === 'revoked'
+            && field(afterOther, 'status') === 'active';
+    })),
+    // ── JWT / JWKS (the highest-value capability) ─────────────────────────────────────
+    done('clerk.jwt.session_token', 'jwt', 'Session token: issue a REAL signed RS256 JWT', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens` });
+        const jwt = field(tok, 'jwt');
+        return ok(tok) && field(tok, 'object') === 'token' && typeof jwt === 'string' && jwt.split('.').length === 3;
+    })),
+    done('clerk.jwt.jwks_endpoint', 'jwt', 'JWKS: serve a real JWKS document at the well-known path', 'api', 'core', () => withRoot(async (h) => {
+        const jwks = await h({ m: 'GET', p: '/.well-known/jwks.json' });
+        const keys = field(jwks, 'keys');
+        return ok(jwks) && Array.isArray(keys) && keys.length === 1 && keys[0].kty === 'RSA' && keys[0].alg === 'RS256' && typeof keys[0].n === 'string';
+    })),
+    done('clerk.jwt.verify_against_jwks', 'jwt', 'JWT/JWKS: a twin-issued token verifies against the served JWKS (claims round-trip)', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens` });
+        const jwt = field(tok, 'jwt');
+        const jwksResp = await h({ m: 'GET', p: '/.well-known/jwks.json' });
+        const result = verifyJwtWithJwks(jwt, jwksResp.body);
+        // claims must round-trip: sub == user id, sid == session id, plus standard iss
+        return result.valid === true && result.payload?.sub === id(u) && result.payload?.sid === id(s) && typeof result.payload?.iss === 'string';
+    })),
+    done('clerk.jwt.tamper_rejected', 'jwt', 'JWT/JWKS: a tampered or expired token fails verification', 'api', 'core', () => withRoot(async () => {
+        const root = mkdtempSync(join(tmpdir(), 'clerk-jwt-'));
+        try {
+            const jwt = await signJwt({ sub: 'user_x' }, { root, now: 1_000 });
+            const jwks = await buildJwks(root);
+            const tampered = `${jwt.slice(0, -4)}AAAA`;
+            const expired = verifyJwtWithJwks(jwt, jwks, { now: 10_000 }); // long past exp
+            const bad = verifyJwtWithJwks(tampered, jwks, { now: 1_001 });
+            const good = verifyJwtWithJwks(jwt, jwks, { now: 1_001 });
+            return good.valid === true && bad.valid === false && expired.valid === false;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('clerk.jwt.template_token', 'jwt', 'JWT template: issue a token with the template’s custom claims', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        await h({ m: 'POST', p: '/v1/jwt_templates', b: { name: 'supabase', claims: { role: 'authenticated' } } });
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens/supabase` });
+        const jwt = field(tok, 'jwt');
+        const jwks = await h({ m: 'GET', p: '/.well-known/jwks.json' });
+        const result = verifyJwtWithJwks(jwt, jwks.body);
+        return ok(tok) && result.valid === true && result.payload?.role === 'authenticated';
+    })),
+    done('clerk.jwt.stable_kid', 'jwt', 'JWKS: token header kid matches a JWKS key kid (stable across calls)', 'api', 'common', () => withRoot(async () => {
+        const root = mkdtempSync(join(tmpdir(), 'clerk-kid-'));
+        try {
+            const jwt = await signJwt({ sub: 'user_y' }, { root });
+            const headerKid = JSON.parse(Buffer.from(jwt.split('.')[0].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString()).kid;
+            const jwks = await buildJwks(root);
+            const jwks2 = await buildJwks(root); // same persisted key → same kid
+            return headerKid === jwks.keys[0].kid && jwks.keys[0].kid === jwks2.keys[0].kid;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('clerk.jwt.custom_signing_key', 'jwt', 'JWT template: bring-your-own custom signing key (HS256)', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const secret = 'super-shared-hs256-secret';
+        const tmpl = await h({ m: 'POST', p: '/v1/jwt_templates', b: { name: 'supabase', claims: { role: 'authenticated' }, custom_signing_key: true, signing_algorithm: 'HS256', key: secret } });
+        // the secret must never be serialized back (twin-internal)
+        if (!ok(tmpl) || field(tmpl, 'custom_signing_key') !== true || field(tmpl, 'signing_algorithm') !== 'HS256' || 'key' in tmpl.body || '_signing_key' in tmpl.body)
+            return false;
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens/supabase` });
+        const jwt = field(tok, 'jwt');
+        // the token is genuinely HS256 (header alg) and verifies against the shared secret
+        const header = JSON.parse(Buffer.from(jwt.split('.')[0].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString());
+        const v = verifyJwtHs256(jwt, secret);
+        const wrong = verifyJwtHs256(jwt, 'not-the-secret');
+        // it must NOT verify against the RS256 JWKS (HS256 is symmetric, not in the JWKS)
+        const jwks = (await h({ m: 'GET', p: '/.well-known/jwks.json' })).body;
+        const viaJwks = verifyJwtWithJwks(jwt, jwks);
+        // custom_signing_key=true requires a key + HS256 (validation)
+        const missingKey = await h({ m: 'POST', p: '/v1/jwt_templates', b: { name: 'bad', custom_signing_key: true } });
+        const badAlgo = await h({ m: 'POST', p: '/v1/jwt_templates', b: { name: 'bad2', custom_signing_key: true, signing_algorithm: 'RS512', key: 'x' } });
+        return ok(tok) && header.alg === 'HS256' && v.valid === true && v.payload?.role === 'authenticated' && v.payload?.sub === id(u)
+            && wrong.valid === false && viaJwks.valid === false && missingKey.status === 422 && badAlgo.status === 422;
+    })),
+    done('clerk.jwt.networkless_verify', 'jwt', 'authenticateRequest networkless verification helper (signed-in actor from claims)', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens` });
+        const jwt = field(tok, 'jwt');
+        const jwks = (await h({ m: 'GET', p: '/.well-known/jwks.json' })).body;
+        const state = networklessVerifyToken(jwt, jwks);
+        // negative: a tampered token yields a signed-out state with no actor (never throws)
+        const tampered = networklessVerifyToken(`${jwt.slice(0, -4)}AAAA`, jwks);
+        return state.isSignedIn === true && state.userId === id(u) && state.sessionId === id(s)
+            && tampered.isSignedIn === false && tampered.userId === null;
+    })),
+    // ── Sign-in tokens ────────────────────────────────────────────────────────────
+    done('clerk.sign_in_tokens.create', 'sign_in_tokens', 'Sign-in tokens: create a real signed token for a user', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const t = await h({ m: 'POST', p: '/v1/sign_in_tokens', b: { user_id: id(u) } });
+        const jwt = field(t, 'token');
+        return ok(t) && field(t, 'user_id') === id(u) && typeof jwt === 'string' && jwt.split('.').length === 3;
+    })),
+    done('clerk.sign_in_tokens.revoke', 'sign_in_tokens', 'Sign-in tokens: revoke', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const t = await h({ m: 'POST', p: '/v1/sign_in_tokens', b: { user_id: id(u) } });
+        const rev = await h({ m: 'POST', p: `/v1/sign_in_tokens/${id(t)}/revoke` });
+        if (!ok(rev) || field(rev, 'status') !== 'revoked')
+            return false;
+        // re-revoking a non-pending token is rejected; an unknown id 404s
+        const again = await h({ m: 'POST', p: `/v1/sign_in_tokens/${id(t)}/revoke` });
+        const missing = await h({ m: 'POST', p: '/v1/sign_in_tokens/sit_nope/revoke' });
+        return again.status === 422 && missing.status === 404;
+    })),
+    done('clerk.actor_tokens.create', 'actor_tokens', 'Actor tokens (impersonation): create + revoke a real signed token', 'api', 'niche', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const t = await h({ m: 'POST', p: '/v1/actor_tokens', b: { user_id: id(u), actor: { sub: 'user_admin' } } });
+        const jwt = field(t, 'token');
+        if (!ok(t) || field(t, 'user_id') !== id(u) || field(t, 'actor').sub !== 'user_admin' || jwt.split('.').length !== 3)
+            return false;
+        // the minted token verifies against the JWKS and carries the impersonation `act` claim
+        const jwks = (await h({ m: 'GET', p: '/.well-known/jwks.json' })).body;
+        const v = verifyJwtWithJwks(jwt, jwks);
+        if (!v.valid || v.payload?.sub !== id(u) || v.payload?.act?.sub !== 'user_admin')
+            return false;
+        const noActor = await h({ m: 'POST', p: '/v1/actor_tokens', b: { user_id: id(u) } });
+        const missingUser = await h({ m: 'POST', p: '/v1/actor_tokens', b: { user_id: 'user_nope', actor: { sub: 'x' } } });
+        const rev = await h({ m: 'POST', p: `/v1/actor_tokens/${id(t)}/revoke` });
+        return noActor.status === 422 && missingUser.status === 404 && ok(rev) && field(rev, 'status') === 'revoked';
+    })),
+    done('clerk.testing_tokens.create', 'testing', 'Testing tokens (bypass bot protection in E2E)', 'api', 'niche', () => withRoot(async (h) => {
+        const t = await h({ m: 'POST', p: '/v1/testing_tokens' });
+        const tok = field(t, 'token');
+        const t2 = await h({ m: 'POST', p: '/v1/testing_tokens' });
+        return ok(t) && field(t, 'object') === 'testing_token' && typeof tok === 'string' && tok.startsWith('testing_token_')
+            && typeof field(t, 'expires_at') === 'number' && field(t2, 'token') !== tok;
+    })),
+    // ── Organizations ─────────────────────────────────────────────────────────────
+    done('clerk.orgs.create', 'organizations', 'Organizations: create with name + slug', 'api', 'core', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme Inc' } });
+        return ok(o) && field(o, 'object') === 'organization' && field(o, 'name') === 'Acme Inc' && field(o, 'slug') === 'acme-inc';
+    })),
+    done('clerk.orgs.crud', 'organizations', 'Organizations: retrieve / update / list / delete', 'api', 'core', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        const g = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        const upd = await h({ m: 'PATCH', p: `/v1/organizations/${id(o)}`, b: { name: 'Acme Two' } });
+        const l = await h({ m: 'GET', p: '/v1/organizations' });
+        const del = await h({ m: 'DELETE', p: `/v1/organizations/${id(o)}` });
+        const gone = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        return ok(g) && id(g) === id(o) && ok(upd) && field(upd, 'name') === 'Acme Two' && field(l, 'total_count') === 1 && ok(del) && field(del, 'deleted') === true && gone.status === 404;
+    })),
+    done('clerk.orgs.lookup_by_slug', 'organizations', 'Organizations: retrieve by slug', 'api', 'common', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Globex' } });
+        const bySlug = await h({ m: 'GET', p: '/v1/organizations/globex' });
+        return ok(o) && typeof id(o) === 'string' && id(o).length > 0 && ok(bySlug) && id(bySlug) === id(o) && field(bySlug, 'slug') === 'globex' && field(bySlug, 'name') === 'Globex';
+    })),
+    done('clerk.orgs.validation', 'organizations', 'Organizations: rejects missing name + duplicate slug', 'api', 'core', () => withRoot(async (h) => {
+        const noName = await h({ m: 'POST', p: '/v1/organizations', b: {} });
+        await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Dup', slug: 'dup' } });
+        const dup = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Dup2', slug: 'dup' } });
+        return noName.status === 422 && dup.status === 422;
+    })),
+    done('clerk.orgs.metadata', 'organizations', 'Organizations: merge metadata', 'api', 'common', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Meta Co' } });
+        await h({ m: 'PATCH', p: `/v1/organizations/${id(o)}/metadata`, b: { public_metadata: { tier: 'gold' } } });
+        const g = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        return ok(g) && field(g, 'public_metadata').tier === 'gold';
+    })),
+    done('clerk.orgs.domains', 'organizations', 'Organization domains (verified domains / enrollment modes)', 'api', 'common', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Domains Co' } });
+        const d = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/domains`, b: { name: 'acme.test', enrollment_mode: 'automatic_invitation' } });
+        if (!ok(d) || field(d, 'name') !== 'acme.test' || field(d, 'enrollment_mode') !== 'automatic_invitation')
+            return false;
+        const list = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/domains` });
+        const patch = await h({ m: 'PATCH', p: `/v1/organizations/${id(o)}/domains/${id(d)}`, b: { enrollment_mode: 'manual_invitation' } });
+        const dup = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/domains`, b: { name: 'acme.test' } });
+        const badMode = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/domains`, b: { name: 'x.test', enrollment_mode: 'bogus' } });
+        const del = await h({ m: 'DELETE', p: `/v1/organizations/${id(o)}/domains/${id(d)}` });
+        const after = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/domains` });
+        return field(list, 'data').length === 1 && ok(patch) && field(patch, 'enrollment_mode') === 'manual_invitation'
+            && dup.status === 422 && badMode.status === 422 && ok(del) && field(del, 'deleted') === true && field(after, 'data').length === 0;
+    })),
+    done('clerk.orgs.roles_permissions', 'organizations', 'Custom organization roles + permissions (membership resolves its permissions)', 'api', 'common', () => withRoot(async (h) => {
+        // system roles + permissions are enumerable
+        const roles = await h({ m: 'GET', p: '/v1/organizations_roles' });
+        const perms = await h({ m: 'GET', p: '/v1/organizations_permissions' });
+        const roleKeys = field(roles, 'data').map((r) => r.key);
+        if (!roleKeys.includes('admin') || !roleKeys.includes('basic_member') || field(perms, 'data').length === 0)
+            return false;
+        // a custom role can be created and assigned; its permissions flow onto the membership
+        const custom = await h({ m: 'POST', p: '/v1/organizations_roles', b: { key: 'org:billing', name: 'Billing', permissions: ['org:sys_profile:read', 'org:sys_memberships:read'] } });
+        if (!ok(custom))
+            return false;
+        const dup = await h({ m: 'POST', p: '/v1/organizations_roles', b: { key: 'admin', name: 'Dup' } });
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Roles Co' } });
+        const mAdmin = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u), role: 'admin' } });
+        const adminPerms = field(mAdmin, 'permissions');
+        const upd = await h({ m: 'PATCH', p: `/v1/organizations/${id(o)}/memberships/${id(u)}`, b: { role: 'org:billing' } });
+        const billingPerms = field(upd, 'permissions');
+        return dup.status === 422 && adminPerms.includes('org:sys_memberships:manage')
+            && !billingPerms.includes('org:sys_memberships:manage') && billingPerms.includes('org:sys_profile:read');
+    })),
+    done('clerk.orgs.logo', 'organizations', 'Organization logo upload / delete', 'api', 'niche', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Logo Co' } });
+        if (field(o, 'has_image') !== false)
+            return false;
+        const set = await h({ m: 'PUT', p: `/v1/organizations/${id(o)}/logo`, b: { file: 'https://cdn.test/logo.png' } });
+        if (!ok(set) || field(set, 'has_image') !== true || field(set, 'image_url') !== 'https://cdn.test/logo.png')
+            return false;
+        const del = await h({ m: 'DELETE', p: `/v1/organizations/${id(o)}/logo` });
+        const missing = await h({ m: 'PUT', p: '/v1/organizations/org_nope/logo', b: { file: 'x' } });
+        return ok(del) && field(del, 'has_image') === false && field(del, 'image_url') === '' && missing.status === 404;
+    })),
+    // ── Organization memberships ────────────────────────────────────────────────────
+    done('clerk.org_memberships.add', 'org_memberships', 'Org memberships: add a member with a role', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        const m = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u), role: 'admin' } });
+        return ok(m) && field(m, 'object') === 'organization_membership' && field(m, 'role') === 'admin' && field(m, 'public_user_data').user_id === id(u);
+    })),
+    done('clerk.org_memberships.list', 'org_memberships', 'Org memberships: list for an org (with nested user + org)', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u) } });
+        const l = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/memberships` });
+        const data = field(l, 'data');
+        return ok(l) && data.length === 1 && data[0].organization?.id === id(o);
+    })),
+    done('clerk.org_memberships.update_role', 'org_memberships', 'Org memberships: update a member’s role', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u), role: 'basic_member' } });
+        const upd = await h({ m: 'PATCH', p: `/v1/organizations/${id(o)}/memberships/${id(u)}`, b: { role: 'admin' } });
+        return ok(upd) && field(upd, 'role') === 'admin';
+    })),
+    done('clerk.org_memberships.remove', 'org_memberships', 'Org memberships: remove a member', 'api', 'core', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u) } });
+        const del = await h({ m: 'DELETE', p: `/v1/organizations/${id(o)}/memberships/${id(u)}` });
+        const l = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/memberships` });
+        return ok(del) && field(del, 'deleted') === true && field(l, 'data').length === 0;
+    })),
+    done('clerk.org_memberships.members_count', 'org_memberships', 'Org memberships: members_count tracks add/remove', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u) } });
+        const afterAdd = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        await h({ m: 'DELETE', p: `/v1/organizations/${id(o)}/memberships/${id(u)}` });
+        const afterRemove = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        return field(afterAdd, 'members_count') === 1 && field(afterRemove, 'members_count') === 0;
+    })),
+    done('clerk.org_memberships.duplicate_rejected', 'org_memberships', 'Org memberships: a duplicate add is rejected', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u) } });
+        const dup = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u) } });
+        return dup.status === 422;
+    })),
+    done('clerk.users.org_memberships', 'org_memberships', 'Users: list a user’s organization memberships', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        await h({ m: 'POST', p: `/v1/organizations/${id(o)}/memberships`, b: { user_id: id(u), role: 'admin' } });
+        const l = await h({ m: 'GET', p: `/v1/users/${id(u)}/organization_memberships` });
+        const data = field(l, 'data');
+        return ok(l) && data.length === 1 && data[0].organization?.id === id(o);
+    })),
+    // ── Organization invitations ────────────────────────────────────────────────────
+    done('clerk.org_invitations.create', 'org_invitations', 'Org invitations: create (pending) + bumps count', 'api', 'core', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        const inv = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations`, b: { email_address: 'new@twin.test', role: 'basic_member' } });
+        const org = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        return ok(inv) && field(inv, 'status') === 'pending' && field(inv, 'email_address') === 'new@twin.test' && field(org, 'pending_invitations_count') === 1;
+    })),
+    done('clerk.org_invitations.list_revoke', 'org_invitations', 'Org invitations: list + revoke', 'api', 'core', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Acme' } });
+        const inv = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations`, b: { email_address: 'x@twin.test' } });
+        const l = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/invitations` });
+        const rev = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations/${id(inv)}/revoke` });
+        return field(l, 'data').length === 1 && ok(rev) && field(rev, 'status') === 'revoked';
+    })),
+    done('clerk.org_invitations.accept', 'org_invitations', 'Org invitations: accept → creates membership + decrements pending count', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser('new@twin.test') });
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Accept Co' } });
+        const inv = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations`, b: { email_address: 'new@twin.test', role: 'admin' } });
+        const acc = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations/${id(inv)}/accept`, b: { user_id: id(u) } });
+        if (!ok(acc) || field(acc, 'object') !== 'organization_membership' || field(acc, 'role') !== 'admin')
+            return false;
+        const invAfter = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/invitations` });
+        const orgAfter = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        const members = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/memberships` });
+        // re-accepting an already-accepted invite is rejected
+        const reAccept = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations/${id(inv)}/accept`, b: { user_id: id(u) } });
+        return field(invAfter, 'data')[0].status === 'accepted'
+            && field(orgAfter, 'pending_invitations_count') === 0
+            && field(members, 'data').length === 1 && reAccept.status === 422;
+    })),
+    done('clerk.org_invitations.bulk', 'org_invitations', 'Org invitations: bulk create', 'api', 'niche', () => withRoot(async (h) => {
+        const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Bulk Co' } });
+        const bulk = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations/bulk`, b: { invitations: [
+                    { email_address: 'a@twin.test', role: 'admin' },
+                    { email_address: 'b@twin.test' },
+                ] } });
+        const created = bulk.body;
+        if (!ok(bulk) || !Array.isArray(created) || created.length !== 2 || created[0].role !== 'admin' || created[0].status !== 'pending')
+            return false;
+        const org = await h({ m: 'GET', p: `/v1/organizations/${id(o)}` });
+        const list = await h({ m: 'GET', p: `/v1/organizations/${id(o)}/invitations` });
+        // an empty array + a missing email are rejected
+        const empty = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations/bulk`, b: { invitations: [] } });
+        const noEmail = await h({ m: 'POST', p: `/v1/organizations/${id(o)}/invitations/bulk`, b: { invitations: [{ role: 'admin' }] } });
+        return field(org, 'pending_invitations_count') === 2 && field(list, 'data').length === 2 && empty.status === 422 && noEmail.status === 422;
+    })),
+    // ── Application invitations ─────────────────────────────────────────────────────
+    done('clerk.invitations.crud', 'invitations', 'Invitations: create / list / revoke', 'api', 'common', () => withRoot(async (h) => {
+        const inv = await h({ m: 'POST', p: '/v1/invitations', b: { email_address: 'invitee@twin.test' } });
+        if (!ok(inv) || field(inv, 'status') !== 'pending')
+            return false;
+        const l = await h({ m: 'GET', p: '/v1/invitations' });
+        const rev = await h({ m: 'POST', p: `/v1/invitations/${id(inv)}/revoke` });
+        return l.body.length === 1 && ok(rev) && field(rev, 'status') === 'revoked';
+    })),
+    done('clerk.invitations.notify', 'invitations', 'Invitations: notify flag / redirect_url handling', 'api', 'niche', () => withRoot(async (h) => {
+        // notify defaults true → the twin records an invite url (it never delivers email)
+        const notified = await h({ m: 'POST', p: '/v1/invitations', b: { email_address: 'n1@twin.test', redirect_url: 'https://app.test/welcome' } });
+        if (!ok(notified) || field(notified, 'notified') !== true || typeof field(notified, 'url') !== 'string' || !String(field(notified, 'url')).includes('welcome'))
+            return false;
+        // notify:false → no url recorded, redirect_url null
+        const quiet = await h({ m: 'POST', p: '/v1/invitations', b: { email_address: 'n2@twin.test', notify: false } });
+        return ok(quiet) && field(quiet, 'notified') === false && field(quiet, 'url') === null;
+    })),
+    // ── Allowlist / Blocklist ────────────────────────────────────────────────────────
+    done('clerk.allowlist.crud', 'access_lists', 'Allowlist identifiers: create / list / delete', 'api', 'common', () => withRoot(async (h) => {
+        const a = await h({ m: 'POST', p: '/v1/allowlist_identifiers', b: { identifier: 'vip@twin.test' } });
+        if (!ok(a) || field(a, 'identifier') !== 'vip@twin.test' || field(a, 'identifier_type') !== 'email_address')
+            return false;
+        const l = await h({ m: 'GET', p: '/v1/allowlist_identifiers' });
+        const del = await h({ m: 'DELETE', p: `/v1/allowlist_identifiers/${id(a)}` });
+        const l2 = await h({ m: 'GET', p: '/v1/allowlist_identifiers' });
+        return l.body.length === 1 && ok(del) && field(del, 'deleted') === true && l2.body.length === 0;
+    })),
+    done('clerk.blocklist.crud', 'access_lists', 'Blocklist identifiers: create / list / delete', 'api', 'common', () => withRoot(async (h) => {
+        const b = await h({ m: 'POST', p: '/v1/blocklist_identifiers', b: { identifier: '+15551234567' } });
+        if (!ok(b) || field(b, 'identifier_type') !== 'phone_number')
+            return false;
+        const l = await h({ m: 'GET', p: '/v1/blocklist_identifiers' });
+        const del = await h({ m: 'DELETE', p: `/v1/blocklist_identifiers/${id(b)}` });
+        return l.body.length === 1 && ok(del) && field(del, 'deleted') === true;
+    })),
+    // ── JWT templates (CRUD, separate from token issuance) ────────────────────────────
+    done('clerk.jwt_templates.crud', 'jwt_templates', 'JWT templates: create / list / retrieve / update / delete', 'api', 'common', () => withRoot(async (h) => {
+        const t = await h({ m: 'POST', p: '/v1/jwt_templates', b: { name: 'firebase', claims: { x: 1 }, lifetime: 120 } });
+        if (!ok(t) || field(t, 'name') !== 'firebase' || field(t, 'lifetime') !== 120)
+            return false;
+        const g = await h({ m: 'GET', p: `/v1/jwt_templates/${id(t)}` });
+        const upd = await h({ m: 'PATCH', p: `/v1/jwt_templates/${id(t)}`, b: { lifetime: 300 } });
+        const l = await h({ m: 'GET', p: '/v1/jwt_templates' });
+        const del = await h({ m: 'DELETE', p: `/v1/jwt_templates/${id(t)}` });
+        return ok(g) && id(g) === id(t) && ok(upd) && field(upd, 'lifetime') === 300 && l.body.length === 1 && ok(del) && field(del, 'deleted') === true;
+    })),
+    // ── Webhooks (svix-style signed emission via injected sink) ───────────────────────
+    done('clerk.webhooks.user_created', 'webhooks', 'Webhooks: a signed user.created webhook is emitted + verifies', 'api', 'core', () => withRoot(async (h) => {
+        clearClerkWebhooks();
+        const secret = 'whsec_dGVzdHNlY3JldHRlc3RzZWNyZXQ=';
+        const delivered = [];
+        registerClerkWebhook('https://app.test/webhook', secret);
+        try {
+            const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+            // the created user must be REAL (a genuine id + echoed shape), not just a 2xx status
+            if (!ok(u) || typeof id(u) !== 'string' || id(u).length === 0 || field(u, 'object') !== 'user')
+                return false;
+            // emit deterministically via the injected sink and verify svix signature
+            const out = await emitClerkEvent('user.create', { id: id(u) }, { deliver: (url, body, headers) => { delivered.push({ body, headers }); } });
+            if (out.length !== 1)
+                return false;
+            const ev = verifyWebhook(delivered[0].body, delivered[0].headers, secret);
+            return ev.type === 'user.created' && typeof ev.data.id === 'string' && ev.data.id === id(u);
+        }
+        finally {
+            clearClerkWebhooks();
+        }
+    })),
+    done('clerk.webhooks.signature_scheme', 'webhooks', 'Webhooks: svix signature recompute matches (tamper rejected)', 'api', 'core', () => {
+        const secret = 'whsec_dGVzdHNlY3JldHRlc3RzZWNyZXQ=';
+        const sig = computeSvixSignature('msg_1', 1700000000, '{"hello":"world"}', secret);
+        const good = (() => {
+            try {
+                verifyWebhook('{"hello":"world"}', { 'svix-id': 'msg_1', 'svix-timestamp': '1700000000', 'svix-signature': sig }, secret);
+                return true;
+            }
+            catch (err) {
+                if (isInfrastructureError(err))
+                    throw harnessError('clerk.webhooks.signature_scheme', err);
+                return false;
+            }
+        })();
+        const bad = (() => {
+            try {
+                verifyWebhook('{"hello":"TAMPERED"}', { 'svix-id': 'msg_1', 'svix-timestamp': '1700000000', 'svix-signature': sig }, secret);
+                return false;
+            }
+            catch {
+                return true;
+            }
+        })();
+        return Promise.resolve(sig.startsWith('v1,') && good && bad);
+    }),
+    done('clerk.webhooks.org_events', 'webhooks', 'Webhooks: organization.created maps to the right event type', 'api', 'common', () => withRoot(async (h) => {
+        clearClerkWebhooks();
+        const delivered = [];
+        registerClerkWebhook('https://app.test/webhook');
+        try {
+            const o = await h({ m: 'POST', p: '/v1/organizations', b: { name: 'Hook Co' } });
+            // the org must be REAL (genuine id + echoed shape) before we fold it into the event
+            if (!ok(o) || typeof id(o) !== 'string' || id(o).length === 0 || field(o, 'object') !== 'organization')
+                return false;
+            const out = await emitClerkEvent('organization.create', { id: id(o) }, { deliver: (_u, body) => { delivered.push({ body }); } });
+            if (out.length !== 1)
+                return false;
+            const parsed = JSON.parse(delivered[0].body);
+            return parsed.type === 'organization.created' && parsed.data?.id === id(o);
+        }
+        finally {
+            clearClerkWebhooks();
+        }
+    })),
+    done('clerk.webhooks.delivery_retries', 'webhooks', 'Webhooks: delivery attempts log', 'api', 'niche', () => withRoot(async (h) => {
+        clearClerkWebhooks();
+        try {
+            const ep = await h({ m: 'POST', p: '/v1/webhooks/endpoints', b: { url: 'https://app.test/hook' } });
+            // a write that maps to an event records a delivery attempt for the endpoint
+            await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+            const attempts = await h({ m: 'GET', p: `/v1/webhooks/endpoints/${id(ep)}/attempts` });
+            const data = field(attempts, 'data');
+            if (!ok(attempts) || data.length < 1 || data[0].event_type !== 'user.created' || data[0].status !== 'succeeded')
+                return false;
+            // a disabled endpoint records no further attempts
+            await h({ m: 'PATCH', p: `/v1/webhooks/endpoints/${id(ep)}`, b: { disabled: true } });
+            await h({ m: 'POST', p: '/v1/users', b: mkUser('two@twin.test') });
+            const after = await h({ m: 'GET', p: `/v1/webhooks/endpoints/${id(ep)}/attempts` });
+            const missing = await h({ m: 'GET', p: '/v1/webhooks/endpoints/ep_nope/attempts' });
+            return field(after, 'data').length === data.length && missing.status === 404;
+        }
+        finally {
+            clearClerkWebhooks();
+        }
+    })),
+    done('clerk.webhooks.endpoints_api', 'webhooks', 'Webhooks: manage endpoints via the Backend API', 'api', 'niche', () => withRoot(async (h) => {
+        clearClerkWebhooks();
+        try {
+            const ep = await h({ m: 'POST', p: '/v1/webhooks/endpoints', b: { url: 'https://app.test/hook', description: 'prod' } });
+            const secret = field(ep, 'signing_secret');
+            if (!ok(ep) || field(ep, 'object') !== 'webhook_endpoint' || field(ep, 'url') !== 'https://app.test/hook' || !secret.startsWith('whsec_'))
+                return false;
+            const get = await h({ m: 'GET', p: `/v1/webhooks/endpoints/${id(ep)}` });
+            const list = await h({ m: 'GET', p: '/v1/webhooks/endpoints' });
+            const upd = await h({ m: 'PATCH', p: `/v1/webhooks/endpoints/${id(ep)}`, b: { description: 'staging' } });
+            const del = await h({ m: 'DELETE', p: `/v1/webhooks/endpoints/${id(ep)}` });
+            const gone = await h({ m: 'GET', p: `/v1/webhooks/endpoints/${id(ep)}` });
+            const noUrl = await h({ m: 'POST', p: '/v1/webhooks/endpoints', b: {} });
+            return ok(get) && id(get) === id(ep) && field(list, 'data').length === 1
+                && ok(upd) && field(upd, 'description') === 'staging' && ok(del) && field(del, 'deleted') === true && gone.status === 404 && noUrl.status === 422;
+        }
+        finally {
+            clearClerkWebhooks();
+        }
+    })),
+    // ── read-only guard ──────────────────────────────────────────────────────────────
+    done('clerk.serve.read_only', 'serve', 'Read-only twin rejects writes (405)', 'api', 'core', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'clerk-ro-'));
+        try {
+            const r = await handleClerkTwinRequest({ method: 'POST', path: '/v1/users', body: JSON.stringify(mkUser()), readOnly: true, root });
+            return r.status === 405;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('clerk.serve.unknown_route', 'serve', 'Unknown route fails like Clerk (404), never fabricates success', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/nonexistent_collection' });
+        return r.status === 404 && Array.isArray(r.body.errors);
+    })),
+    // ── Connector ─────────────────────────────────────────────────────────────────
+    done('clerk.connector.pull_users', 'connector', 'Connector: pull users from an injected client, fold into the twin', 'connector', 'core', async () => {
+        const { pullClerkUsers, syncClerkFromReal } = await import("./clerk-connector.js");
+        const fakeClient = {
+            users: { getUserList: async () => ({ data: [{ id: 'user_real_1', firstName: 'Real', emailAddresses: [{ emailAddress: 'real@x.test' }] }], totalCount: 1 }) },
+            organizations: { getOrganizationList: async () => ({ data: [], totalCount: 0 }) },
+        };
+        const pulled = await pullClerkUsers(fakeClient);
+        if (pulled.length !== 1 || pulled[0].id !== 'user_real_1')
+            return false;
+        const root = mkdtempSync(join(tmpdir(), 'clerk-pull-'));
+        try {
+            const res = await syncClerkFromReal(fakeClient, { root, occurredAt: '2026-01-01T00:00:00.000Z' });
+            const got = await handleClerkTwinRequest({ method: 'GET', path: '/v1/users', root });
+            return res.observed >= 1 && got.body.some((u) => u.id === 'user_real_1');
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('clerk.connector.push_confirm', 'connector', 'Connector: push pending writes to an injected client + confirm (idempotent re-push)', 'connector', 'core', async () => {
+        const { performClerkAction } = await import("./clerk-connector.js");
+        const root = mkdtempSync(join(tmpdir(), 'clerk-push-'));
+        const wire = [];
+        const execute = async (r) => { wire.push(r); return { status: 200, headers: {}, body: JSON.stringify({ id: 'user_real_pushed' }) }; };
+        try {
+            const made = await handleClerkTwinRequest({ method: 'POST', path: '/v1/users', body: JSON.stringify(mkUser()), root });
+            const id = String(made.body.id);
+            const out = await performClerkAction(execute, { operation: 'user.create', subject: { type: 'user', id }, fields: mkUser() }, { resolve: (_t, l) => l, service: 'clerk', root });
+            // one entry, one wire write, the vendor's id back; the twin's own records (a session, an attempt) cross nothing
+            const own = await performClerkAction(execute, { operation: 'sign_in_attempt.upsert', subject: { type: 'sign_in_attempt', id: 'sia_x' }, fields: {} }, { resolve: (_t, l) => l, service: 'clerk', root });
+            return out.externalId === 'user_real_pushed' && wire.length === 1 && wire[0].path === '/v1/users' && own.externalId === 'sia_x' && wire.length === 1;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('clerk.connector.push_unsupported', 'connector', 'Connector: an unsupported push op fails loudly (no silent drop)', 'connector', 'common', async () => {
+        const { pushClerkAction } = await import("./clerk-connector.js");
+        const fakeClient = { users: {}, organizations: {} };
+        try {
+            await pushClerkAction(fakeClient, { operation: 'session.create', subject: { type: 'session', id: 'sess_1' }, fields: {} });
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }),
+    done('clerk.connector.pull_sessions', 'connector', 'Connector: pull sessions / memberships from real Clerk, fold into the twin', 'connector', 'common', async () => {
+        const { pullClerkSessions, pullClerkMemberships, syncClerkFromReal } = await import("./clerk-connector.js");
+        const fakeClient = {
+            users: { getUserList: async () => ({ data: [{ id: 'user_real_1', emailAddresses: [{ emailAddress: 'real@x.test' }] }], totalCount: 1 }) },
+            organizations: {
+                getOrganizationList: async () => ({ data: [{ id: 'org_real_1', name: 'Real Org', slug: 'real-org' }], totalCount: 1 }),
+                getOrganizationMembershipList: async ({ organizationId }) => ({ data: [{ id: 'orgmem_real_1', role: 'admin', organization: { id: organizationId }, publicUserData: { userId: 'user_real_1' } }], totalCount: 1 }),
+            },
+            sessions: { getSessionList: async () => ({ data: [{ id: 'sess_real_1', userId: 'user_real_1', status: 'active' }], totalCount: 1 }) },
+        };
+        const sessions = await pullClerkSessions(fakeClient);
+        const memberships = await pullClerkMemberships(fakeClient, ['org_real_1']);
+        if (sessions.length !== 1 || sessions[0].id !== 'sess_real_1' || memberships.length !== 1 || memberships[0].fields._user_id !== 'user_real_1')
+            return false;
+        const root = mkdtempSync(join(tmpdir(), 'clerk-pull-sess-'));
+        try {
+            await syncClerkFromReal(fakeClient, { root, occurredAt: '2026-01-01T00:00:00.000Z' });
+            const gotSessions = await handleClerkTwinRequest({ method: 'GET', path: '/v1/sessions', root });
+            const gotMembers = await handleClerkTwinRequest({ method: 'GET', path: '/v1/organizations/org_real_1/memberships', root });
+            return gotSessions.body.some((s) => s.id === 'sess_real_1')
+                && gotMembers.body.data.some((m) => m.id === 'orgmem_real_1' && m.public_user_data?.user_id === 'user_real_1');
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    // ── UI mirror ──────────────────────────────────────────────────────────────────
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'Users', '/v1/', 'primaryEmail';
+    // now uiDataCoupled: seed a real user with a distinct email → fetch the SAME `/v1/users` list
+    // the Users screen reads → shape it through the mirror's OWN `users` section title()/
+    // subtitle() closures (imported as `SECTIONS`, the exact functions the row list calls) →
+    // assert the seeded name + email survive. Failable: an empty root's list has no [0] row, so
+    // `section(...).subtitle` throws on `undefined` and the outer `withRoot` try/catch → false.
+    done('clerk.ui.users_screen', 'ui', 'UI mirror: Users screen renders from the twin REST API (data-coupled)', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'POST', p: '/v1/users', b: mkUser('ui-users@twin.test') }),
+        fetch: async (h) => (await h({ m: 'GET', p: '/v1/users' })).body[0],
+        render: (user) => `${section('users').title(user)} | ${section('users').subtitle(user)}`,
+        assert: (_user, markup) => !!markup && markup.includes('Ada Lovelace') && markup.includes('ui-users@twin.test') && markup.includes('active'),
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'Sessions', 'user_id'; now
+    // uiDataCoupled: seed a user + a session bound to it → fetch the SAME `/v1/sessions` list
+    // the Sessions screen reads → shape via the mirror's OWN `sessions` section subtitle() (which
+    // reads `status`/`user_id`) → assert the seeded user id + active status survive. Failable: an
+    // empty root's session list has no [0] row → subtitle throws on undefined → false.
+    done('clerk.ui.sessions_screen', 'ui', 'UI mirror: Sessions screen (data-coupled)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: async (h) => {
+            const u = await h({ m: 'POST', p: '/v1/users', b: mkUser('ui-sessions@twin.test') });
+            return h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        },
+        fetch: async (h) => (await h({ m: 'GET', p: '/v1/sessions' })).body[0],
+        render: (session) => section('sessions').subtitle(session),
+        assert: (session, markup) => typeof session.user_id === 'string' && markup === `active · ${session.user_id}`,
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'Organizations', 'members'; now
+    // uiDataCoupled: seed an org with a distinct name → fetch the SAME `/v1/organizations` list the
+    // Organizations screen reads → shape via the mirror's OWN `organizations` section title()/
+    // subtitle() (which read `orgMemberCount`/`slug`) → assert the seeded slug survives. Failable:
+    // an empty root's org list has no [0] row → subtitle throws on undefined → false.
+    done('clerk.ui.organizations_screen', 'ui', 'UI mirror: Organizations screen (data-coupled)', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'POST', p: '/v1/organizations', b: { name: 'UI Check Org' } }),
+        fetch: async (h) => field(await h({ m: 'GET', p: '/v1/organizations' }), 'data')[0],
+        render: (org) => `${section('organizations').title(org)} | ${section('organizations').subtitle(org)}`,
+        assert: (_org, markup) => markup === 'UI Check Org | 0 members · ui-check-org',
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'Allowlist', 'Blocklist',
+    // 'identifier'; now uiDataCoupled: seed one allowlist + one blocklist identifier, each with a
+    // distinct value → fetch the SAME `/v1/allowlist_identifiers` + `/v1/blocklist_identifiers`
+    // lists those screens read → shape via the mirror's OWN section title()/subtitle() closures →
+    // assert both seeded identifiers + their derived types survive. Failable: an empty root's
+    // lists have no [0] rows → the closures throw on undefined → false.
+    done('clerk.ui.access_lists_screen', 'ui', 'UI mirror: Allowlist + Blocklist screens (data-coupled)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: async (h) => {
+            await h({ m: 'POST', p: '/v1/allowlist_identifiers', b: { identifier: 'ui-allow@twin.test' } });
+            return h({ m: 'POST', p: '/v1/blocklist_identifiers', b: { identifier: '+15559990000' } });
+        },
+        fetch: async (h) => ({
+            allow: (await h({ m: 'GET', p: '/v1/allowlist_identifiers' })).body[0],
+            block: (await h({ m: 'GET', p: '/v1/blocklist_identifiers' })).body[0],
+        }),
+        render: ({ allow, block }) => `${section('allowlist_identifiers').title(allow)} ${section('allowlist_identifiers').subtitle(allow)} || ` +
+            `${section('blocklist_identifiers').title(block)} ${section('blocklist_identifiers').subtitle(block)}`,
+        assert: (_data, markup) => !!markup && markup.includes('ui-allow@twin.test') && markup.includes('email_address')
+            && markup.includes('+15559990000') && markup.includes('phone_number'),
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'JWT Templates', 'lifetime';
+    // now uiDataCoupled: seed a JWT template with a distinct name + lifetime → fetch the SAME
+    // `/v1/jwt_templates` list the JWT Templates screen reads → shape via the mirror's OWN
+    // section title()/subtitle() → assert the seeded name + lifetime survive. Failable: an empty
+    // root's list has no [0] row → subtitle throws on undefined → false.
+    done('clerk.ui.jwt_templates_screen', 'ui', 'UI mirror: JWT Templates screen (data-coupled)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'POST', p: '/v1/jwt_templates', b: { name: 'ui-check-template', claims: { role: 'authenticated' }, lifetime: 90 } }),
+        fetch: async (h) => (await h({ m: 'GET', p: '/v1/jwt_templates' })).body[0],
+        render: (tmpl) => `${section('jwt_templates').title(tmpl)} | ${section('jwt_templates').subtitle(tmpl)}`,
+        assert: (_tmpl, markup) => markup === 'ui-check-template | lifetime 90s · RS256',
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'detail-line', 'pill ',
+    // 'Clerk twin'; now uiDataCoupled: seed an invitation with a distinct email (status starts
+    // 'pending') → fetch the SAME `/v1/invitations` list the detail panel would select into →
+    // render it through the mirror's OWN exported `NestedLines`/`StatusPill` components (exactly
+    // what the detail panel renders for any selected record) → assert the seeded email survives
+    // flattening AND the seeded 'pending' status drives the correct pill tone. Failable: an
+    // empty root's list has no [0] row → flattenClerkValue(undefined) yields no seeded email.
+    done('clerk.ui.detail_panel', 'ui', 'UI mirror: detail panel flattens nested fields + status pill (data-coupled)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'POST', p: '/v1/invitations', b: { email_address: 'ui-detail@twin.test' } }),
+        fetch: async (h) => (await h({ m: 'GET', p: '/v1/invitations' })).body[0],
+        render: (inv) => renderToStaticMarkup(createElement('div', null, createElement(NestedLines, { lines: flattenClerkValue(inv) }), inv?.status ? createElement(StatusPill, { value: inv.status }) : null)),
+        assert: (inv, markup) => !!markup && markup.includes('detail-line') && markup.includes('ui-detail@twin.test')
+            && inv.status === 'pending' && markup.includes(`pill ${statusTone(inv.status)}`),
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'Create user', 'CreateUserForm',
+    // "method: 'POST'", '/v1/users'; now uiDataCoupled: `seed` issues the EXACT request
+    // `CreateUserForm`'s submit handler sends (POST /v1/users with the same body shape) → `fetch`
+    // reads the SAME `/v1/users` list the dashboard reloads into on `onCreated` → `render` mounts
+    // the mirror's OWN exported `CreateUserForm` component (structural proof the wired action
+    // exists) → assert the seeded user is really there. Failable: an unseeded root's list omits
+    // the seeded email.
+    done('clerk.ui.create_user_action', 'ui', 'UI mirror: create-a-user action from the dashboard (data-coupled)', 'ui', 'niche', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'POST', p: '/v1/users', b: { email_address: ['ui-create@twin.test'], first_name: 'Uic' } }),
+        fetch: async (h) => (await h({ m: 'GET', p: '/v1/users' })).body,
+        render: () => renderToStaticMarkup(createElement(CreateUserForm, { onCreated: () => { } })),
+        assert: (users, markup) => !!markup && markup.includes('Create user') &&
+            users.some((u) => u.email_addresses[0]?.email_address === 'ui-create@twin.test' && u.first_name === 'Uic'),
+    })),
+    // TWIN-14 (B4) migration — was a marker-grep over the literals 'Impersonate user',
+    // 'ImpersonateButton', '/v1/actor_tokens'; now uiDataCoupled: seed a user, then `fetch` issues
+    // the EXACT request `ImpersonateButton`'s click handler sends (POST /v1/actor_tokens with
+    // actor.sub `dashboard_admin`) — there is no separate list endpoint, the button reads its own
+    // POST response — → `render` mounts the mirror's OWN exported `ImpersonateButton` over the
+    // seeded user → assert the minted token really carries the seeded user + the button's actor
+    // sub. Failable: a missing/unseeded user 404s the actor-token mint.
+    done('clerk.ui.impersonate', 'ui', 'UI mirror: impersonate / sign-in-as a user (data-coupled)', 'ui', 'niche', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'POST', p: '/v1/users', b: mkUser('ui-impersonate@twin.test') }),
+        fetch: async (h) => {
+            // re-fetch the seeded user (seed's response isn't threaded into fetch) via the list.
+            const user = (await h({ m: 'GET', p: '/v1/users' })).body[0];
+            const minted = await h({ m: 'POST', p: '/v1/actor_tokens', b: { user_id: user.id, actor: { sub: 'dashboard_admin' } } });
+            return Object.assign(minted, { user });
+        },
+        render: ({ user }) => renderToStaticMarkup(createElement(ImpersonateButton, { user })),
+        assert: (data, markup) => !!markup && markup.includes('Impersonate user') &&
+            ok(data) && field(data, 'user_id') === data.user.id && field(data, 'actor')?.sub === 'dashboard_admin',
+    })),
+    // ── Long-tail Backend API surface (todo) ──────────────────────────────────────────
+    done('clerk.clients.verify', 'clients', 'Clients: verify a session token → bound client + session', 'api', 'common', () => withRoot(async (h) => {
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const tok = await h({ m: 'POST', p: `/v1/sessions/${id(s)}/tokens` });
+        const jwt = field(tok, 'jwt');
+        const verified = await h({ m: 'POST', p: '/v1/clients/verify', b: { token: jwt } });
+        if (!ok(verified) || field(verified, 'object') !== 'client' || !field(verified, 'session_ids').includes(id(s)))
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/clients/verify', b: { token: 'not.a.jwt' } });
+        const missing = await h({ m: 'POST', p: '/v1/clients/verify', b: {} });
+        return bad.status === 401 && missing.status === 422;
+    })),
+    done('clerk.clients.list', 'clients', 'Clients: list active clients', 'api', 'niche', () => withRoot(async (h) => {
+        const empty = await h({ m: 'GET', p: '/v1/clients' });
+        if (!ok(empty) || field(empty, 'data').length !== 0)
+            return false;
+        const u = await h({ m: 'POST', p: '/v1/users', b: mkUser() });
+        const s = await h({ m: 'POST', p: '/v1/sessions', b: { user_id: id(u) } });
+        const list = await h({ m: 'GET', p: '/v1/clients' });
+        const clients = field(list, 'data');
+        if (!ok(list) || clients.length !== 1 || !clients[0].session_ids.includes(id(s)))
+            return false;
+        // revoking the session drops the active client
+        await h({ m: 'POST', p: `/v1/sessions/${id(s)}/revoke` });
+        const after = await h({ m: 'GET', p: '/v1/clients' });
+        return field(after, 'data').length === 0;
+    })),
+    done('clerk.redirect_urls.crud', 'redirect_urls', 'Redirect URLs allowlist CRUD', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/redirect_urls', b: { url: 'https://app.test/callback' } });
+        if (!ok(r) || field(r, 'object') !== 'redirect_url' || field(r, 'url') !== 'https://app.test/callback')
+            return false;
+        const get = await h({ m: 'GET', p: `/v1/redirect_urls/${id(r)}` });
+        const list = await h({ m: 'GET', p: '/v1/redirect_urls' });
+        const del = await h({ m: 'DELETE', p: `/v1/redirect_urls/${id(r)}` });
+        const gone = await h({ m: 'GET', p: `/v1/redirect_urls/${id(r)}` });
+        const noUrl = await h({ m: 'POST', p: '/v1/redirect_urls', b: {} });
+        return ok(get) && id(get) === id(r) && list.body.length === 1 && ok(del) && field(del, 'deleted') === true && gone.status === 404 && noUrl.status === 422;
+    })),
+    done('clerk.oauth_apps.crud', 'oauth_applications', 'OAuth applications CRUD (+ secret rotation)', 'api', 'niche', () => withRoot(async (h) => {
+        const a = await h({ m: 'POST', p: '/v1/oauth_applications', b: { name: 'My App', callback_url: 'https://app.test/cb' } });
+        const secret = field(a, 'client_secret');
+        if (!ok(a) || field(a, 'object') !== 'oauth_application' || typeof field(a, 'client_id') !== 'string' || !secret.startsWith('secret_'))
+            return false;
+        const get = await h({ m: 'GET', p: `/v1/oauth_applications/${id(a)}` });
+        const upd = await h({ m: 'PATCH', p: `/v1/oauth_applications/${id(a)}`, b: { name: 'Renamed' } });
+        const rot = await h({ m: 'POST', p: `/v1/oauth_applications/${id(a)}/rotate_secret` });
+        const list = await h({ m: 'GET', p: '/v1/oauth_applications' });
+        const del = await h({ m: 'DELETE', p: `/v1/oauth_applications/${id(a)}` });
+        const noName = await h({ m: 'POST', p: '/v1/oauth_applications', b: {} });
+        return ok(get) && ok(upd) && field(upd, 'name') === 'Renamed' && ok(rot) && field(rot, 'client_secret') !== secret
+            && field(list, 'data').length === 1 && ok(del) && field(del, 'deleted') === true && noName.status === 422;
+    })),
+    done('clerk.saml_connections.crud', 'saml_connections', 'SAML connections CRUD', 'api', 'niche', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/v1/saml_connections', b: { name: 'Okta', domain: 'acme.test', provider: 'saml_okta' } });
+        if (!ok(c) || field(c, 'object') !== 'saml_connection' || field(c, 'domain') !== 'acme.test' || typeof field(c, 'acs_url') !== 'string')
+            return false;
+        const get = await h({ m: 'GET', p: `/v1/saml_connections/${id(c)}` });
+        const upd = await h({ m: 'PATCH', p: `/v1/saml_connections/${id(c)}`, b: { active: true } });
+        const list = await h({ m: 'GET', p: '/v1/saml_connections' });
+        const del = await h({ m: 'DELETE', p: `/v1/saml_connections/${id(c)}` });
+        const missing = await h({ m: 'POST', p: '/v1/saml_connections', b: { name: 'X' } });
+        return ok(get) && id(get) === id(c) && ok(upd) && field(upd, 'active') === true && field(list, 'data').length === 1
+            && ok(del) && field(del, 'deleted') === true && missing.status === 422;
+    })),
+    done('clerk.domains.crud', 'domains', 'Instance domains (primary + satellite domains)', 'api', 'niche', () => withRoot(async (h) => {
+        const primary = await h({ m: 'POST', p: '/v1/domains', b: { name: 'app.test' } });
+        if (!ok(primary) || field(primary, 'is_satellite') !== false || typeof field(primary, 'accounts_portal_url') !== 'string')
+            return false;
+        // a second primary is rejected; satellites are allowed
+        const dupPrimary = await h({ m: 'POST', p: '/v1/domains', b: { name: 'other.test' } });
+        const sat = await h({ m: 'POST', p: '/v1/domains', b: { name: 'sat.test', is_satellite: true } });
+        if (dupPrimary.status !== 422 || !ok(sat) || field(sat, 'is_satellite') !== true)
+            return false;
+        const list = await h({ m: 'GET', p: '/v1/domains' });
+        const upd = await h({ m: 'PATCH', p: `/v1/domains/${id(sat)}`, b: { proxy_url: 'https://proxy.test' } });
+        const delPrimary = await h({ m: 'DELETE', p: `/v1/domains/${id(primary)}` });
+        const delSat = await h({ m: 'DELETE', p: `/v1/domains/${id(sat)}` });
+        return field(list, 'data').length === 2 && ok(upd) && field(upd, 'proxy_url') === 'https://proxy.test'
+            && delPrimary.status === 422 && ok(delSat) && field(delSat, 'deleted') === true;
+    })),
+    done('clerk.instance_settings.update', 'instance', 'Instance settings: read + update (restrictions / MFA / attack protection)', 'api', 'common', () => withRoot(async (h) => {
+        const get = await h({ m: 'GET', p: '/v1/instance' });
+        if (!ok(get) || field(get, 'object') !== 'instance' || field(get, 'restrictions').allowlist !== false)
+            return false;
+        const upd = await h({ m: 'PATCH', p: '/v1/instance', b: { restrictions: { allowlist: true }, mfa: { totp: true } } });
+        const r = field(upd, 'restrictions');
+        const mfa = field(upd, 'mfa');
+        // deep-merge: the untouched restriction keys survive alongside the new one
+        if (r.allowlist !== true || r.blocklist !== false || mfa.totp !== true)
+            return false;
+        // the change persists on a subsequent read, and the focused sub-resource path works too
+        const after = await h({ m: 'GET', p: '/v1/instance' });
+        const sub = await h({ m: 'PATCH', p: '/v1/instance/restrictions', b: { blocklist: true } });
+        return field(after, 'restrictions').allowlist === true && field(sub, 'restrictions').blocklist === true && field(sub, 'restrictions').allowlist === true;
+    })),
+    done('clerk.waitlist_entries.crud', 'waitlist', 'Waitlist entries: create + list (idempotent on email)', 'api', 'niche', () => withRoot(async (h) => {
+        const a = await h({ m: 'POST', p: '/v1/waitlist_entries', b: { email_address: 'wait1@twin.test' } });
+        if (!ok(a) || field(a, 'object') !== 'waitlist_entry' || field(a, 'email_address') !== 'wait1@twin.test' || field(a, 'status') !== 'pending')
+            return false;
+        if (field(a, 'is_locked') !== false || field(a, 'invitation') !== null || typeof field(a, 'created_at') !== 'number')
+            return false;
+        // idempotent on email_address: a second POST returns the SAME entry, not a new one
+        const dup = await h({ m: 'POST', p: '/v1/waitlist_entries', b: { email_address: 'wait1@twin.test' } });
+        if (!ok(dup) || id(dup) !== id(a))
+            return false;
+        await h({ m: 'POST', p: '/v1/waitlist_entries', b: { email_address: 'wait2@twin.test' } });
+        const l = await h({ m: 'GET', p: '/v1/waitlist_entries' });
+        const data = field(l, 'data');
+        if (!ok(l) || !Array.isArray(data) || data.length !== 2 || field(l, 'total_count') !== 2)
+            return false;
+        // status filter narrows; an unknown status yields none
+        const filtered = await h({ m: 'GET', p: '/v1/waitlist_entries?status=invited' });
+        if (field(filtered, 'data').length !== 0)
+            return false;
+        // negative: a missing/invalid email is a 422
+        const bad = await h({ m: 'POST', p: '/v1/waitlist_entries', b: { email_address: 'not-an-email' } });
+        return bad.status === 422;
+    })),
+    done('clerk.proxy_checks.create', 'proxy', 'Proxy checks: validate a proxy_url for a domain', 'api', 'niche', () => withRoot(async (h) => {
+        const dom = await h({ m: 'POST', p: '/v1/domains', b: { name: 'twin.test' } });
+        if (!ok(dom))
+            return false;
+        const chk = await h({ m: 'POST', p: '/v1/proxy_checks', b: { domain_id: id(dom), proxy_url: 'https://twin.test/__clerk' } });
+        if (!ok(chk) || field(chk, 'object') !== 'proxy_check' || field(chk, 'domain_id') !== id(dom))
+            return false;
+        if (field(chk, 'proxy_url') !== 'https://twin.test/__clerk' || field(chk, 'successful') !== true || typeof field(chk, 'last_run_at') !== 'number')
+            return false;
+        // negative: unknown domain → 404; malformed (non-https) proxy_url → 422; missing field → 422
+        const noDom = await h({ m: 'POST', p: '/v1/proxy_checks', b: { domain_id: 'dmn_nope', proxy_url: 'https://twin.test/__clerk' } });
+        const badUrl = await h({ m: 'POST', p: '/v1/proxy_checks', b: { domain_id: id(dom), proxy_url: 'http://insecure' } });
+        const missing = await h({ m: 'POST', p: '/v1/proxy_checks', b: { domain_id: id(dom) } });
+        return noDom.status === 404 && badUrl.status === 422 && missing.status === 422;
+    })),
+    done('clerk.beta_features.update', 'beta', 'Beta features: update beta instance settings', 'api', 'niche', () => withRoot(async (h) => {
+        // defaults are present on a fresh instance
+        const before = await h({ m: 'GET', p: '/v1/instance' });
+        if (!ok(before) || field(before, 'progressive_sign_up') !== false || field(before, 'test_mode') !== false)
+            return false;
+        const upd = await h({ m: 'PATCH', p: '/v1/beta_features/instance_settings', b: { progressive_sign_up: true, test_mode: true, from_email_address: 'hello' } });
+        if (!ok(upd) || field(upd, 'object') !== 'instance' || field(upd, 'progressive_sign_up') !== true || field(upd, 'test_mode') !== true || field(upd, 'from_email_address') !== 'hello')
+            return false;
+        // the change persists on a subsequent read and does NOT clobber other instance settings
+        const after = await h({ m: 'GET', p: '/v1/instance' });
+        if (field(after, 'progressive_sign_up') !== true || field(after, 'restrictions').allowlist !== false)
+            return false;
+        // negative: an unmodeled beta sub-resource path is not a 200 write
+        const bad = await h({ m: 'PATCH', p: '/v1/beta_features/nope', b: { x: 1 } });
+        return bad.status === 404;
+    })),
+    // ── New honest niche todos surfaced from the real Backend API (keep todo>0) ──
+    // Machine auth (M2M tokens, GA 2025-10): the Backend API exposes /machines + /m2m_tokens —
+    // create/list a machine, then mint/list/revoke an M2M token for it. None modeled yet.
+    todo('clerk.machines.crud', 'machine_auth', 'Machines: create/list (POST/GET /machines)', 'api', 'niche'),
+    todo('clerk.m2m_tokens.crud', 'machine_auth', 'M2M tokens: create/list/revoke (POST/GET /m2m_tokens)', 'api', 'niche'),
+    // The Backend API exposes the instance’s sign-up attempts: GET /sign_ups (and GET /sign_ups/:id).
+    todo('clerk.sign_ups.list', 'sign_ups', 'Sign-ups: list/retrieve attempts (GET /sign_ups)', 'api', 'niche'),
+    // TWIN-88 (reviews/2026-07-06-philosophy-first/PART2-VENDOR-PACKS.md finding F2): the twin
+    // fakes auth — ANY Backend API key is accepted, so the real vendor's 401-on-bad-key is not
+    // modeled (see clerk-twin.ts:9-10 and the README's Auth section). A known, written-down gap
+    // that now has a manifest entry instead of only living in prose (contrast
+    // openai.errors.auth_401/openai.auth.faked, openweather.auth.missing_key, polar's auth.token).
+    todo('clerk.auth.bad_key_401', 'security', 'Backend API key auth: reject a missing/invalid key with a real 401 (currently faked — any key accepted)', 'api', 'niche'),
+    // ── Pull-surface coverage audit gaps (TWIN-46 / G2) — filed as manifest todos, which is
+    // what the demand-ordered build list is drawn from. See pull-audit.json (repo root) for the
+    // per-pack pull-vs-read-surface evidence.
+    todo('clerk.connector.pull_org_invitations', 'connector', 'Connector: pull organization invitations from the real account', 'connector', 'core'),
+    todo('clerk.connector.pull_invitations', 'connector', 'Connector: pull instance-level invitations from the real account', 'connector', 'common'),
+    todo('clerk.connector.pull_access_lists', 'connector', 'Connector: pull the allowlist/blocklist from the real account', 'connector', 'common'),
+];
+/** Run the Clerk capability manifest into the categorized gap report. */
+export function clerkCapabilities() {
+    return checkCapabilities('clerk', CLERK_CAPABILITIES);
+}