@volter/twin-xidentity 0.1.0

package/dist/src/xidentity-capabilities.js

@@ -0,0 +1,905 @@
+// X (Twitter) identity capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target),
+// authored top-down from the vendor's own artefacts, all fetched 2026-08-21:
+//   • the X API v2 OpenAPI document (https://api.x.com/2/openapi.json, version 2.167): the
+//     /2/users/me operation (parameters, security scopes, response schema), the Problem error
+//     family, and the 24-scope OAuth2UserToken catalog with X's consent descriptions;
+//   • docs.x.com OAuth 2.0 guides (authorization-code + user-access-token): the authorize URL and
+//     its parameters, the token/refresh/revoke requests, confidential-vs-public client rules;
+//   • docs.x.com rate-limit pages: the x-rate-limit-* headers, the 15-minute window, 75/15min per
+//     user for /2/users/me, 429 + legacy code 88;
+//   • the official SDK sources (@xdevplatform/xdk `oauth2_auth.ts`, twitter-api-typescript-sdk
+//     `OAuth2User.ts`): the token/revoke response shapes the docs never show as JSON, the
+//     authorize-URL builders (state required, PKCE always sent), the Basic-auth construction.
+// NOT from what this twin has built. `verify()` (required to count as done) is ground truth; every
+// `expected:'done'` is genuinely claimed, so a broken one shows as a regression.
+//
+// GRANULARITY: one capability per PROTOCOL BEHAVIOUR (a parameter honoured, an error produced, a
+// field selected), the googleoauth precedent — this surface is four endpoints with dozens of
+// behaviours, so per-endpoint entries would have been a denominator of four and a lie.
+//
+// EVIDENCE BOUNDARIES: a `done` whose behaviour is derived from RFC 6749/7009 or widely-reported
+// wire captures rather than a fetched official artefact says so in its title/comment, and a
+// sibling `todo` pins the live capture. The DENOMINATOR also includes X identity surface the twin
+// does not model yet (OAuth 1.0a three-legged, the v1.1 app-only bearer flow, unmodelled user
+// fields) as honest todos.
+//
+// TWIN-ONLY ROUTES ARE NOT COUNTED. `/_twin/consent`, `/_twin/clients`, `/_twin/accounts`,
+// `/_twin/session` and `/_twin/rate_limit` are scaffolding (X's authorize form posts to an
+// undocumented internal endpoint; no API creates an X App or switches the x.com session), so they
+// are absent from this denominator exactly as ADDING_A_TWIN.md §6 requires.
+//
+// TWO DELIBERATE GRANULARITY CHOICES a reviewer will notice (§9 round one raised both):
+//   • PIN-todos ("PIN the live …") sit in the denominator alongside build-todos. They are not
+//     padding: each names a BEHAVIOUR the twin serves whose vendor truth is unverified, and
+//     closing one is real work against the live vendor (the googleoauth precedent:
+//     `googleoauth.tokeninfo.id_token`, `errors.error_page_http_status`). Coverage % only gets
+//     WORSE from carrying them.
+//   • The field-selection MECHANICS are one `done` (`users_me.user_fields_selection` — one
+//     behaviour: the enum parameter selects fields) while each UNMODELLED field is its own todo:
+//     a todo must be individually buildable and closeable, and "model entities" is a different
+//     work item from "model withheld". The asymmetry is per-WORK-ITEM granularity, not
+//     per-column inflation.
+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 } from '@volter/world-tooling';
+import { ConsentPage, ErrorPage } from "../client/xidentity-consent.js";
+import { CONSENT_CLIENT_JS, xIdentityConsentState } from "./xidentity-consent-ui.js";
+import { checkXIdentityConformance } from "./xidentity-conformance.js";
+import { XIdentityBudgetError, XIDENTITY_BUDGET_BURST_CEILING } from "./xidentity-budget.js";
+import { liveXIdentityExecute, mapUsersMeAccount, pullXIdentity, pushPendingXIdentityActions, syncXIdentityFromReal, } from "./xidentity-connector.js";
+import { pkceS256 } from "./xidentity-pkce.js";
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, DEFAULT_PUBLIC_CLIENT_ID, defaultRedirectUris } from "./xidentity-store.js";
+import { handleXIdentityTwinRequest } from "./xidentity-twin.js";
+const AT = '2026-02-01T00:00:00.000Z';
+const atPlus = (seconds) => new Date(Date.parse(AT) + seconds * 1000).toISOString();
+/** The origin this harness's world serves the twin at. The seeded demo clients' callbacks are
+ *  DERIVED from it (runtime contract R7: the port belongs to the caller's world, never to the
+ *  twin's source), so the probes below name no port of their own. */
+const DEMO_ORIGIN = 'http://localhost:3000';
+const REDIRECT_URIS = defaultRedirectUris(DEMO_ORIGIN);
+const REDIRECT = REDIRECT_URIS[0];
+const ADA = DEFAULT_ACCOUNTS[0];
+const GRACE = DEFAULT_ACCOUNTS[1];
+const SCOPE = 'tweet.read users.read offline.access';
+const VERIFIER = 'cap-verifier-0123456789-0123456789-0123456789-012';
+const BASIC = `Basic ${Buffer.from(`${DEFAULT_CLIENT_ID}:${DEFAULT_CLIENT_SECRET}`).toString('base64')}`;
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'xidentity-cap-'));
+    const h = ((s) => handleXIdentityTwinRequest({
+        method: s.m,
+        path: s.p,
+        ...(s.b === undefined ? {} : { body: s.b }),
+        ...(s.h ? { headers: s.h } : {}),
+        root,
+        origin: DEMO_ORIGIN,
+        occurredAt: s.at ?? AT,
+    }));
+    h.root = root;
+    try {
+        return await verifyBoundary('xidentity.withRoot', () => steps(h));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const ok = (r) => r.status >= 200 && r.status < 300;
+const body = (r) => r.body;
+const html = (r) => String(r.body);
+const loc = (r) => r.headers?.['location'] ?? '';
+const qp = (r, key) => {
+    try {
+        return new URL(loc(r)).searchParams.get(key);
+    }
+    catch {
+        return null;
+    }
+};
+const form = (params) => new URLSearchParams(params).toString();
+const decoded = (token) => Buffer.from(String(token ?? ''), 'base64url').toString('utf8');
+/** Build an authorize URL from parameters, so a verify can vary exactly one of them. `undefined`
+ *  REMOVES a base parameter. */
+function authUrl(params = {}) {
+    const q = new URLSearchParams();
+    const base = {
+        response_type: 'code',
+        client_id: DEFAULT_CLIENT_ID,
+        redirect_uri: REDIRECT,
+        scope: SCOPE,
+        state: 'cap-state',
+        code_challenge: pkceS256(VERIFIER),
+        code_challenge_method: 'S256',
+        ...params,
+    };
+    for (const [k, v] of Object.entries(base))
+        if (v !== undefined)
+            q.set(k, v);
+    return `/i/oauth2/authorize?${q.toString()}`;
+}
+const AUTH_REQUEST_RE = /name="auth_request" value="([^"]+)"/;
+/** Drive the REAL browser legs: authorization request → authorize screen → Authorize/Cancel →
+ *  the 302. Everything a verify needs from the round trip comes back. */
+async function consentFlow(h, opts = {}) {
+    const auth = await h({ m: 'GET', p: authUrl(opts.params ?? {}), ...(opts.at ? { at: opts.at } : {}) });
+    const requestId = AUTH_REQUEST_RE.exec(html(auth))?.[1] ?? '';
+    const redirect = await h({
+        m: 'POST',
+        p: '/_twin/consent',
+        b: form({ auth_request: requestId, decision: opts.decision ?? 'allow' }),
+        ...(opts.at ? { at: opts.at } : {}),
+    });
+    return { auth, requestId, redirect, code: qp(redirect, 'code'), state: qp(redirect, 'state') };
+}
+/** The full round trip, ending in redeemed tokens (confidential client + Basic by default). */
+async function fullFlow(h, opts = {}) {
+    const flow = await consentFlow(h, opts);
+    if (!flow.code)
+        return { code: null, tokens: {}, status: 0, redirect: flow.redirect };
+    const clientId = opts.clientId ?? DEFAULT_CLIENT_ID;
+    const basic = opts.basic === null ? undefined : (opts.basic ?? BASIC);
+    const res = await h({
+        m: 'POST',
+        p: '/2/oauth2/token',
+        b: form({
+            grant_type: 'authorization_code',
+            code: flow.code,
+            client_id: clientId,
+            redirect_uri: REDIRECT,
+            code_verifier: opts.verifier ?? VERIFIER,
+        }),
+        ...(basic ? { h: { authorization: basic } } : {}),
+        ...(opts.tokenAt ?? opts.at ? { at: opts.tokenAt ?? opts.at } : {}),
+    });
+    return { code: flow.code, tokens: body(res), status: res.status, redirect: flow.redirect };
+}
+// ── shorthands ──
+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' });
+// ── the connector's offline fake: a REAL-SHAPED X reply (the OpenAPI example user), never an
+// invented one ──
+const FAKE_USERS_ME = {
+    data: {
+        id: '2244994945',
+        name: 'X Developers',
+        username: 'XDevelopers',
+        created_at: '2013-12-14T04:35:55.000Z',
+        description: 'The voice of the X developer community',
+        profile_image_url: 'https://pbs.twimg.com/profile_images/xdevs_normal.png',
+        protected: false,
+        public_metrics: { followers_count: 583423, following_count: 2048, tweet_count: 14052, listed_count: 1672, like_count: 100, media_count: 300 },
+        verified: true,
+        verified_type: 'business',
+    },
+};
+const fakeExecute = async (_method, path) => {
+    if (path.startsWith('/2/users/me'))
+        return structuredClone(FAKE_USERS_ME);
+    return {};
+};
+// ── the manifest ──────────────────────────────────────────────────────────────────────────────
+export const XIDENTITY_CAPABILITIES = [
+    // ═══ authorize — GET x.com/i/oauth2/authorize ═════════════════════════════════════════════
+    done('xidentity.authorize.renders_consent', 'authorize', 'A valid authorization request renders the authorize screen (HTML, 200) with a settleable request handle', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl() });
+        return r.status === 200 && /ar_[0-9a-f]{32}/.test(html(r)) && html(r).includes('Authorize app');
+    })),
+    done('xidentity.authorize.requires_client_id', 'authorize', 'A missing client_id renders the error page (no redirect — there is no trusted callback yet)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ client_id: undefined }) });
+        return r.status === 400 && html(r).includes('client_id') && !loc(r);
+    })),
+    done('xidentity.authorize.unknown_client', 'authorize', 'An unknown client_id renders the error page naming invalid_client (401), never a redirect', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ client_id: 'bm90LWEtcmVhbC1jbGllbnQ6MTpjaQ' }) });
+        return r.status === 401 && html(r).includes('invalid_client') && !loc(r);
+    })),
+    done('xidentity.authorize.requires_redirect_uri', 'authorize', 'A missing redirect_uri renders the error page (no redirect)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ redirect_uri: undefined }) });
+        return r.status === 400 && html(r).includes('redirect_uri') && !loc(r);
+    })),
+    done('xidentity.authorize.redirect_uri_exact_match', 'authorize', 'Callback URLs are compared EXACTLY (docs: "must correspond to one of the Callback URLs… exact match validation") — a trailing-slash variant is refused with the error page, the registered one passes', 'api', 'core', () => withRoot(async (h) => {
+        const near = await h({ m: 'GET', p: authUrl({ redirect_uri: `${REDIRECT}/` }) });
+        const exact = await h({ m: 'GET', p: authUrl() });
+        return near.status === 400 && !loc(near) && html(near).includes('redirect_uri') && exact.status === 200 && html(exact).includes('Authorize app');
+    })),
+    done('xidentity.authorize.fragment_redirect_refused', 'authorize', 'A redirect_uri carrying a fragment is refused outright EVEN WHEN REGISTERED with one (RFC 6749 §3.1.2; a fragment never reaches the server)', 'api', 'niche', () => withRoot(async (h) => {
+        // The discriminating case (§9 round two): an unregistered fragment URI is refused by plain
+        // exact-match anyway, so the guard is only provable against a client REGISTERED with the
+        // fragment-bearing callback.
+        const fragClient = 'RnJhZ0NsaWVudDAxMjM0NTY3ODk';
+        const fragUri = 'http://localhost:3000/cb#frag';
+        await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_id: fragClient, client_secret: 's', name: 'Frag App', redirect_uris: [fragUri] }) });
+        const r = await h({ m: 'GET', p: authUrl({ client_id: fragClient, redirect_uri: fragUri }) });
+        return r.status === 400 && !loc(r);
+    })),
+    done('xidentity.authorize.requires_response_type_code', 'authorize', 'response_type is required and must be `code` — the only value X\'s OAuth 2.0 documents; anything else bounces unsupported_response_type to the validated callback', 'api', 'core', () => withRoot(async (h) => {
+        const missing = await h({ m: 'GET', p: authUrl({ response_type: undefined }) });
+        const wrong = await h({ m: 'GET', p: authUrl({ response_type: 'token' }) });
+        return missing.status === 302 && loc(missing).startsWith(REDIRECT) && qp(missing, 'error') === 'invalid_request'
+            && wrong.status === 302 && qp(wrong, 'error') === 'unsupported_response_type' && qp(wrong, 'state') === 'cap-state';
+    })),
+    done('xidentity.authorize.requires_scope', 'authorize', 'scope is required (the docs\' parameter table); a request without one is refused', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ scope: undefined }) });
+        return r.status === 302 && qp(r, 'error') === 'invalid_request' && String(qp(r, 'error_description')).includes('scope');
+    })),
+    done('xidentity.authorize.requires_state', 'authorize', 'state is required as a PARAMETER (the docs\' table; the legacy official SDK makes it non-optional) — and the EMPTY string is accepted, because the current official SDK emits state:"" when its caller omits one', 'api', 'core', () => withRoot(async (h) => {
+        // §9 round one: the current xdk's getAuthorizationUrl(state?) emits `state: state || ""`,
+        // so an EMPTY state parameter is what the vendor's own client sends — refusing it would
+        // refuse the official SDK. Absent-vs-empty is decided deliberately: absent → refused
+        // (RFC-derived, pinned by xidentity.authorize.error_channel), empty → the screen.
+        const missing = await h({ m: 'GET', p: authUrl({ state: undefined }) });
+        const empty = await h({ m: 'GET', p: authUrl({ state: '' }) });
+        return missing.status === 302 && qp(missing, 'error') === 'invalid_request' && String(qp(missing, 'error_description')).includes('state')
+            && empty.status === 200 && html(empty).includes('Authorize app');
+    })),
+    done('xidentity.authorize.state_max_500', 'authorize', 'state is capped at 500 characters (docs: "up to 500 characters"); 500 passes, 501 is refused', 'api', 'niche', () => withRoot(async (h) => {
+        const atCap = await h({ m: 'GET', p: authUrl({ state: 'x'.repeat(500) }) });
+        const over = await h({ m: 'GET', p: authUrl({ state: 'x'.repeat(501) }) });
+        return atCap.status === 200 && over.status === 302 && qp(over, 'error') === 'invalid_request';
+    })),
+    done('xidentity.authorize.state_roundtrip', 'authorize', 'The caller\'s state is echoed VERBATIM on the success redirect (the docs\' callback example carries it first)', 'api', 'core', () => withRoot(async (h) => {
+        const state = 'st~ate-With_Odd.Chars123';
+        const flow = await consentFlow(h, { params: { state } });
+        return flow.redirect.status === 302 && flow.state === state && !!flow.code;
+    })),
+    done('xidentity.authorize.requires_pkce', 'authorize', 'PKCE is REQUIRED: an authorization request without code_challenge is refused (the docs\' parameter table; the LEGACY official SDK always sends one — the current xdk only when setPkceParameters was called, so the docs table is the load-bearing evidence)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ code_challenge: undefined, code_challenge_method: undefined }) });
+        return r.status === 302 && qp(r, 'error') === 'invalid_request' && String(qp(r, 'error_description')).includes('code_challenge');
+    })),
+    done('xidentity.authorize.challenge_method_values', 'authorize', 'code_challenge_method accepts the two documented values (S256, plain) and refuses anything else', 'api', 'core', () => withRoot(async (h) => {
+        const bad = await h({ m: 'GET', p: authUrl({ code_challenge_method: 'S512' }) });
+        const plain = await h({ m: 'GET', p: authUrl({ code_challenge: 'plain-challenge-value', code_challenge_method: 'plain' }) });
+        return bad.status === 302 && qp(bad, 'error') === 'invalid_request' && plain.status === 200;
+    })),
+    done('xidentity.authorize.deny_access_denied', 'authorize', 'Cancelling bounces error=access_denied to the callback with the state echoed, and NO code', 'api', 'core', () => withRoot(async (h) => {
+        const flow = await consentFlow(h, { decision: 'deny' });
+        return flow.redirect.status === 302 && qp(flow.redirect, 'error') === 'access_denied' && flow.state === 'cap-state' && flow.code === null;
+    })),
+    done('xidentity.authorize.callback_params_exact', 'authorize', 'The success redirect carries EXACTLY state and code — the docs\' callback example (`?state=state&code=…`) has no other parameter, and the twin invents none', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        if (flow.redirect.status !== 302)
+            return false;
+        const keys = [...new URL(loc(flow.redirect)).searchParams.keys()].sort();
+        return keys.length === 2 && keys[0] === 'code' && keys[1] === 'state';
+    })),
+    done('xidentity.authorize.request_single_use', 'authorize', 'A settled authorization request cannot be settled twice (the browser cannot replay a decision)', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const again = await h({ m: 'POST', p: '/_twin/consent', b: form({ auth_request: flow.requestId, decision: 'allow' }) });
+        return !!flow.code && again.status === 400 && body(again)['error'] === 'invalid_request';
+    })),
+    todo('xidentity.authorize.challenge_method_case', 'authorize', 'PIN the live case tolerance for code_challenge_method: the docs write S256; the legacy official SDK emits lowercase s256 (the twin accepts both, unpinned)', 'api', 'niche'),
+    todo('xidentity.authorize.challenge_method_default', 'authorize', 'PIN the live default when code_challenge_method is omitted (the twin follows RFC 7636\'s `plain` default, unpinned)', 'api', 'niche'),
+    todo('xidentity.authorize.error_channel', 'authorize', 'PIN which authorize failures X renders as a page vs bounces to the callback (the twin follows RFC 6749 §4.1.2.1 after the redirect_uri boundary, unpinned)', 'api', 'common'),
+    todo('xidentity.authorize.error_page_fidelity', 'authorize', 'PIN x.com\'s live authorize error page (DOM, wording, HTTP status) — the twin renders a plain machine-readable card, unpinned', 'api', 'niche'),
+    todo('xidentity.authorize.openapi_authorize_host', 'authorize', 'RESOLVE the source discrepancy: the v2 OpenAPI names api.x.com/2/oauth2/authorize as authorizationUrl while docs and both official SDKs use x.com/i/oauth2/authorize (the twin serves the documented browser URL only)', 'api', 'niche'),
+    // ═══ consent semantics ════════════════════════════════════════════════════════════════════
+    done('xidentity.consent.all_or_nothing', 'consent', 'X\'s consent is ALL-OR-NOTHING (two buttons, no per-scope checkboxes): the grant and the token carry the FULL requested scope set', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens, status } = await fullFlow(h);
+        return status === 200 && tokens['scope'] === SCOPE;
+    })),
+    done('xidentity.consent.session_account_consents', 'consent', 'The consent is made BY the x.com session\'s signed-in account — switching the session switches whose identity the flow yields', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/_twin/session', b: JSON.stringify({ account_id: GRACE.id }) });
+        const { tokens, status } = await fullFlow(h);
+        if (status !== 200)
+            return false;
+        const me = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        return ok(me) && body(me)['data']?.id === GRACE.id && body(me)['data']?.username === GRACE.username;
+    })),
+    todo('xidentity.consent.regrant_replaces', 'consent', 'PIN whether a re-authorization REPLACES or UNIONS the client\'s prior grant (the twin replaces — the screen showed the new set — unpinned)', 'api', 'niche'),
+    todo('xidentity.consent.offline_access_wording', 'consent', 'PIN the consent screen\'s live wording for offline.access (the OpenAPI description is developer-facing; the twin shows the widely-reported "Stay connected…" line, unpinned)', 'ui', 'niche'),
+    // ═══ token — POST api.x.com/2/oauth2/token (authorization_code) ═══════════════════════════
+    done('xidentity.token.code_exchange', 'token', 'A minted code redeems for the SDK-shaped token body: token_type bearer, expires_in 7200 (docs: 2-hour default), the granted scope, an X-shaped opaque access token', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens, status } = await fullFlow(h);
+        return status === 200
+            && tokens['token_type'] === 'bearer'
+            && tokens['expires_in'] === 7200
+            && tokens['scope'] === SCOPE
+            && decoded(tokens['access_token']).includes(':at:');
+    })),
+    done('xidentity.token.pkce_s256', 'token', 'S256 PKCE verifies with real SHA-256: the right verifier redeems, a wrong one is refused with the single indistinguishable bad-code answer', 'api', 'core', () => withRoot(async (h) => {
+        const good = await fullFlow(h);
+        const bad = await fullFlow(h, { verifier: 'wrong-verifier-0123456789-0123456789-01234567' });
+        return good.status === 200 && bad.status === 400 && bad.tokens['error'] === 'invalid_request';
+    })),
+    done('xidentity.token.pkce_plain', 'token', 'plain PKCE compares the verifier literally to the challenge', 'api', 'common', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { params: { code_challenge: 'the-plain-secret', code_challenge_method: 'plain' }, verifier: 'the-plain-secret' });
+        const bad = await fullFlow(h, { params: { code_challenge: 'the-plain-secret', code_challenge_method: 'plain' }, verifier: 'not-the-secret' });
+        // The failure must be THE PKCE refusal, not any 400 (a missing parameter would also 400).
+        return r.status === 200 && bad.status === 400
+            && bad.tokens['error'] === 'invalid_request'
+            && String(bad.tokens['error_description']).includes('authorization code was invalid');
+    })),
+    done('xidentity.token.requires_code_verifier', 'token', 'code_verifier is required at the token endpoint (the docs\' parameter list)', 'api', 'core', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code: flow.code ?? '', client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT }), h: { authorization: BASIC } });
+        return r.status === 400 && body(r)['error'] === 'invalid_request' && String(body(r)['error_description']).includes('code_verifier');
+    })),
+    done('xidentity.token.redirect_uri_repeated_and_matching', 'token', 'redirect_uri must be repeated at the token endpoint and match the code\'s (RFC 6749 §4.1.3; the docs\' parameter list requires it)', 'api', 'core', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const missing = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code: flow.code ?? '', client_id: DEFAULT_CLIENT_ID, code_verifier: VERIFIER }), h: { authorization: BASIC } });
+        const wrong = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code: flow.code ?? '', client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT_URIS[1], code_verifier: VERIFIER }), h: { authorization: BASIC } });
+        return missing.status === 400 && String(body(missing)['error_description']).includes('redirect_uri')
+            && wrong.status === 400 && body(wrong)['error'] === 'invalid_request';
+    })),
+    done('xidentity.token.code_single_use', 'token', 'An authorization code redeems exactly ONCE; the replay is refused with the reported wire message ("Value passed for the authorization code was invalid.")', 'api', 'core', () => withRoot(async (h) => {
+        const { code, status } = await fullFlow(h);
+        if (status !== 200 || !code)
+            return false;
+        const replay = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code, client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT, code_verifier: VERIFIER }), h: { authorization: BASIC } });
+        return replay.status === 400 && body(replay)['error'] === 'invalid_request' && String(body(replay)['error_description']).includes('authorization code was invalid');
+    })),
+    done('xidentity.token.code_expires', 'token', 'An authorization code expires (30s modelled; the exact live TTL is a filed todo) — redemption before the deadline succeeds, after it is refused', 'api', 'common', () => withRoot(async (h) => {
+        const fresh = await fullFlow(h, { tokenAt: atPlus(29) });
+        const stale = await fullFlow(h, { tokenAt: atPlus(31) });
+        return fresh.status === 200 && stale.status === 400;
+    })),
+    done('xidentity.token.code_bound_to_client', 'token', 'A code minted for one client is refused when another client redeems it — indistinguishably from an unknown code', 'api', 'core', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code: flow.code ?? '', client_id: DEFAULT_PUBLIC_CLIENT_ID, redirect_uri: REDIRECT, code_verifier: VERIFIER }) });
+        return r.status === 400 && body(r)['error'] === 'invalid_request';
+    })),
+    done('xidentity.token.confidential_basic_auth', 'token', 'A confidential client authenticates with HTTP Basic (docs: base64(client_id:client_secret)); a wrong secret is 401 invalid_client', 'api', 'core', () => withRoot(async (h) => {
+        const good = await fullFlow(h);
+        const badBasic = `Basic ${Buffer.from(`${DEFAULT_CLIENT_ID}:not-the-secret`).toString('base64')}`;
+        const bad = await fullFlow(h, { basic: badBasic });
+        return good.status === 200 && bad.status === 401 && bad.tokens['error'] === 'invalid_client';
+    })),
+    done('xidentity.token.confidential_requires_basic', 'token', 'A confidential client presenting only a body client_id (no Basic header) is refused — the docs document Basic for confidential clients and body client_id for PUBLIC clients only', 'api', 'common', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { basic: null });
+        return r.status === 401 && r.tokens['error'] === 'invalid_client';
+    })),
+    done('xidentity.token.public_client_body_id', 'token', 'A public client exchanges with client_id in the BODY and no secret (docs: "You still are required to include Client Id in the body… with a public client")', 'api', 'core', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { params: { client_id: DEFAULT_PUBLIC_CLIENT_ID }, clientId: DEFAULT_PUBLIC_CLIENT_ID, basic: null });
+        return r.status === 200 && typeof r.tokens['access_token'] === 'string';
+    })),
+    done('xidentity.token.offline_access_gates_refresh', 'token', 'A refresh_token rides EXACTLY when the grant carries offline.access (docs: "The offline.access scope enables refresh token issuance") — present with it, absent without it', 'api', 'core', () => withRoot(async (h) => {
+        const withOffline = await fullFlow(h);
+        const without = await fullFlow(h, { params: { scope: 'tweet.read users.read' } });
+        return withOffline.status === 200 && decoded(withOffline.tokens['refresh_token']).includes(':rt:')
+            && without.status === 200 && without.tokens['refresh_token'] === undefined;
+    })),
+    done('xidentity.token.requires_grant_type', 'token', 'A token request without grant_type is refused; an unknown grant_type answers unsupported_grant_type', 'api', 'common', () => withRoot(async (h) => {
+        const missing = await h({ m: 'POST', p: '/2/oauth2/token', b: '' });
+        const unknown = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'password', client_id: DEFAULT_PUBLIC_CLIENT_ID }) });
+        return missing.status === 400 && body(missing)['error'] === 'invalid_request'
+            && unknown.status === 400 && body(unknown)['error'] === 'unsupported_grant_type';
+    })),
+    done('xidentity.token.requires_code', 'token', 'An authorization_code exchange without a code is refused as invalid_request', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT, code_verifier: VERIFIER }), h: { authorization: BASIC } });
+        return r.status === 400 && body(r)['error'] === 'invalid_request' && String(body(r)['error_description']).includes('code');
+    })),
+    todo('xidentity.token.token_type_case', 'token', 'PIN the live token_type literal (the twin serves the widely-reported lowercase "bearer"; the docs show no response JSON)', 'api', 'niche'),
+    todo('xidentity.token.error_wording', 'token', 'PIN the token endpoint\'s live error codes and descriptions per failure (the docs show no error examples; the twin uses RFC codes with reported wire wording)', 'api', 'common'),
+    todo('xidentity.token.code_ttl', 'token', 'PIN the live authorization-code lifetime (the twin models the widely-reported 30 seconds)', 'api', 'niche'),
+    todo('xidentity.token.client_secret_post', 'token', 'PIN whether X accepts client_secret in the POST body (client_secret_post) — the docs document only Basic; the twin refuses, unpinned', 'api', 'niche'),
+    todo('xidentity.token.json_body_tolerance', 'token', 'PIN whether the live token endpoint tolerates a JSON body (the twin requires application/x-www-form-urlencoded, per the docs\' curl examples)', 'api', 'niche'),
+    // ═══ refresh — POST /2/oauth2/token (refresh_token) ═══════════════════════════════════════
+    done('xidentity.refresh.grant', 'refresh', 'A refresh_token redeems for a fresh 2-hour access token carrying the same scope (docs: refresh_token, grant_type=refresh_token, client_id)', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        return r.status === 200 && body(r)['expires_in'] === 7200 && body(r)['scope'] === SCOPE && decoded(body(r)['access_token']).includes(':at:');
+    })),
+    done('xidentity.refresh.rotation', 'refresh', 'Refresh tokens ROTATE (widely-reported wire behaviour; live pin filed): the response carries a NEW refresh_token and the spent one is refused on second use', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const first = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        const replay = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        return first.status === 200
+            && typeof body(first)['refresh_token'] === 'string'
+            && body(first)['refresh_token'] !== tokens['refresh_token']
+            && replay.status === 400 && String(body(replay)['error_description']).includes('token was invalid');
+    })),
+    done('xidentity.refresh.requires_refresh_token', 'refresh', 'A refresh request without refresh_token is refused as invalid_request', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        return r.status === 400 && body(r)['error'] === 'invalid_request';
+    })),
+    done('xidentity.refresh.unknown_token_refused', 'refresh', 'An unknown refresh token is refused with the reported wire message ("Value passed for the token was invalid.")', 'api', 'common', () => withRoot(async (h) => {
+        await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', refresh_token: 'bm90LWEtdG9rZW4', client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        return r.status === 400 && String(body(r)['error_description']).includes('token was invalid');
+    })),
+    done('xidentity.refresh.bound_to_client', 'refresh', 'A refresh token minted for one client is refused when another client presents it — with the same indistinguishable bad-token answer', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']), client_id: DEFAULT_PUBLIC_CLIENT_ID }) });
+        return r.status === 400 && body(r)['error'] === 'invalid_request' && String(body(r)['error_description']).includes('token was invalid');
+    })),
+    todo('xidentity.refresh.scope_param', 'refresh', 'PIN whether X honours a scope-narrowing parameter on refresh (RFC 6749 §6 allows it; X does not document it; the twin ignores it)', 'api', 'niche'),
+    todo('xidentity.refresh.token_lifetime', 'refresh', 'PIN the refresh token\'s own lifetime/expiry semantics (undocumented; the twin models no expiry)', 'api', 'niche'),
+    // ═══ revoke — POST api.x.com/2/oauth2/revoke ══════════════════════════════════════════════
+    done('xidentity.revoke.access_token', 'revoke', 'Revoking an access token answers {"revoked":true} (the legacy official SDK\'s typed response) and the token is dead at /2/users/me', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: String(tokens['access_token']), client_id: DEFAULT_CLIENT_ID, token_type_hint: 'access_token' }), h: { authorization: BASIC } });
+        const me = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        return r.status === 200 && body(r)['revoked'] === true && me.status === 401;
+    })),
+    done('xidentity.revoke.pair_revocation', 'revoke', 'Revocation is "log out": revoking EITHER half kills the whole (client, user) grant — the refresh token dies with the access token (RFC-derived sweep; live pin filed)', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: String(tokens['access_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        const refresh = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        // The refusal must be THE dead-token answer, not any 400.
+        return refresh.status === 400 && String(body(refresh)['error_description']).includes('token was invalid');
+    })),
+    done('xidentity.revoke.refresh_token_hint', 'revoke', 'Revoking by refresh token (token_type_hint=refresh_token, the legacy SDK\'s other path) kills the grant too', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: String(tokens['refresh_token']), client_id: DEFAULT_CLIENT_ID, token_type_hint: 'refresh_token' }), h: { authorization: BASIC } });
+        const me = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        return r.status === 200 && body(r)['revoked'] === true && me.status === 401;
+    })),
+    done('xidentity.revoke.requires_token', 'revoke', 'A revoke request without a token parameter is refused as invalid_request', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        return r.status === 400 && body(r)['error'] === 'invalid_request';
+    })),
+    done('xidentity.revoke.client_auth', 'revoke', 'The revoke endpoint authenticates the client exactly as the token endpoint does — a wrong secret is 401 invalid_client', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: String(tokens['access_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: `Basic ${Buffer.from(`${DEFAULT_CLIENT_ID}:wrong`).toString('base64')}` } });
+        return r.status === 401 && body(r)['error'] === 'invalid_client';
+    })),
+    done('xidentity.revoke.unknown_token_200', 'revoke', 'An unknown token still answers 200 {"revoked":true} (RFC 7009 §2.2 — a probe cannot learn which tokens exist; live pin filed)', 'api', 'niche', () => withRoot(async (h) => {
+        await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: 'bm90LWEtdG9rZW4', client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        return r.status === 200 && body(r)['revoked'] === true;
+    })),
+    // Demoted from `done` by §9 round one: the twin answers a foreign-client revoke 200 while
+    // revoking nothing, but RFC 7009's two clauses point OPPOSITE ways here (§2.2 "invalid tokens do
+    // not cause an error" vs §2.1 "verifies whether the token was issued to the client … if this
+    // validation fails, the request is refused") and no X artefact settles which reading the vendor
+    // takes. The never-cross-revoke SECURITY property stays pinned as a twin invariant in
+    // xidentity-twin.test.ts; the vendor's status/body for this case is the todo.
+    todo('xidentity.revoke.cross_client_wire', 'revoke', 'PIN the live answer when a client revokes ANOTHER client\'s token (RFC 7009 §2.1 refusal vs §2.2 invalid-token 200 — the twin currently answers 200 and revokes nothing)', 'api', 'common'),
+    done('xidentity.revoke.hint_cannot_mislead', 'revoke', 'A wrong token_type_hint does not change the outcome (RFC 7009 §2.1: the hint only optimises the lookup)', 'api', 'niche', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: String(tokens['access_token']), client_id: DEFAULT_CLIENT_ID, token_type_hint: 'refresh_token' }), h: { authorization: BASIC } });
+        const me = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        return r.status === 200 && me.status === 401;
+    })),
+    todo('xidentity.revoke.wire_pin', 'revoke', 'PIN the live revoke behaviour: unknown-token status, the pair-wide sweep, and the exact response body (the SDK types {revoked: boolean}; the docs show the request only)', 'api', 'common'),
+    // ═══ users_me — GET api.x.com/2/users/me ══════════════════════════════════════════════════
+    done('xidentity.users_me.default_fields', 'users_me', 'The default response is data:{id,name,username} and NOTHING else (the OpenAPI/docs default field set)', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const me = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const d = body(me)['data'];
+        return ok(me) && d?.id === ADA.id && d?.name === ADA.name && d?.username === ADA.username
+            && Object.keys(d).sort().join(',') === 'id,name,username';
+    })),
+    done('xidentity.users_me.bearer_required', 'users_me', 'No bearer → the 401 problem envelope ({"title":"Unauthorized","type":"about:blank",…} — REPORTED wire shape, pinned by errors.auth_envelope_pin; the OpenAPI default-error contract)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/2/users/me' });
+        const b = body(r);
+        return r.status === 401 && b['title'] === 'Unauthorized' && b['type'] === 'about:blank' && b['status'] === 401 && b['detail'] === 'Unauthorized';
+    })),
+    done('xidentity.users_me.unknown_token', 'users_me', 'An unknown bearer gets the same 401 problem envelope', 'api', 'core', () => withRoot(async (h) => {
+        await fullFlow(h);
+        const r = await h({ m: 'GET', p: '/2/users/me', h: { authorization: 'Bearer bm90LWEtdG9rZW4' } });
+        return r.status === 401 && body(r)['title'] === 'Unauthorized';
+    })),
+    done('xidentity.users_me.expired_token', 'users_me', 'A token past its 2-hour expiry is refused with the 401 problem envelope', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const live = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` }, at: atPlus(7199) });
+        const dead = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` }, at: atPlus(7201) });
+        return live.status === 200 && dead.status === 401;
+    })),
+    done('xidentity.users_me.scope_enforcement', 'users_me', 'The operation demands BOTH tweet.read and users.read (the OpenAPI operation\'s OAuth2UserToken entry) — a token missing one is 403 naming the missing scope', 'api', 'core', () => withRoot(async (h) => {
+        const narrow = await fullFlow(h, { params: { scope: 'users.read offline.access' } });
+        const r = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${narrow.tokens['access_token']}` } });
+        // The 403 STATUS is the grounded fact; the envelope's title/type literals are unpinned
+        // vendor prose (xidentity.users_me.insufficient_scope_wording, todo), so they are
+        // deliberately NOT asserted here — only the status and the named missing scope.
+        return narrow.status === 200 && r.status === 403 && String(body(r)['detail']).includes('tweet.read');
+    })),
+    done('xidentity.users_me.user_fields_selection', 'users_me', 'user.fields selects the OpenAPI-enumerated optional fields: each modelled field appears when asked for and not otherwise', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const bare = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const rich = await h({ m: 'GET', p: '/2/users/me?user.fields=created_at,description,location,profile_image_url,protected,url,verified,verified_type', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const d = body(rich)['data'];
+        return ok(rich)
+            && body(bare)['data']['created_at'] === undefined
+            && d['created_at'] === ADA.createdAt
+            && d['description'] === ADA.description
+            && d['location'] === ADA.location
+            && d['profile_image_url'] === ADA.profileImageUrl
+            && d['protected'] === false
+            && d['url'] === ADA.url
+            && d['verified'] === true
+            && d['verified_type'] === 'blue';
+    })),
+    done('xidentity.users_me.public_metrics', 'users_me', 'user.fields=public_metrics returns the metrics object with the vendor\'s six counters', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'GET', p: '/2/users/me?user.fields=public_metrics', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const m = body(r)['data']?.['public_metrics'];
+        return ok(r) && m?.['followers_count'] === ADA.publicMetrics.followers_count && m?.['tweet_count'] === ADA.publicMetrics.tweet_count
+            && typeof m?.['following_count'] === 'number' && typeof m?.['listed_count'] === 'number';
+    })),
+    done('xidentity.users_me.confirmed_email', 'users_me', 'user.fields=confirmed_email returns the e-mail ONLY to a token holding users.email (X\'s April-2025 announcement gates the field behind that scope); without it the field is withheld', 'api', 'niche', () => withRoot(async (h) => {
+        const withScope = await fullFlow(h, { params: { scope: 'tweet.read users.read users.email offline.access' } });
+        const without = await fullFlow(h);
+        const granted = await h({ m: 'GET', p: '/2/users/me?user.fields=confirmed_email', h: { authorization: `Bearer ${withScope.tokens['access_token']}` } });
+        const withheld = await h({ m: 'GET', p: '/2/users/me?user.fields=confirmed_email', h: { authorization: `Bearer ${without.tokens['access_token']}` } });
+        // OMISSION (rather than a 403) for the un-scoped request is EXTRAPOLATION — pinned by
+        // xidentity.users_me.confirmed_email_scope_behavior (todo).
+        return ok(granted) && body(granted)['data']?.['confirmed_email'] === ADA.confirmedEmail
+            && ok(withheld) && body(withheld)['data']?.['confirmed_email'] === undefined;
+    })),
+    done('xidentity.users_me.invalid_field_400', 'users_me', 'An invalid user.fields value gets the invalid-request envelope: errors[].parameters names it, type is the …/problems/invalid-request URL (the errors[] array is the REPORTED WIRE shape — the OpenAPI\'s InvalidRequestProblem carries singular parameter/value; pin filed)', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'GET', p: '/2/users/me?user.fields=bogus,created_at', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const b = body(r);
+        const err = b['errors']?.[0];
+        return r.status === 400
+            && b['type'] === 'https://api.x.com/2/problems/invalid-request'
+            && b['title'] === 'Invalid Request'
+            && b['detail'] === 'One or more parameters to your request was invalid.'
+            && Array.isArray(err?.['parameters']?.['user.fields'])
+            && (err?.['parameters']?.['user.fields']).includes('bogus')
+            && String(err?.['message']).includes('bogus');
+    })),
+    done('xidentity.users_me.invalid_expansion_400', 'users_me', 'An invalid expansions value gets the same invalid-request envelope (the enum is affiliation, most_recent_post_id, pinned_post_id)', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'GET', p: '/2/users/me?expansions=pinned_tweet_id', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const err = body(r)['errors']?.[0];
+        return r.status === 400 && Array.isArray(err?.['parameters']?.['expansions']) && String(err?.['message']).includes('pinned_tweet_id');
+    })),
+    done('xidentity.users_me.revoked_session_401', 'users_me', 'DIRTY-STATE: consent → use → revoke → re-consent yields a NEW working token while the revoked one stays dead (state built up across a full lifecycle)', 'api', 'common', () => withRoot(async (h) => {
+        const first = await fullFlow(h);
+        await h({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: String(first.tokens['access_token']), client_id: DEFAULT_CLIENT_ID }), h: { authorization: BASIC } });
+        const second = await fullFlow(h);
+        const dead = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${first.tokens['access_token']}` } });
+        const alive = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${second.tokens['access_token']}` } });
+        return dead.status === 401 && alive.status === 200 && body(alive)['data']?.['id'] === ADA.id;
+    })),
+    todo('xidentity.users_me.expansion_hydration', 'users_me', 'HYDRATE the documented expansions (affiliation, most_recent_post_id, pinned_post_id) into includes.* — needs post objects the identity twin does not model', 'api', 'common'),
+    todo('xidentity.users_me.tweet_fields_validation', 'users_me', 'VALIDATE tweet.fields against the OpenAPI PostFieldsParameter enum (accepted but unvalidated today)', 'api', 'niche'),
+    todo('xidentity.users_me.field_connection_status', 'users_me', 'Model user.fields=connection_status (relational to a source user)', 'api', 'niche'),
+    todo('xidentity.users_me.field_entities', 'users_me', 'Model user.fields=entities (URL/description entity extraction)', 'api', 'niche'),
+    todo('xidentity.users_me.field_is_identity_verified', 'users_me', 'Model user.fields=is_identity_verified', 'api', 'niche'),
+    todo('xidentity.users_me.field_parody', 'users_me', 'Model user.fields=parody (parody-account label)', 'api', 'niche'),
+    todo('xidentity.users_me.field_profile_banner_url', 'users_me', 'Model user.fields=profile_banner_url', 'api', 'niche'),
+    todo('xidentity.users_me.field_receives_your_dm', 'users_me', 'Model user.fields=receives_your_dm (relational)', 'api', 'niche'),
+    todo('xidentity.users_me.field_subscribes_to_you', 'users_me', 'Model user.fields=subscribes_to_you (relational)', 'api', 'niche'),
+    todo('xidentity.users_me.field_subscription', 'users_me', 'Model user.fields=subscription and subscription_type (X Premium tier)', 'api', 'niche'),
+    todo('xidentity.users_me.field_verified_followers_count', 'users_me', 'Model user.fields=verified_followers_count', 'api', 'niche'),
+    todo('xidentity.users_me.field_withheld', 'users_me', 'Model user.fields=withheld (country-withheld metadata)', 'api', 'niche'),
+    todo('xidentity.users_me.insufficient_scope_wording', 'users_me', 'PIN the live 403 body for a token missing a required scope (the twin states the refusal plainly rather than inventing vendor prose)', 'api', 'common'),
+    todo('xidentity.users_me.invalid_request_envelope_pin', 'users_me', 'PIN the live invalid-parameter body against the OpenAPI\'s singular InvalidRequestProblem (the twin serves the reported errors[] wire shape)', 'api', 'common'),
+    todo('xidentity.users_me.confirmed_email_scope_behavior', 'users_me', 'PIN what the live endpoint does when confirmed_email is requested WITHOUT users.email (the twin withholds the field; a 403 is the other candidate)', 'api', 'niche'),
+    todo('xidentity.users_me.app_only_forbidden', 'users_me', 'Model the 403 Unsupported Authentication envelope an app-only bearer gets on this user-context endpoint', 'api', 'common'),
+    todo('xidentity.users_me.oauth1_user_context', 'users_me', 'Model OAuth 1.0a User Context as the alternate auth the OpenAPI lists for this operation', 'api', 'niche'),
+    todo('xidentity.users_me.partial_errors', 'users_me', 'Model the errors[] array alongside data (per-field Problem entries on a 200, per GetUsersMeResponse)', 'api', 'niche'),
+    // ═══ rate envelope ════════════════════════════════════════════════════════════════════════
+    done('xidentity.rate.headers', 'rate', 'Every /2/users/me response carries x-rate-limit-limit/remaining/reset (docs.x.com fundamentals): limit 75, remaining decrements per call, reset a unix timestamp', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const first = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const second = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        return first.headers?.['x-rate-limit-limit'] === '75'
+            && first.headers?.['x-rate-limit-remaining'] === '74'
+            && second.headers?.['x-rate-limit-remaining'] === '73'
+            && Number(first.headers?.['x-rate-limit-reset']) === Math.floor(Date.parse(AT) / 1000) + 900;
+    })),
+    done('xidentity.rate.429_code_88', 'rate', 'An exhausted 15-minute window answers HTTP 429 with legacy code 88 "Rate limit exceeded" (docs.x.com fundamentals, verbatim) and remaining 0', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        await h({ m: 'POST', p: '/_twin/rate_limit', b: JSON.stringify({ account_id: ADA.id, used: 75 }) });
+        const r = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const errs = body(r)['errors'];
+        return r.status === 429 && errs?.[0]?.['code'] === 88 && errs?.[0]?.['message'] === 'Rate limit exceeded'
+            && r.headers?.['x-rate-limit-remaining'] === '0';
+    })),
+    done('xidentity.rate.window_resets', 'rate', 'DIRTY-STATE: an exhausted window RESETS after its 15 minutes — the same token is served again in the next window', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        await h({ m: 'POST', p: '/_twin/rate_limit', b: JSON.stringify({ account_id: ADA.id, used: 75 }) });
+        const blocked = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` } });
+        const next = await h({ m: 'GET', p: '/2/users/me', h: { authorization: `Bearer ${tokens['access_token']}` }, at: atPlus(901) });
+        return blocked.status === 429 && next.status === 200 && next.headers?.['x-rate-limit-remaining'] === '74';
+    })),
+    todo('xidentity.rate.what_counts', 'rate', 'PIN which outcomes spend the window on the live vendor (the twin counts 200s only; 4xx are free, unpinned)', 'api', 'niche'),
+    todo('xidentity.rate.per_app_windows', 'rate', 'Model per-APP rate windows for endpoints that document them (users/me documents per-user only)', 'api', 'niche'),
+    // ═══ errors / router ══════════════════════════════════════════════════════════════════════
+    done('xidentity.errors.unmodeled_404_problem', 'errors', 'An unmodelled /2 route fails like the vendor: the 404 problem envelope (REPORTED shape, pinned by errors.not_found_envelope_pin), never a fake success', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/2/users/by?usernames=ada_twin' });
+        const b = body(r);
+        return r.status === 404 && b['title'] === 'Not Found Error' && b['type'] === 'about:blank' && b['status'] === 404;
+    })),
+    done('xidentity.errors.wrong_method_404', 'errors', 'A wrong method on a modelled path is refused with the not-found envelope, not served', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/2/users/me', b: '{}' });
+        return r.status === 404 && body(r)['title'] === 'Not Found Error';
+    })),
+    done('xidentity.errors.malformed_client_auth_contained', 'errors', 'A Basic credential whose percent-decoding blows up becomes the vendor\'s own 400 OAuth envelope (the route-boundary guard), never an escaped 500', 'api', 'niche', () => withRoot(async (h) => {
+        // base64("client%E0%A4%A:secret") — decodeURIComponent throws URIError on the client half.
+        const evil = `Basic ${Buffer.from('client%E0%A4%A:secret').toString('base64')}`;
+        const r = await h({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code: 'x', redirect_uri: REDIRECT, code_verifier: VERIFIER }), h: { authorization: evil } });
+        return r.status === 400 && body(r)['error'] === 'invalid_request';
+    })),
+    todo('xidentity.errors.problem_family', 'errors', 'Model the remaining OpenAPI Problem subtypes (not-authorized-for-field, field-hydration-failure, resource-unavailable, …) on the surfaces that emit them', 'api', 'niche'),
+    todo('xidentity.errors.auth_envelope_pin', 'errors', 'PIN the live 401 body for a bad/absent bearer (the twin serves the reported about:blank problem shape the bearer_required/unknown_token verifies assert)', 'api', 'common'),
+    todo('xidentity.errors.not_found_envelope_pin', 'errors', 'PIN the live 404 body for an unmodelled /2 route (the twin serves the reported "Not Found Error" about:blank shape)', 'api', 'niche'),
+    // ═══ scopes catalog ═══════════════════════════════════════════════════════════════════════
+    done('xidentity.scopes.catalog_is_vendor_verbatim', 'scopes', 'The scope catalog bijects with the vendor\'s: the OpenAPI\'s 24 OAuth2UserToken scopes plus the announcement-added users.email, and nothing else (literal list, so drift in EITHER direction goes red)', 'api', 'core', async () => {
+        // The 24 scopes from api.x.com/2/openapi.json (2.167) securitySchemes — a LITERAL, never an
+        // import of the catalog under test (the two-constants tautology §6 names). `users.email` is
+        // NOT in that artefact: it comes from X's April-2025 email-retrieval announcement (see
+        // xidentity-scopes.ts) — a recorded intra-vendor discrepancy, asserted separately.
+        const OPENAPI_SCOPES = [
+            'block.read', 'block.write', 'bookmark.read', 'bookmark.write', 'broadcast.read', 'broadcast.write',
+            'dm.read', 'dm.write', 'follows.read', 'follows.write', 'like.read', 'like.write', 'list.read',
+            'list.write', 'media.write', 'mute.read', 'mute.write', 'offline.access', 'space.read',
+            'timeline.read', 'tweet.moderate.write', 'tweet.read', 'tweet.write', 'users.read',
+        ];
+        const { SCOPE_CATALOG } = await import("./xidentity-scopes.js");
+        const have = Object.keys(SCOPE_CATALOG).sort();
+        return have.length === 25 && OPENAPI_SCOPES.every((s) => have.includes(s)) && have.includes('users.email')
+            && SCOPE_CATALOG['users.read'].label === 'View any account you can see, including protected accounts.'
+            && SCOPE_CATALOG['dm.write'].label === 'Send and manage your Direct Messages.';
+    }),
+    done('xidentity.scopes.space_separated', 'scopes', 'The scope parameter is space-separated on the wire (the docs\' example: scope=tweet.read%20users.read…) and the token response echoes it space-joined', 'api', 'common', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { params: { scope: 'users.read tweet.read' } });
+        return r.status === 200 && r.tokens['scope'] === 'users.read tweet.read';
+    })),
+    todo('xidentity.scopes.unknown_scope_live', 'scopes', 'PIN what the live authorize endpoint does with an unknown scope value (the twin renders it flagged on the screen rather than inventing a rejection)', 'api', 'niche'),
+    todo('xidentity.scopes.users_email_wording', 'scopes', 'PIN the consent screen\'s live wording for users.email (the label is twin prose; the scope itself is announcement-grounded)', 'ui', 'niche'),
+    // ═══ read-only twin ═══════════════════════════════════════════════════════════════════════
+    done('xidentity.readonly.writes_refused', 'readonly', 'A read-only twin refuses every credential-minting leg (405, protocol-shaped error body) — D3', 'api', 'common', () => withRoot(async (h) => {
+        await fullFlow(h); // seed a world first, through the ordinary write path
+        const ro = (s) => handleXIdentityTwinRequest({ method: s.m, path: s.p, ...(s.b !== undefined ? { body: s.b } : {}), root: h.root, origin: DEMO_ORIGIN, occurredAt: AT, readOnly: true });
+        const tok = await ro({ m: 'POST', p: '/2/oauth2/token', b: form({ grant_type: 'authorization_code', code: 'x', client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT, code_verifier: VERIFIER }) });
+        const rev = await ro({ m: 'POST', p: '/2/oauth2/revoke', b: form({ token: 'x', client_id: DEFAULT_CLIENT_ID }) });
+        return tok.status === 405 && body(tok)['error'] === 'temporarily_unavailable' && rev.status === 405;
+    })),
+    done('xidentity.readonly.reads_served', 'readonly', 'A read-only twin still serves GET /2/users/me over existing state (rate accounting suspended, headers intact)', 'api', 'niche', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await handleXIdentityTwinRequest({ method: 'GET', path: '/2/users/me', headers: { authorization: `Bearer ${tokens['access_token']}` }, root: h.root, occurredAt: AT, readOnly: true });
+        return r.status === 200 && body(r)['data']?.['id'] === ADA.id && r.headers?.['x-rate-limit-limit'] === '75';
+    })),
+    // ═══ conformance (the endpoint census with teeth) ═════════════════════════════════════════
+    done('xidentity.conformance.census', 'conformance', 'The conformance check passes: one real probe per claimed endpoint, the ROUTER_SURFACE census, the live round trip, and a reachability witness per resource type', 'api', 'core', async () => {
+        const report = await checkXIdentityConformance();
+        return report.ok && report.endpointsProbed === 4 && report.resourceTypesChecked === 9;
+    }),
+    // ═══ the authorize SCREEN (the vendor's own UI — data-coupled, per ADDING_A_TWIN.md §6) ═══
+    done('xidentity.ui.authorize_screen', 'ui', 'The authorize screen names the REGISTERED app and the SIGNED-IN account from the projection (data-coupled: a seeded client + persona appear on screen)', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        // Seed a THIRD persona and a SECOND client through the twin's own write paths, then sign the
+        // new persona in — the screen cannot be passing on the seeded defaults alone.
+        seed: async (h) => {
+            await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_id: 'QWNtZVNjaGVkdWxpbmc6MTpjaQ', client_secret: 'acme-secret', name: 'Acme Scheduling', client_type: 'confidential', redirect_uris: [REDIRECT] }) });
+            await h({ m: 'POST', p: '/_twin/accounts', b: JSON.stringify({ id: '9000000000000000003', username: 'katherine_twin', name: 'Katherine Johnson' }) });
+            await h({ m: 'POST', p: '/_twin/session', b: JSON.stringify({ account_id: '9000000000000000003' }) });
+        },
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ client_id: 'QWNtZVNjaGVkdWxpbmc6MTpjaQ' }) })),
+        assert: (markup) => markup.includes('Acme Scheduling')
+            && markup.includes('wants to access your X account')
+            && markup.includes('Katherine Johnson') && markup.includes('@katherine_twin')
+            && !markup.includes('Twin Demo App') && !markup.includes('@ada_twin'),
+    })),
+    done('xidentity.ui.scope_sections', 'ui', 'The screen groups scopes under "Things … can view" / "Things … can do" with X\'s own consent wording from the catalog (data-coupled to the auth request)', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ scope: 'tweet.read dm.write offline.access' }) }),
+        fetch: async (h) => {
+            const a = await h({ m: 'GET', p: authUrl({ scope: 'tweet.read dm.write offline.access' }) });
+            const rid = AUTH_REQUEST_RE.exec(html(a))?.[1] ?? '';
+            return html(await h({ m: 'GET', p: `/_twin/consent?auth_request=${rid}` }));
+        },
+        assert: (markup) => markup.includes('can view')
+            && markup.includes('can do')
+            && markup.includes('View all posts you can see, including those from protected accounts.')
+            && markup.includes('Send and manage your Direct Messages.')
+            && markup.includes('Stay connected to your account until you revoke access.'),
+    })),
+    done('xidentity.ui.decision_buttons', 'ui', 'The screen\'s two decisions are REAL form submits — "Authorize app" and "Cancel" carry decision values into the twin\'s consent post', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl() }),
+        fetch: async (h) => {
+            const a = await h({ m: 'GET', p: authUrl() });
+            const rid = AUTH_REQUEST_RE.exec(html(a))?.[1] ?? '';
+            return html(await h({ m: 'GET', p: `/_twin/consent?auth_request=${rid}` }));
+        },
+        // Attribute ORDER is the renderer's business (React emits value before name) — assert each
+        // decision button as a whole tag, order-independent within it.
+        assert: (markup) => /<button[^>]*value="allow"[^>]*>Authorize app<\/button>/.test(markup)
+            && /<button[^>]*value="deny"[^>]*>Cancel<\/button>/.test(markup)
+            && (markup.match(/name="decision"/g) ?? []).length === 2
+            && markup.includes('/_twin/consent'),
+    })),
+    done('xidentity.ui.redirect_notice', 'ui', 'The screen shows WHERE the browser will be sent — the validated redirect_uri\'s host, from the auth request (data-coupled: the SECOND registered callback\'s host, so a hardcoded first/default host fails)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ redirect_uri: REDIRECT_URIS[1] }) }),
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ redirect_uri: REDIRECT_URIS[1] }) })),
+        // §9 round one: asserting the FIRST registered callback's host could not discriminate a
+        // data-coupled notice from a hardcoded one. The request names the second (127.0.0.1) and
+        // the first's host must be ABSENT.
+        // Both hosts are DERIVED from the registered callbacks, never named as ports here (R7).
+        // The assertion is pinned to the NOTICE ELEMENT itself rather than the whole page: the twin
+        // is served at the first callback's origin, so that host also appears in the consent form's
+        // own action — a whole-markup `!includes` would now fail for a reason unrelated to coupling.
+        assert: (markup) => markup.includes('redirected to')
+            && markup.includes(`class="redirect-host">${new URL(REDIRECT_URIS[1]).host}<`)
+            && !markup.includes(`class="redirect-host">${new URL(REDIRECT_URIS[0]).host}<`),
+    })),
+    done('xidentity.ui.unknown_scope_flagged', 'ui', 'A scope outside the vendor catalog renders VISIBLY FLAGGED rather than silently or prettily (a typo\'d scope is a real integration bug)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ scope: 'tweet.read totally.bogus' }) }),
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ scope: 'tweet.read totally.bogus' }) })),
+        assert: (markup) => markup.includes('totally.bogus') && markup.includes('not in the twin&#x27;s scope catalog'),
+    })),
+    done('xidentity.ui.consent_state_renders_real_component', 'ui', 'The SHIPPED ConsentPage component renders the twin\'s OWN view model (the same state builder the served page uses) — one renderer, no lookalike', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ scope: 'tweet.read users.read' }) }),
+        fetch: async (h) => {
+            const a = await h({ m: 'GET', p: authUrl({ scope: 'tweet.read users.read' }) });
+            const rid = AUTH_REQUEST_RE.exec(html(a))?.[1] ?? '';
+            return xIdentityConsentState({ root: h.root, requestId: rid, origin: 'https://x.com' });
+        },
+        render: (view) => (view ? renderToStaticMarkup(createElement(ConsentPage, { view })) : ''),
+        assert: (view, markup) => !!view && !!markup
+            && view.scopes.length === 2
+            && view.account.username === ADA.username
+            && markup.includes('View any account you can see, including protected accounts.')
+            && markup.includes(`@${ADA.username}`),
+    })),
+    done('xidentity.ui.error_page_renders_real_component', 'ui', 'The authorize endpoint SERVES the real ErrorPage component for an un-redirectable failure (driven through the handler, not a lookalike render)', 'ui', 'common', () => 
+    // §9 round one: rendering the component over literal props proved the component, not the
+    // route. This drives the failure the way a browser hits it and asserts the SERVED markup.
+    withRoot(async (h) => {
+        const served = await h({ m: 'GET', p: authUrl({ client_id: 'bm90LWEtcmVhbC1jbGllbnQ6MTpjaQ' }) });
+        // The SERVED page must literally CONTAIN the real component's own render for the same
+        // failure facts — a hand-rolled template carrying the same headline strings cannot pass
+        // (§9 round two: asserting the direct render only against itself was a tautology).
+        const direct = renderToStaticMarkup(createElement(ErrorPage, {
+            status: 401,
+            code: 'invalid_client',
+            detail: 'The client_id does not name a known App.',
+            requestParam: 'client_id=bm90LWEtcmVhbC1jbGllbnQ6MTpjaQ',
+        }));
+        return served.status === 401
+            && html(served).includes('Something went wrong')
+            && html(served).includes(direct);
+    })),
+    done('xidentity.ui.client_transpiles', 'ui', 'The consent client bundles for the browser (structural: the shipped TSX transpiles and carries the hydration entry)', 'ui', 'niche', async () => {
+        // The REAL bundle the twin serves — the COMMITTED xidentity-consent-client.gen.ts, which
+        // consent-clients.test.ts proves is a fresh build of the TSX.
+        const js = CONSENT_CLIENT_JS;
+        return js.length > 1000 && js.includes('consent-enhanced');
+    }),
+    // ═══ connector (dimension: connector — the saboteur phase keys on this) ═══════════════════
+    done('xidentity.connector.pull_identity', 'connector', 'Pull observes the real account behind the operator\'s token (real-shaped /2/users/me reply over an injected fake) and folds it into the twin — the persona then serves through the projection', 'connector', 'core', async () => verifyBoundary('xidentity.connector.pull_identity', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xidentity-conn-'));
+        try {
+            const n = await pullXIdentity(fakeExecute, root, '2026-02-01T00:00:01.000Z');
+            const { readOne } = await import("./xidentity-store.js");
+            const row = readOne(root, 'account', '2244994945');
+            return n === 1 && row?.username === 'XDevelopers' && row?.verifiedType === 'business'
+                && row?.publicMetrics?.followers_count === 583423 && row?.pulled === true;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('xidentity.connector.pull_idempotent', 'connector', 'A re-pull of identical vendor state appends NOTHING (shadow-diffed syncPull; deltasAppended 0 on the second pass)', 'connector', 'core', async () => verifyBoundary('xidentity.connector.pull_idempotent', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xidentity-conn-'));
+        try {
+            const first = await syncXIdentityFromReal(fakeExecute, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            const second = await syncXIdentityFromReal(fakeExecute, { root, occurredAt: '2026-02-01T00:00:02.000Z' });
+            return first.deltasAppended > 0 && second.deltasAppended === 0 && second.observed === 1;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('xidentity.connector.pull_requests_modeled_fields', 'connector', 'The pull asks for every modelled user.field (a default-field pull would silently observe a bald persona)', 'connector', 'common', async () => verifyBoundary('xidentity.connector.pull_requests_modeled_fields', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xidentity-conn-'));
+        const seen = [];
+        const recording = async (m, p) => {
+            seen.push(`${m} ${p}`);
+            return structuredClone(FAKE_USERS_ME);
+        };
+        try {
+            await pullXIdentity(recording, root, '2026-02-01T00:00:01.000Z');
+            const call = seen[0] ?? '';
+            return seen.length === 1 && call.startsWith('GET /2/users/me?user.fields=')
+                && ['created_at', 'profile_image_url', 'public_metrics', 'verified_type', 'confirmed_email'].every((f) => call.includes(f));
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('xidentity.connector.refused_pull_throws', 'connector', 'A REFUSED pull is NOT an empty account: a problem-envelope reply (even under HTTP 200) throws the REFUSAL instead of folding emptiness over observed state', 'connector', 'core', async () => verifyBoundary('xidentity.connector.refused_pull_throws', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xidentity-conn-'));
+        const refusing = async () => ({ title: 'Unauthorized', type: 'about:blank', status: 401, detail: 'Unauthorized' });
+        try {
+            // The HAPPY path must still work first — otherwise a dead connector that throws on
+            // EVERYTHING would satisfy the refusal expectation below (the mutation gate caught
+            // exactly that: a bare "it threw" is what a sabotaged pull also does).
+            const n = await pullXIdentity(fakeExecute, root, '2026-02-01T00:00:01.000Z');
+            if (n !== 1)
+                return false;
+            await pullXIdentity(refusing, root, '2026-02-01T00:00:02.000Z');
+            return false; // the refusal must throw
+        }
+        catch (e) {
+            // …and the throw must be the connector's OWN refusal, not an arbitrary failure.
+            if (!String(e).includes('refused'))
+                return false;
+            const { readOne, readType } = await import("./xidentity-store.js");
+            // The earlier good pull SURVIVES the refused one — nothing was folded over it.
+            return readType(root, 'account').length === 1 && readOne(root, 'account', '2244994945')?.username === 'XDevelopers';
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('xidentity.connector.mapping_invents_nothing', 'connector', 'The account mapping records ONLY what the reply disclosed — omitted optional fields stay absent, never placeholders, INCLUDING name/username', 'connector', 'common', async () => {
+        const mapped = mapUsersMeAccount({ data: { id: '99', name: 'Terse', username: 'terse' } });
+        const f = mapped.fields;
+        // …and a partial reply (id only — the shape a partial-errors response can take) must not
+        // fold null over a previously-pulled persona's real name/username (§9 round one).
+        const partial = mapUsersMeAccount({ data: { id: '99' } });
+        const pf = partial.fields;
+        return mapped.id === '99' && f['username'] === 'terse'
+            && !('createdAt' in f) && !('profileImageUrl' in f) && !('publicMetrics' in f) && f['pulled'] === true
+            && !('username' in pf) && !('name' in pf) && pf['pulled'] === true;
+    }),
+    done('xidentity.connector.budget_enforced', 'connector', 'The live executor is fail-closed: at the burst ceiling the next call THROWS with the injected fetch\'s call count UNCHANGED (counted on the fake — nothing reached the vendor)', 'connector', 'core', async () => verifyBoundary('xidentity.connector.budget_enforced', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xidentity-budget-'));
+        let calls = 0;
+        const fakeFetch = (async () => {
+            calls += 1;
+            return new Response(JSON.stringify(structuredClone(FAKE_USERS_ME)), { status: 200, headers: { 'content-type': 'application/json' } });
+        });
+        try {
+            const clock = { t: 1_700_000_000_000 };
+            const execute = liveXIdentityExecute('cap-test-token', { fetchImpl: fakeFetch, budgetOptions: { path: join(root, 'ledger.json'), now: () => clock.t } });
+            for (let i = 0; i < XIDENTITY_BUDGET_BURST_CEILING; i += 1)
+                await execute('GET', '/2/users/me');
+            if (calls !== XIDENTITY_BUDGET_BURST_CEILING)
+                return false;
+            try {
+                await execute('GET', '/2/users/me');
+                return false; // the ceiling must throw
+            }
+            catch (e) {
+                return e instanceof XIdentityBudgetError && calls === XIDENTITY_BUDGET_BURST_CEILING;
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('xidentity.connector.unmapped_path_refused', 'connector', 'The live executor refuses an unmapped X path OUTRIGHT — zero requests issued (the raw-vendor-call ban, D8)', 'connector', 'common', async () => verifyBoundary('xidentity.connector.unmapped_path_refused', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xidentity-budget-'));
+        let calls = 0;
+        const fakeFetch = (async () => {
+            calls += 1;
+            return new Response('{}', { status: 200 });
+        });
+        try {
+            const execute = liveXIdentityExecute('cap-test-token', { fetchImpl: fakeFetch, budgetOptions: { path: join(root, 'ledger.json'), now: () => 1_700_000_000_000 } });
+            try {
+                await execute('GET', '/2/tweets/search/recent');
+                return false;
+            }
+            catch {
+                return calls === 0;
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('xidentity.connector.push_reports_impossible', 'connector', 'Push never fakes: X has no write API for this surface, so push confirms nothing and REPORTS the real pending count as unpushable', 'connector', 'common', () => 
+    // Runs inside withRoot so real local writes exist first — on a virgin root the pending count
+    // is zero BY CONSTRUCTION and "reports the pending count" would be unproven (§9 round one:
+    // deleting the pendingActions() read entirely stayed green against the old verify).
+    withRoot(async (h) => {
+        const before = pushPendingXIdentityActions(h.root);
+        const { status } = await fullFlow(h);
+        const after = pushPendingXIdentityActions(h.root);
+        return status === 200 && before.pushed === 0 && after.pushed === 0 && after.unpushable > before.unpushable;
+    })),
+    todo('xidentity.connector.push', 'connector', 'PUSH remains structurally impossible (X exposes no client/grant/user write API); revisit if X ever ships one', 'connector', 'niche'),
+    todo('xidentity.connector.pull_clients', 'connector', 'PULL the OAuth client registry — impossible today (X Apps live in the developer portal; no API reads them)', 'connector', 'niche'),
+    todo('xidentity.connector.pull_grants', 'connector', 'PULL the token\'s granted scope set — impossible today (X has no tokeninfo/introspection endpoint)', 'connector', 'niche'),
+    // ═══ adjacent X auth surface the identity twin does not model yet (honest denominator) ═════
+    todo('xidentity.app_only.bearer_token', 'app_only', 'Model the app-only bearer flow (POST /oauth2/token, grant_type=client_credentials, the v1.1 path)', 'api', 'common'),
+    todo('xidentity.app_only.invalidate_token', 'app_only', 'Model POST /oauth2/invalidate_token for app-only bearers', 'api', 'niche'),
+    todo('xidentity.oauth1.request_token', 'oauth1', 'Model OAuth 1.0a step 1: POST /oauth/request_token', 'api', 'niche'),
+    todo('xidentity.oauth1.authorize', 'oauth1', 'Model OAuth 1.0a step 2: GET /oauth/authorize (the legacy consent screen)', 'api', 'niche'),
+    todo('xidentity.oauth1.access_token', 'oauth1', 'Model OAuth 1.0a step 3: POST /oauth/access_token', 'api', 'niche'),
+];
+export function xidentityCapabilities() {
+    return checkCapabilities('xidentity', XIDENTITY_CAPABILITIES);
+}