@volter/twin-xai 0.1.0

package/dist/src/xai-capabilities.js

@@ -0,0 +1,1072 @@
+// xAI capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from what the xAI (Grok) API actually does — NOT from what this twin has built. This is the
+// honest denominator: entries the twin hasn't reached are `todo` and coverage reads partial
+// until the twin truly covers the API. `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 the API's *full* surface every cycle.
+//
+// THERE ARE NO CARVE-OUTS. Every inference endpoint returns a clearly-labeled deterministic
+// stub, Live Search returns deterministic labeled citations, and the image endpoint returns the
+// faithful shape with labeled placeholder URLs/bytes — those ARE this twin's answers, not
+// shortfalls from a "real" one. Every entry here is either done or todo. NOTE: xAI publishes NO embeddings endpoint (announced but not GA at
+// authoring time), so embeddings are deliberately ABSENT from this manifest — listing them
+// would be denominator padding, and the twin 404s the path exactly like the vendor. Scenario
+// scripting (xai-scenario.ts) is twin scaffolding, not vendor surface, and is likewise absent.
+//
+// xAI's console remains outside this API-first pack, but Grok Build device authorization is a
+// required browser leg of the OAuth protocol. Its entry/consent/result UI therefore receives the
+// same data-coupled capability and real-browser scrutiny as the dedicated identity twins.
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { projectResources } from '@volter/world-core';
+import { checkCapabilities, uiDataCoupled } from '@volter/world-tooling';
+import { DeviceConsentPage } from "../client/xai-device-auth.js";
+import { xaiDeviceAuthView } from "./xai-device-auth-ui.js";
+import { startXaiTwinDeviceAuthorization } from "./xai-oauth.js";
+import { createXaiTwinServer } from "./xai-server.js";
+import { handleXaiTwinRequest } from "./xai-twin.js";
+const AT = '2026-01-01T00:00:00Z'; // pinned occurredAt → deterministic ids/timestamps
+/** Run a sequence of real xAI requests against an isolated root; return all responses. */
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'xai-cap-'));
+    const h = (s) => handleXaiTwinRequest({ method: s.m, path: s.p, body: s.raw ?? (s.b === undefined ? undefined : JSON.stringify(s.b)), root, occurredAt: AT, origin: 'http://127.0.0.1:4000' });
+    try {
+        return await steps(h);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** Collect the streaming SSE events for a chat request against an isolated root. */
+function withStream(body, fn) {
+    return new Promise((resolve) => {
+        const root = mkdtempSync(join(tmpdir(), 'xai-cap-'));
+        const events = [];
+        handleXaiTwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify(body), root, occurredAt: AT, sseSink: (e) => events.push(e) })
+            .then((final) => resolve(fn(events, final)))
+            .catch(() => resolve(false))
+            .finally(() => rmSync(root, { recursive: true, force: true }));
+    });
+}
+async function withRootH(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'xai-cap-'));
+    const h = (s) => handleXaiTwinRequest({ method: s.m, path: s.p, body: s.raw ?? (s.b === undefined ? undefined : JSON.stringify(s.b)), root, occurredAt: AT, origin: 'http://127.0.0.1:4000', ...(s.headers ? { headers: s.headers } : {}), ...(s.requireTwinOauth === undefined ? {} : { requireTwinOauth: s.requireTwinOauth }) });
+    try {
+        return await steps(h, root);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+function withUiRoot(steps) {
+    return withRootH((request, root) => steps({ request, root }));
+}
+async function withLiveUi(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'xai-cap-ui-'));
+    const server = await createXaiTwinServer({ root, port: 0 });
+    try {
+        return await steps(`http://127.0.0.1:${server.port}`, root);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        server.stop();
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+function pendingCode(root) {
+    return String(projectResources('xai', root).find((resource) => resource.type === 'oauth_device_authorization' && resource.status === 'pending')?.user_code ?? '');
+}
+const ok = (r) => r.status >= 200 && r.status < 300;
+const id = (r) => r.body?.id;
+// xAI errors are FLAT { code, error } strings — assert the shape, not just the status.
+const flatError = (r) => typeof r.body?.code === 'string' && typeof r.body?.error === 'string';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// ── shorthands (mirror the openai/anthropic 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' });
+const CHAT = (extra = {}) => ({ model: 'grok-4-0709', messages: [{ role: 'user', content: 'hello twin' }], ...extra });
+export const XAI_CAPABILITIES = [
+    todo('xai.images.served_bytes', 'images', 'Image URLs resolve: serve deterministic placeholder image bytes at the URLs /v1/images/generations returns (today they point at a host that answers nothing)', 'api', 'common'),
+    // ── Grok Build OAuth / account world ─────────────────────────────────────────────────
+    done('xai.oauth.device_authorization', 'oauth', 'Device authorization: issue → pending → user approval → one-use exchange', 'api', 'core', () => withRoot(async (h) => {
+        const start = await h({ m: 'POST', p: '/oauth2/device/code', raw: new URLSearchParams({ client_id: 'grok-build', scope: 'openid offline_access grok-cli:access' }).toString() });
+        const body = start.body;
+        if (!ok(start) || typeof body.device_code !== 'string' || !String(body.verification_uri_complete).includes(String(body.user_code)))
+            return false;
+        const pending = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', device_code: body.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }).toString() });
+        if (pending.status !== 400 || pending.body.error !== 'authorization_pending')
+            return false;
+        const approved = await h({ m: 'POST', p: '/twin/oauth/authorizations', b: { approved: true, user_code: body.user_code } });
+        const wrongClient = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'other-client', device_code: body.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }).toString() });
+        const token = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', device_code: body.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }).toString() });
+        const replay = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', device_code: body.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }).toString() });
+        return ok(approved) && wrongClient.status === 400 && wrongClient.body.error === 'invalid_grant'
+            && ok(token) && typeof token.body.access_token === 'string' && replay.status === 400;
+    })),
+    done('xai.oauth.refresh', 'oauth', 'Refresh rotates the access token while retaining the virtual account and refresh authority', 'api', 'core', () => withRoot(async (h) => {
+        const start = await h({ m: 'POST', p: '/oauth2/device/code', raw: new URLSearchParams({ client_id: 'grok-build', scope: 'offline_access grok-cli:access' }).toString() });
+        const device = start.body;
+        await h({ m: 'POST', p: '/twin/oauth/authorizations', b: { approved: true, user_code: device.user_code } });
+        const first = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', device_code: device.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }).toString() });
+        const credential = first.body;
+        const wrongClient = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'other-client', grant_type: 'refresh_token', refresh_token: credential.refresh_token }).toString() });
+        const refreshed = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', grant_type: 'refresh_token', refresh_token: credential.refresh_token }).toString() });
+        const replay = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', grant_type: 'refresh_token', refresh_token: credential.refresh_token }).toString() });
+        const next = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', grant_type: 'refresh_token', refresh_token: refreshed.body.refresh_token }).toString() });
+        return wrongClient.status === 400 && wrongClient.body.error === 'invalid_grant'
+            && ok(refreshed) && refreshed.body.refresh_token !== credential.refresh_token
+            && refreshed.body.access_token !== credential.access_token && replay.status === 400
+            && ok(next) && next.body.refresh_token !== refreshed.body.refresh_token;
+    })),
+    todo('xai.cli_oauth.direct_device_redirect', 'oauth', 'Direct `grok login --device-auth` redirection to a sealed Twin origin (the official CLI fixes this device-login origin; brokered external auth is the supported seam)', 'api', 'common'),
+    // ── Grok Build device UI (the vendor-owned browser leg of the OAuth protocol) ─────────
+    done('xai.ui.device_entry', 'ui', 'The device-entry screen renders the issued code in a labeled field and advances through a real form POST', 'ui', 'core', async () => await withLiveUi(async (origin) => {
+        const start = await fetch(`${origin}/oauth2/device/code`, { method: 'POST', body: new URLSearchParams({ client_id: 'grok-build', scope: 'openid grok-cli:access' }) });
+        const issued = await start.json();
+        const entry = await fetch(String(issued.verification_uri_complete));
+        const markup = await entry.text();
+        if (entry.status !== 200 || !markup.includes('Sign in to Grok Build') || !markup.includes(`value="${String(issued.user_code)}"`)
+            || !markup.includes('name="user_code"') || !markup.includes('/oauth2/device/continue')
+            || !markup.includes('viewBox="0 0 834 318"') || !markup.includes('SpaceXAI account home link'))
+            return false;
+        const submitted = await fetch(`${origin}/oauth2/device/continue`, {
+            method: 'POST', redirect: 'manual', body: new URLSearchParams({ user_code: String(issued.user_code) }),
+        });
+        const location = submitted.headers.get('location') ?? '';
+        return submitted.status === 303 && new URL(location).pathname === '/oauth2/device/consent'
+            && new URL(location).searchParams.get('user_code') === issued.user_code;
+    })),
+    done('xai.ui.invalid_device_code', 'ui', 'Blank entry is disabled and an invalid or expired code follows the official clear-field PRG error state', 'ui', 'core', async () => await withLiveUi(async (origin, root) => {
+        const blank = await fetch(`${origin}/oauth2/device`);
+        const blankMarkup = await blank.text();
+        if (!blankMarkup.includes('placeholder="Enter device code"') || !/<button(?=[^>]*disabled)[^>]*>Continue<\/button>/.test(blankMarkup))
+            return false;
+        const submitted = await fetch(`${origin}/oauth2/device/continue`, {
+            method: 'POST', redirect: 'manual', body: new URLSearchParams({ user_code: 'NOPE-0000' }),
+        });
+        const location = submitted.headers.get('location') ?? '';
+        if (submitted.status !== 303 || new URL(location).pathname !== '/oauth2/device' || new URL(location).search !== '?error=invalid_code')
+            return false;
+        const invalid = await fetch(location);
+        const markup = await invalid.text();
+        if (invalid.status !== 200 || !markup.includes('Invalid or expired code. Please try again.')
+            || markup.includes('value="NOPE-0000"') || !/<button(?=[^>]*disabled)[^>]*>Continue<\/button>/.test(markup))
+            return false;
+        const expired = await startXaiTwinDeviceAuthorization({
+            body: new URLSearchParams({ client_id: 'grok-build', scope: 'grok-cli:access' }),
+            occurredAt: '2000-01-01T00:00:00.000Z', origin, root,
+        });
+        const expiredCode = String(expired.body.user_code);
+        const expiredSubmit = await fetch(`${origin}/oauth2/device/continue`, {
+            method: 'POST', redirect: 'manual', body: new URLSearchParams({ user_code: expiredCode }),
+        });
+        const expiredLocation = expiredSubmit.headers.get('location') ?? '';
+        const expiredPage = await fetch(expiredLocation);
+        const expiredMarkup = await expiredPage.text();
+        return expiredSubmit.status === 303 && new URL(expiredLocation).search === '?error=invalid_code'
+            && expiredPage.status === 200 && expiredMarkup.includes('Invalid or expired code. Please try again.')
+            && !expiredMarkup.includes(`value="${expiredCode}"`) && /<button(?=[^>]*disabled)[^>]*>Continue<\/button>/.test(expiredMarkup);
+    })),
+    done('xai.ui.consent_scope_projection', 'ui', 'The consent screen derives vendor-visible permission rows from the pending request scope instead of a static lookalike', 'ui', 'core', uiDataCoupled({
+        withRoot: withUiRoot,
+        seed: ({ request }) => request({ m: 'POST', p: '/oauth2/device/code', raw: new URLSearchParams({ client_id: 'grok-build', scope: 'openid email grok-cli:access' }).toString() }),
+        fetch: async ({ root }) => xaiDeviceAuthView(pendingCode(root), root, undefined, AT),
+        render: (view) => renderToStaticMarkup(createElement(DeviceConsentPage, { view })),
+        assert: (view, markup) => view.permissions.length === 3 && !!markup
+            && markup.includes('Verify your identity') && markup.includes('Read your email address') && markup.includes('Use the xAI API')
+            && !markup.includes('Read your profile (name, avatar)') && !markup.includes("Maintain access when you&#x27;re not present")
+            && !markup.includes('Read and write access Grok.com'),
+    })),
+    done('xai.ui.consent_decisions', 'ui', 'Deny and Allow are real named form submits carrying the projected device code into the OAuth decision route', 'ui', 'core', async () => await withLiveUi(async (origin, root) => {
+        const start = await fetch(`${origin}/oauth2/device/code`, { method: 'POST', body: new URLSearchParams({ client_id: 'grok-build', scope: 'openid profile email offline_access grok-cli:access api:access conversations:write' }) });
+        const issued = await start.json();
+        const consent = await fetch(`${origin}/oauth2/device/consent?user_code=${encodeURIComponent(String(issued.user_code))}`);
+        const markup = await consent.text();
+        if (consent.status !== 200 || !markup.includes('/oauth2/device/decision') || !markup.includes(`value="${String(issued.user_code)}"`)
+            || !/<button(?=[^>]*name="decision")(?=[^>]*value="deny")[^>]*>Deny<\/button>/.test(markup)
+            || !/<button(?=[^>]*name="decision")(?=[^>]*value="approve")[^>]*>Allow<\/button>/.test(markup))
+            return false;
+        const denied = await fetch(`${origin}/oauth2/device/decision`, { method: 'POST', redirect: 'manual', body: new URLSearchParams({ decision: 'deny', user_code: String(issued.user_code) }) });
+        const location = denied.headers.get('location') ?? '';
+        const done = await fetch(location);
+        const doneMarkup = await done.text();
+        const state = xaiDeviceAuthView(String(issued.user_code), root);
+        if (denied.status !== 303 || new URL(location).pathname !== '/oauth2/device/done'
+            || state.status !== 'denied' || done.status !== 200 || !doneMarkup.includes('Authorization Denied'))
+            return false;
+        const approveStart = await fetch(`${origin}/oauth2/device/code`, { method: 'POST', body: new URLSearchParams({ client_id: 'grok-build', scope: 'openid grok-cli:access' }) });
+        const approveIssued = await approveStart.json();
+        const allowed = await fetch(`${origin}/oauth2/device/decision`, { method: 'POST', redirect: 'manual', body: new URLSearchParams({ decision: 'approve', user_code: String(approveIssued.user_code) }) });
+        const allowedLocation = allowed.headers.get('location') ?? '';
+        const allowedDone = await fetch(allowedLocation);
+        const allowedMarkup = await allowedDone.text();
+        return allowed.status === 303 && new URL(allowedLocation).pathname === '/oauth2/device/done'
+            && xaiDeviceAuthView(String(approveIssued.user_code), root).status === 'approved'
+            && allowedDone.status === 200 && allowedMarkup.includes('Device Authorized');
+    })),
+    done('xai.ui.account_shell_sign_out', 'ui', 'The vendor-shaped account sign-out route leaves the pending OAuth grant undecided and returns to blank device entry', 'ui', 'common', async () => await withLiveUi(async (origin, root) => {
+        const start = await fetch(`${origin}/oauth2/device/code`, { method: 'POST', body: new URLSearchParams({ client_id: 'grok-build', scope: 'openid grok-cli:access' }) });
+        const issued = await start.json();
+        const consent = await fetch(`${origin}/oauth2/device/consent?user_code=${encodeURIComponent(String(issued.user_code))}`);
+        const markup = await consent.text();
+        if (!markup.includes('/sign-out?redirect=oauth2-provider&amp;return_to='))
+            return false;
+        const href = markup.match(/href="([^"]*\/sign-out[^"]*)"/)?.[1]?.replaceAll('&amp;', '&');
+        if (!href)
+            return false;
+        const signOutUrl = new URL(href, origin);
+        if (signOutUrl.pathname !== '/sign-out' || signOutUrl.searchParams.get('redirect') !== 'oauth2-provider'
+            // every link on the device pages is built from the World's public base (6c6ad4b2b), return_to included
+            || signOutUrl.searchParams.get('return_to') !== `${origin}/oauth2/device/consent?user_code=${String(issued.user_code)}`)
+            return false;
+        const signOut = await fetch(signOutUrl, { redirect: 'manual' });
+        const location = signOut.headers.get('location') ?? '';
+        return signOut.status === 303 && new URL(location).pathname === '/oauth2/device'
+            && xaiDeviceAuthView(String(issued.user_code), root).status === 'pending';
+    })),
+    done('xai.ui.completion_state', 'ui', 'The Twin-local completion route derives Device Authorized from the approved OAuth row, never from a query marker', 'ui', 'common', async () => await withLiveUi(async (origin, root) => {
+        const start = await fetch(`${origin}/oauth2/device/code`, { method: 'POST', body: new URLSearchParams({ client_id: 'grok-build', scope: 'openid grok-cli:access' }) });
+        const issued = await start.json();
+        await fetch(`${origin}/oauth2/device/decision`, { method: 'POST', redirect: 'manual', body: new URLSearchParams({ decision: 'approve', user_code: String(issued.user_code) }) });
+        const approved = await fetch(`${origin}/oauth2/device/done?user_code=${encodeURIComponent(String(issued.user_code))}`);
+        const approvedMarkup = await approved.text();
+        const forged = await fetch(`${origin}/oauth2/device/done?approved=true&user_code=NOT-REAL`);
+        const forgedMarkup = await forged.text();
+        const state = xaiDeviceAuthView(String(issued.user_code), root);
+        return state.status === 'approved' && approved.status === 200 && approvedMarkup.includes('Device Authorized')
+            && approvedMarkup.includes('Return to your terminal to continue.') && forged.status === 404 && !forgedMarkup.includes('Device Authorized');
+    })),
+    // ── Chat Completions (the OpenAI-compatible envelope + xAI deltas — faithful) ──────────
+    done('xai.chat.create', 'chat', 'Chat: create → faithful envelope (UUID id/object/created/model/choices/usage details)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        if (b.object !== 'chat.completion' || b.model !== 'grok-4-0709' || typeof b.created !== 'number')
+            return false;
+        if (!UUID_RE.test(String(b.id)))
+            return false; // xAI ids are UUID-formatted, not 'chatcmpl-…'
+        const c = b.choices?.[0];
+        if (!c || c.message?.role !== 'assistant' || typeof c.message?.content !== 'string' || c.finish_reason !== 'stop')
+            return false;
+        const u = b.usage;
+        if (typeof u?.prompt_tokens !== 'number' || u.total_tokens !== u.prompt_tokens + u.completion_tokens)
+            return false;
+        // the xAI usage detail objects must be PRESENT and populated — typed check, so a missing
+        // detail object cannot slip past an optional-chained comparison (§9 hardening)
+        if (typeof u.prompt_tokens_details?.text_tokens !== 'number' || u.prompt_tokens_details.text_tokens <= 0)
+            return false;
+        return typeof u.completion_tokens_details?.reasoning_tokens === 'number' && typeof u.num_sources_used === 'number';
+    })),
+    done('xai.chat.stub_labeled', 'chat', 'Stub completion is clearly labeled as a twin stub (not real Grok output)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const text = r.body.choices?.[0]?.message?.content;
+        return ok(r) && text.includes('[twin-stub') && text.includes('hello twin');
+    })),
+    done('xai.cli_proxy.grok_build', 'cli_proxy', 'Official Grok CLI proxy token marker + x-grok-model-override route the built-in grok-build model', 'api', 'core', () => withRootH(async (h, root) => {
+        const start = await h({ m: 'POST', p: '/oauth2/device/code', raw: new URLSearchParams({ client_id: 'grok-build', scope: 'offline_access grok-cli:access' }).toString() });
+        const device = start.body;
+        await h({ m: 'POST', p: '/twin/oauth/authorizations', b: { approved: true, user_code: device.user_code } });
+        const exchange = await h({ m: 'POST', p: '/oauth2/token', raw: new URLSearchParams({ client_id: 'grok-build', device_code: device.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }).toString() });
+        const accessToken = String(exchange.body.access_token);
+        const okResponse = await h({
+            m: 'POST',
+            p: '/v1/chat/completions',
+            b: CHAT({ model: 'ignored-by-cli-proxy' }),
+            headers: {
+                authorization: `Bearer ${accessToken}`,
+                'x-grok-model-override': 'grok-build',
+                'x-xai-token-auth': 'xai-grok-cli',
+            },
+            requireTwinOauth: true,
+        });
+        if (okResponse.status !== 200 || okResponse.body.model !== 'grok-code-fast-1')
+            return false;
+        const usage = projectResources('xai', root).find((resource) => resource.type === 'oauth_usage');
+        if (usage?.requests !== 1 || Number(usage.total_tokens) <= 0)
+            return false;
+        const wrongMarker = await h({
+            m: 'POST',
+            p: '/v1/chat/completions',
+            b: CHAT(),
+            headers: { authorization: `Bearer ${accessToken}`, 'x-xai-token-auth': 'wrong' },
+        });
+        const missingMarker = await h({
+            m: 'POST',
+            p: '/v1/chat/completions',
+            b: CHAT(),
+            headers: { authorization: 'Bearer foreign-token', 'x-grok-model-override': 'grok-build' },
+            requireTwinOauth: true,
+        });
+        const foreignBearer = await h({
+            m: 'POST',
+            p: '/v1/chat/completions',
+            b: CHAT(),
+            headers: { authorization: 'Bearer foreign-token', 'x-grok-model-override': 'grok-build', 'x-xai-token-auth': 'xai-grok-cli' },
+            requireTwinOauth: true,
+        });
+        return wrongMarker.status === 401 && String(wrongMarker.body.error).includes('token-auth marker')
+            && missingMarker.status === 401 && String(missingMarker.body.error).includes('token-auth marker')
+            && foreignBearer.status === 401 && String(foreignBearer.body.error).includes('sealed xAI Twin world');
+    })),
+    done('xai.chat.validation', 'chat', 'Chat validation (model required, non-empty messages) → flat {code,error} 400', 'api', 'core', () => withRoot(async (h) => {
+        const noModel = await h({ m: 'POST', p: '/v1/chat/completions', b: { messages: [{ role: 'user', content: 'x' }] } });
+        const noMsg = await h({ m: 'POST', p: '/v1/chat/completions', b: { model: 'grok-4-0709' } });
+        const empty = await h({ m: 'POST', p: '/v1/chat/completions', b: { model: 'grok-4-0709', messages: [] } });
+        if (noModel.status !== 400 || noMsg.status !== 400 || empty.status !== 400)
+            return false;
+        // the envelope is xAI's FLAT {code, error} strings — never OpenAI's nested error object
+        return flatError(noModel) && noModel.body.code === 'Client specified an invalid argument';
+    })),
+    done('xai.chat.model_not_found', 'chat', 'Unknown model → vendor 404 ("does not exist or your team has no access")', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-99' }) });
+        if (r.status !== 404 || !flatError(r))
+            return false;
+        const b = r.body;
+        if (b.code !== 'Some requested entity was not found' || !String(b.error).includes('grok-99'))
+            return false;
+        // an image model cannot chat (400, not a fake completion)
+        const img = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-2-image-1212' }) });
+        return img.status === 400;
+    })),
+    done('xai.chat.n_choices', 'chat', 'Chat: n returns multiple choices (indexed)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ n: 3 }) });
+        const choices = r.body.choices;
+        if (!ok(r) || choices.length !== 3 || choices[0].index !== 0 || choices[2].index !== 2)
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ n: 0 }) });
+        return bad.status === 400;
+    })),
+    done('xai.chat.max_tokens', 'chat', 'Chat: max_tokens/max_completion_tokens caps output (finish_reason length)', 'api', 'common', () => withRoot(async (h) => {
+        const long = { messages: [{ role: 'user', content: 'please produce a long answer that exceeds one token' }] };
+        const a = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 1, ...long }) });
+        const b = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_completion_tokens: 1, ...long }) });
+        if (!ok(a) || !ok(b))
+            return false;
+        if (a.body.choices[0].finish_reason !== 'length' || b.body.choices[0].finish_reason !== 'length')
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 0 }) });
+        return bad.status === 400;
+    })),
+    done('xai.chat.system_multi_turn', 'chat', 'Chat: system messages count toward prompt_tokens; multi-turn history accepted', 'api', 'common', () => withRoot(async (h) => {
+        const without = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const withSys = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'system', content: 'You are a careful, verbose assistant.' }, { role: 'user', content: 'hello twin' }] }) });
+        if (!ok(without) || !ok(withSys))
+            return false;
+        if (withSys.body.usage.prompt_tokens <= without.body.usage.prompt_tokens)
+            return false;
+        const multi = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'first' }, { role: 'assistant', content: 'reply' }, { role: 'user', content: 'second' }] }) });
+        return ok(multi) && multi.body.object === 'chat.completion' && multi.body.choices[0].message.content.includes('second');
+    })),
+    done('xai.chat.stop', 'chat', 'Chat: stop sequences truncate at the earliest hit', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stop: ['Echoing'] }) });
+        const text = r.body.choices[0].message.content;
+        if (!ok(r) || text.includes('Echoing') || text.length === 0)
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stop: 42 }) });
+        return bad.status === 400;
+    })),
+    done('xai.chat.deterministic_usage', 'chat', 'Chat: usage token counts + UUID id deterministic for a fixed request', 'api', 'common', () => withRoot(async (h) => {
+        const a = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const b = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        if (!ok(a) || !ok(b))
+            return false;
+        const ua = a.body.usage;
+        const ub = b.body.usage;
+        // usage must be a REAL populated token-count object, not just "the same as each other"
+        if (!ua || typeof ua.prompt_tokens !== 'number' || ua.prompt_tokens <= 0)
+            return false;
+        if (typeof ua.completion_tokens !== 'number' || ua.completion_tokens <= 0)
+            return false;
+        if (ua.total_tokens !== ua.prompt_tokens + ua.completion_tokens)
+            return false;
+        if (JSON.stringify(ua) !== JSON.stringify(ub))
+            return false;
+        const ida = id(a);
+        return typeof ida === 'string' && UUID_RE.test(ida) && ida === id(b);
+    })),
+    done('xai.chat.structured_outputs', 'chat', 'Structured outputs: response_format json_object / json_schema → valid JSON content', 'api', 'common', () => withRoot(async (h) => {
+        const obj = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json_object' } }) });
+        if (!ok(obj))
+            return false;
+        let parsedObj;
+        try {
+            parsedObj = JSON.parse(obj.body.choices[0].message.content);
+        }
+        catch {
+            return false;
+        }
+        if (typeof parsedObj !== 'object')
+            return false;
+        const schema = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json_schema', json_schema: { name: 'r', schema: { type: 'object', properties: { title: { type: 'string' }, count: { type: 'integer' }, ok: { type: 'boolean' } } } } } }) });
+        let parsed;
+        try {
+            parsed = JSON.parse(schema.body.choices[0].message.content);
+        }
+        catch {
+            return false;
+        }
+        if (!('title' in parsed) || typeof parsed.title !== 'string' || parsed.count !== 0 || parsed.ok !== false)
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'yaml' } }) });
+        return bad.status === 400;
+    })),
+    done('xai.chat.seed', 'chat', 'seed accepted + reflected (same seed deterministic; distinct seed → distinct id)', 'api', 'niche', () => withRoot(async (h) => {
+        const a = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 42 }) });
+        const a2 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 42 }) });
+        const b = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 7 }) });
+        if (!ok(a) || !ok(b))
+            return false;
+        if (id(a) !== id(a2) || id(a) === id(b))
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 1.5 }) });
+        return bad.status === 400 && flatError(bad);
+    })),
+    done('xai.chat.reasoning_effort', 'chat', 'reasoning_effort: grok-3-mini exposes reasoning_content + reasoning_tokens; grok-4 REJECTS the param (400) and never exposes content', 'api', 'common', () => withRoot(async (h) => {
+        // grok-3-mini + effort → reasoning_content (labeled stub) + effort-scaled reasoning_tokens
+        const hi = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-3-mini', reasoning_effort: 'high' }) });
+        const lo = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-3-mini', reasoning_effort: 'low' }) });
+        if (!ok(hi) || !ok(lo))
+            return false;
+        const hiMsg = hi.body.choices[0].message;
+        if (typeof hiMsg.reasoning_content !== 'string' || !hiMsg.reasoning_content.includes('[twin-stub'))
+            return false;
+        const hiRt = hi.body.usage.completion_tokens_details.reasoning_tokens;
+        const loRt = lo.body.usage.completion_tokens_details.reasoning_tokens;
+        if (!(hiRt > loRt) || loRt <= 0)
+            return false;
+        // reasoning tokens are COUNTED INTO completion_tokens (vendor accounting)
+        if (hi.body.usage.completion_tokens <= hiRt)
+            return false;
+        // grok-4: a reasoning model that REJECTS reasoning_effort and hides the trace
+        const g4bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning_effort: 'high' }) });
+        if (g4bad.status !== 400 || !String(g4bad.body.error).includes('reasoning_effort'))
+            return false;
+        const g4 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        if (g4.body.choices[0].message.reasoning_content !== undefined)
+            return false;
+        if (g4.body.usage.completion_tokens_details.reasoning_tokens <= 0)
+            return false;
+        // grok-3-mini WITHOUT the param still exposes its (stubbed) reasoning trace — the model
+        // always thinks; the param only scales the budget (§9 hardening).
+        const noParam = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-3-mini' }) });
+        if (typeof noParam.body.choices[0].message.reasoning_content !== 'string')
+            return false;
+        // invalid effort value → 400
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-3-mini', reasoning_effort: 'medium' }) });
+        return bad.status === 400;
+    })),
+    done('xai.chat.content_parts', 'chat', 'Chat: content-part array input (text + image_url vision parts → image_tokens counted)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: [{ type: 'text', text: 'describe this' }, { type: 'image_url', image_url: { url: 'data:image/png;base64,iVBORw0KGgo=' } }] }] }) });
+        if (!ok(r))
+            return false;
+        const d = r.body.usage.prompt_tokens_details;
+        return d.image_tokens > 0 && d.text_tokens > 0 && r.body.usage.prompt_tokens === d.text_tokens + d.image_tokens;
+    })),
+    // ── Streaming ─────────────────────────────────────────────────────────────────────────
+    done('xai.streaming.chunks', 'streaming', 'Streaming chat.completion.chunk sequence ends with [DONE]', 'api', 'core', () => withStream(CHAT({ stream: true }), (events) => {
+        const data = events.filter((e) => !e.done);
+        // vendor ordering: the FIRST chunk carries the role delta (§9 hardening: pinned, not just present)
+        const roleFirst = (data[0]?.data.choices)[0]?.delta?.role === 'assistant';
+        const allChunks = data.every((e) => e.data.object === 'chat.completion.chunk');
+        const doneLast = events.length > 0 && events[events.length - 1].done === true;
+        return roleFirst && allChunks && doneLast && data.length > 2;
+    })),
+    done('xai.streaming.reconstruct', 'streaming', 'Streaming content deltas reconstruct the full message text', 'api', 'core', () => withStream(CHAT({ stream: true }), (events, final) => {
+        const text = events.filter((e) => !e.done).map((e) => e.data.choices[0]?.delta?.content ?? '').join('');
+        const full = final.body.choices[0].message.content;
+        return text === full && text.includes('[twin-stub');
+    })),
+    done('xai.streaming.finish_reason', 'streaming', 'Streaming emits a terminal finish_reason chunk', 'api', 'core', () => withStream(CHAT({ stream: true }), (events) => {
+        const data = events.filter((e) => !e.done);
+        const last = data[data.length - 1];
+        return (last?.data.choices)[0]?.finish_reason === 'stop'
+            && data.slice(0, -1).every((e) => e.data.choices[0]?.finish_reason === null);
+    })),
+    done('xai.streaming.tool_call_deltas', 'streaming', 'Streaming tool calls arrive as COMPLETE indexed delta.tool_calls chunks (xAI delta: never split across deltas)', 'api', 'common', () => withStream(CHAT({ stream: true, tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }] }), (events, final) => {
+        const deltas = events.filter((e) => !e.done).flatMap((e) => e.data.choices[0]?.delta?.tool_calls ?? []);
+        if (deltas.length !== 1)
+            return false;
+        // xAI streams each tool call COMPLETE in one delta (id + type + name + full arguments) —
+        // the real @ai-sdk/xai chunk schema REJECTS OpenAI-style split deltas.
+        const d = deltas[0];
+        if (d.function?.name !== 'get_weather' || typeof d.id !== 'string' || d.type !== 'function' || d.index !== 0)
+            return false;
+        try {
+            JSON.parse(d.function.arguments);
+        }
+        catch {
+            return false;
+        }
+        return final.body.choices[0].finish_reason === 'tool_calls';
+    })),
+    done('xai.streaming.include_usage', 'streaming', 'stream_options.include_usage emits a final usage-only chunk', 'api', 'common', () => withStream(CHAT({ stream: true, stream_options: { include_usage: true } }), (events, final) => {
+        const usageChunk = events.filter((e) => !e.done).find((e) => e.data.usage !== undefined && e.data.choices.length === 0);
+        if (!usageChunk)
+            return false;
+        const u = usageChunk.data.usage;
+        const fu = final.body.usage;
+        return u.total_tokens === fu.total_tokens && u.prompt_tokens === fu.prompt_tokens && u.total_tokens > 0;
+    })),
+    // ── Tools (function calling) ──────────────────────────────────────────────────────────
+    done('xai.tools.tool_calls', 'tools', 'Function calling: tools → tool_calls + finish_reason tool_calls', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }] }) });
+        if (!ok(r))
+            return false;
+        const c = r.body.choices[0];
+        if (c.finish_reason !== 'tool_calls' || c.message.content !== null)
+            return false;
+        const tc = c.message.tool_calls?.[0];
+        if (!tc || tc.type !== 'function' || tc.function.name !== 'get_weather' || !String(tc.id).startsWith('call_'))
+            return false;
+        // no tools → plain text, never a fabricated tool call
+        const plain = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        return plain.body.choices[0].message.tool_calls === undefined;
+    })),
+    done('xai.tools.tool_choice', 'tools', 'tool_choice none/required/named gates + forces the call', 'api', 'common', () => withRoot(async (h) => {
+        const tools = [{ type: 'function', function: { name: 'a', parameters: { type: 'object' } } }, { type: 'function', function: { name: 'b', parameters: { type: 'object' } } }];
+        const none = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: 'none' }) });
+        if (!ok(none) || none.body.choices[0].message.tool_calls !== undefined)
+            return false;
+        if (typeof none.body.choices[0].message.content !== 'string')
+            return false;
+        const named = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: { type: 'function', function: { name: 'b' } } }) });
+        const namedCalls = named.body.choices[0].message.tool_calls;
+        if (namedCalls.length !== 1 || namedCalls[0].function.name !== 'b')
+            return false;
+        const required = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: 'required' }) });
+        if (required.body.choices[0].finish_reason !== 'tool_calls')
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: 'sometimes' }) });
+        return bad.status === 400;
+    })),
+    done('xai.tools.parallel_tool_calls', 'tools', 'parallel_tool_calls (default on → one call per tool; false → single call)', 'api', 'common', () => withRoot(async (h) => {
+        const tools = [{ type: 'function', function: { name: 'a', parameters: { type: 'object' } } }, { type: 'function', function: { name: 'b', parameters: { type: 'object' } } }];
+        const par = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools }) });
+        const parCalls = par.body.choices[0].message.tool_calls;
+        if (parCalls.length !== 2 || parCalls[0].id === parCalls[1].id)
+            return false;
+        if (parCalls.map((c) => c.function.name).join(',') !== 'a,b')
+            return false;
+        const single = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, parallel_tool_calls: false }) });
+        return single.body.choices[0].message.tool_calls.length === 1;
+    })),
+    done('xai.tools.schema_arguments', 'tools', 'Stub arguments validate against the declared JSON schema (typed placeholders)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools: [{ type: 'function', function: { name: 'plan', parameters: { type: 'object', properties: { city: { type: 'string' }, days: { type: 'integer' }, indoor: { type: 'boolean' }, kind: { type: 'string', enum: ['walk', 'museum'] } } } } }] }) });
+        if (!ok(r))
+            return false;
+        const args = JSON.parse(r.body.choices[0].message.tool_calls[0].function.arguments);
+        return typeof args.city === 'string' && args.days === 0 && args.indoor === false && args.kind === 'walk';
+    })),
+    done('xai.tools.tool_result_roundtrip', 'tools', 'A tool-role result turn is accepted and answered with text', 'api', 'common', () => withRoot(async (h) => {
+        const base = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'weather in tokyo?' }] }) });
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [
+                    { role: 'user', content: 'weather in tokyo?' },
+                    { role: 'assistant', content: null, tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'get_weather', arguments: '{"city":"tokyo"}' } }] },
+                    { role: 'tool', tool_call_id: 'call_1', content: '{"temp_c": 21}' },
+                ] }) });
+        if (!ok(base) || !ok(r))
+            return false;
+        const c = r.body.choices[0];
+        // the follow-up turn is TEXT (the tools were not re-sent), and the tool_call + tool-result
+        // history genuinely counts toward prompt_tokens (vs the single-message baseline — §9 hardening)
+        return typeof c.message.content === 'string' && c.finish_reason === 'stop'
+            && r.body.usage.prompt_tokens > base.body.usage.prompt_tokens;
+    })),
+    // ── Live Search (xAI delta: search_parameters + citations) ────────────────────────────
+    done('xai.search.parameters', 'search', 'search_parameters mode on → citations[] + usage.num_sources_used; off → none', 'api', 'common', () => withRoot(async (h) => {
+        const on = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'on' } }) });
+        if (!ok(on))
+            return false;
+        const cites = on.body.citations;
+        if (!Array.isArray(cites) || cites.length === 0 || !cites.every((c) => c.includes('twin.invalid')))
+            return false;
+        if (on.body.usage.num_sources_used !== cites.length)
+            return false;
+        // deterministic: the same request yields the same query-seeded citations (§9 hardening)
+        const again = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'on' } }) });
+        if (JSON.stringify(again.body.citations) !== JSON.stringify(cites))
+            return false;
+        const off = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'off' } }) });
+        if (off.body.citations !== undefined || off.body.usage.num_sources_used !== 0)
+            return false;
+        const plain = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        return plain.body.citations === undefined;
+    })),
+    done('xai.search.mode_validation', 'search', 'search_parameters validation (bad mode / bad sources → 400)', 'api', 'common', () => withRoot(async (h) => {
+        const badMode = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'always' } }) });
+        const badSources = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'on', sources: [{ type: 'gopher' }] } }) });
+        const notObj = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: 'on' }) });
+        return badMode.status === 400 && badSources.status === 400 && notObj.status === 400 && flatError(badMode);
+    })),
+    done('xai.search.sources', 'search', 'sources (web/x/news/rss) select which source types are consulted', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'on', sources: [{ type: 'x' }, { type: 'news' }] } }) });
+        if (!ok(r))
+            return false;
+        const cites = r.body.citations;
+        if (!cites.some((c) => c.includes('/x/')) || !cites.some((c) => c.includes('/news/')) || cites.some((c) => c.includes('/web/')))
+            return false;
+        const def = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'on' } }) });
+        return def.body.citations.every((c) => c.includes('/web/'));
+    })),
+    done('xai.search.citations_toggle', 'search', 'return_citations:false omits citations[] but still reports num_sources_used', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ search_parameters: { mode: 'on', return_citations: false } }) });
+        if (!ok(r))
+            return false;
+        return r.body.citations === undefined && r.body.usage.num_sources_used > 0;
+    })),
+    // ── Deferred completions (xAI delta — stateful, kernel-backed) ────────────────────────
+    done('xai.deferred.create', 'deferred', 'deferred:true → { request_id } (no completion body yet)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ deferred: true }) });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        if (typeof b.request_id !== 'string' || !UUID_RE.test(b.request_id))
+            return false;
+        // a deferred request answers with the id envelope ONLY — never an inline completion
+        if (b.choices !== undefined || b.object === 'chat.completion')
+            return false;
+        // two identical deferred requests still get DISTINCT request ids
+        const r2 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ deferred: true }) });
+        return r2.body.request_id !== b.request_id;
+    })),
+    done('xai.deferred.lifecycle', 'deferred', 'Deferred retrieval: 202 pending → 200 completion → consumed (404 after; unknown id 404)', 'api', 'common', () => withRoot(async (h) => {
+        const create = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ deferred: true }) });
+        const reqId = create.body.request_id;
+        const p1 = await h({ m: 'GET', p: `/v1/chat/deferred-completion/${reqId}` });
+        if (p1.status !== 202)
+            return false;
+        const p2 = await h({ m: 'GET', p: `/v1/chat/deferred-completion/${reqId}` });
+        if (p2.status !== 200)
+            return false;
+        const b = p2.body;
+        if (b.object !== 'chat.completion' || !b.choices[0].message.content.includes('[twin-stub'))
+            return false;
+        if (b.usage.total_tokens !== b.usage.prompt_tokens + b.usage.completion_tokens)
+            return false;
+        // single-retrieval semantics: the result is consumed
+        const p3 = await h({ m: 'GET', p: `/v1/chat/deferred-completion/${reqId}` });
+        if (p3.status !== 404 || !flatError(p3))
+            return false;
+        const unknown = await h({ m: 'GET', p: '/v1/chat/deferred-completion/00000000-0000-0000-0000-000000000000' });
+        return unknown.status === 404;
+    })),
+    // ── Anthropic-compatible Messages (POST /v1/messages) ─────────────────────────────────
+    done('xai.messages_compat.create', 'messages_compat', 'Messages: create → Anthropic-shaped envelope (content blocks, stop_reason, usage)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/messages', b: { model: 'grok-4-0709', max_tokens: 256, messages: [{ role: 'user', content: 'hello messages' }] } });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        if (b.type !== 'message' || b.role !== 'assistant' || b.model !== 'grok-4-0709' || !String(b.id).startsWith('msg_'))
+            return false;
+        const block = b.content[0];
+        if (block?.type !== 'text' || !String(block.text).includes('[twin-stub') || !String(block.text).includes('hello messages'))
+            return false;
+        if (b.stop_reason !== 'end_turn' || b.stop_sequence !== null)
+            return false;
+        return b.usage.input_tokens > 0 && b.usage.output_tokens > 0;
+    })),
+    done('xai.messages_compat.validation', 'messages_compat', 'Messages: max_tokens is REQUIRED (Anthropic rule) + model/messages validated', 'api', 'common', () => withRoot(async (h) => {
+        const noMax = await h({ m: 'POST', p: '/v1/messages', b: { model: 'grok-4-0709', messages: [{ role: 'user', content: 'x' }] } });
+        const noModel = await h({ m: 'POST', p: '/v1/messages', b: { max_tokens: 10, messages: [{ role: 'user', content: 'x' }] } });
+        const unknown = await h({ m: 'POST', p: '/v1/messages', b: { model: 'grok-99', max_tokens: 10, messages: [{ role: 'user', content: 'x' }] } });
+        // every failure carries the FLAT {code,error} envelope, and unknown-model the vendor 404 code (§9 hardening)
+        return noMax.status === 400 && flatError(noMax)
+            && noModel.status === 400 && flatError(noModel)
+            && unknown.status === 404 && flatError(unknown) && unknown.body.code === 'Some requested entity was not found';
+    })),
+    done('xai.messages_compat.tools', 'messages_compat', 'Messages: Anthropic-style tools (input_schema) → tool_use block + stop_reason tool_use', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/messages', b: { model: 'grok-4-0709', max_tokens: 256, messages: [{ role: 'user', content: 'weather?' }], tools: [{ name: 'get_weather', description: 'get weather', input_schema: { type: 'object', properties: { city: { type: 'string' } } } }] } });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        const block = b.content[0];
+        if (block?.type !== 'tool_use' || block.name !== 'get_weather' || !String(block.id).startsWith('toolu_'))
+            return false;
+        // input is a schema-typed OBJECT (Anthropic shape), not an OpenAI-style JSON string
+        return typeof block.input === 'object' && typeof block.input.city === 'string' && b.stop_reason === 'tool_use';
+    })),
+    // ── Legacy completions (POST /v1/completions) ─────────────────────────────────────────
+    done('xai.completions_legacy.create', 'completions_legacy', 'Legacy completions: prompt → text_completion envelope (labeled stub)', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/completions', b: { model: 'grok-3', prompt: 'complete me' } });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        if (b.object !== 'text_completion' || b.model !== 'grok-3')
+            return false;
+        const c = b.choices[0];
+        if (typeof c.text !== 'string' || !c.text.includes('[twin-stub') || !c.text.includes('complete me') || c.finish_reason !== 'stop')
+            return false;
+        // usage carries the xAI token-detail objects here too (§9 hardening)
+        const u = b.usage;
+        if (u.prompt_tokens <= 0 || u.total_tokens !== u.prompt_tokens + u.completion_tokens)
+            return false;
+        if (u.prompt_tokens_details?.text_tokens !== u.prompt_tokens || typeof u.completion_tokens_details?.reasoning_tokens !== 'number')
+            return false;
+        const noPrompt = await h({ m: 'POST', p: '/v1/completions', b: { model: 'grok-3' } });
+        const unknown = await h({ m: 'POST', p: '/v1/completions', b: { model: 'grok-99', prompt: 'x' } });
+        return noPrompt.status === 400 && unknown.status === 404;
+    })),
+    // ── Model catalogs ────────────────────────────────────────────────────────────────────
+    done('xai.models.list', 'models', 'GET /v1/models lists the grok catalog (OpenAI-compatible shape)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/models' });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        if (b.object !== 'list' || !Array.isArray(b.data))
+            return false;
+        const ids = b.data.map((m) => m.id);
+        if (!ids.includes('grok-4-0709') || !ids.includes('grok-3-mini') || !ids.includes('grok-2-image-1212'))
+            return false;
+        return b.data.every((m) => m.object === 'model' && m.owned_by === 'xai' && typeof m.created === 'number');
+    })),
+    done('xai.models.get', 'models', 'GET /v1/models/:id retrieves one model; unknown → vendor 404', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/models/grok-4-0709' });
+        if (!ok(r) || r.body.object !== 'model' || r.body.id !== 'grok-4-0709')
+            return false;
+        const nf = await h({ m: 'GET', p: '/v1/models/grok-99' });
+        return nf.status === 404 && flatError(nf) && nf.body.code === 'Some requested entity was not found';
+    })),
+    done('xai.models.aliases', 'models', 'Model aliases resolve for retrieval AND inference (grok-4 → grok-4-0709)', 'api', 'common', () => withRoot(async (h) => {
+        const byAlias = await h({ m: 'GET', p: '/v1/models/grok-4' });
+        if (!ok(byAlias) || byAlias.body.id !== 'grok-4-0709')
+            return false;
+        const chat = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'grok-4-latest' }) });
+        return ok(chat) && chat.body.model === 'grok-4-0709';
+    })),
+    done('xai.models.language_models', 'models', 'GET /v1/language-models (+/:id) serves the rich xAI model objects (modalities, prices, aliases)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/language-models' });
+        if (!ok(r) || !Array.isArray(r.body.models))
+            return false;
+        const g4 = r.body.models.find((m) => m.id === 'grok-4-0709');
+        if (!g4 || !Array.isArray(g4.aliases) || !g4.aliases.includes('grok-4'))
+            return false;
+        if (!g4.input_modalities.includes('image') || typeof g4.prompt_text_token_price !== 'number')
+            return false;
+        const one = await h({ m: 'GET', p: '/v1/language-models/grok-4' }); // alias resolves
+        if (!ok(one) || one.body.id !== 'grok-4-0709')
+            return false;
+        const nf = await h({ m: 'GET', p: '/v1/language-models/grok-99' });
+        return nf.status === 404;
+    })),
+    done('xai.models.image_generation_models', 'models', 'GET /v1/image-generation-models (+/:id) serves the image-model catalog', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/image-generation-models' });
+        if (!ok(r))
+            return false;
+        const list = r.body.models;
+        if (!Array.isArray(list) || !list.some((m) => m.id === 'grok-2-image-1212' && m.output_modalities.includes('image')))
+            return false;
+        const one = await h({ m: 'GET', p: '/v1/image-generation-models/grok-2-image' });
+        if (!ok(one) || one.body.id !== 'grok-2-image-1212')
+            return false;
+        const nf = await h({ m: 'GET', p: '/v1/image-generation-models/grok-4-0709' });
+        return nf.status === 404;
+    })),
+    // ── Image generations ─────────────────────────────────────────────────────────────────
+    done('xai.images.generations', 'images', 'POST /v1/images/generations → data[].url | b64_json + revised_prompt (labeled stubs)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'grok-2-image', prompt: 'a red bicycle', n: 2 } });
+        if (!ok(r))
+            return false;
+        const data = r.body.data;
+        if (data.length !== 2 || typeof data[0].url !== 'string' || !String(data[0].revised_prompt).includes('a red bicycle'))
+            return false;
+        const b64 = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'grok-2-image', prompt: 'a red bicycle', response_format: 'b64_json' } });
+        const decoded = atob(b64.body.data[0].b64_json);
+        if (!decoded.includes('[twin-stub-image]'))
+            return false;
+        const tooMany = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'grok-2-image', prompt: 'x', n: 11 } });
+        const noPrompt = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'grok-2-image' } });
+        const chatModel = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'grok-4-0709', prompt: 'x' } });
+        return tooMany.status === 400 && noPrompt.status === 400 && chatModel.status === 400;
+    })),
+    done('xai.images.openai_params_rejected', 'images', 'xAI compatibility delta: OpenAI\'s size/quality/style params are REJECTED (400)', 'api', 'niche', () => withRoot(async (h) => {
+        for (const bad of [{ size: '1024x1024' }, { quality: 'hd' }, { style: 'vivid' }]) {
+            const r = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'grok-2-image', prompt: 'a cat', ...bad } });
+            if (r.status !== 400 || !String(r.body.error).includes('Argument not supported'))
+                return false;
+        }
+        return true;
+    })),
+    // ── api-key introspection ─────────────────────────────────────────────────────────────
+    done('xai.api_key.get', 'api_key', 'GET /v1/api-key introspects the presented key (redacted value, acls, blocked flags)', 'api', 'common', () => withRootH(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/api-key', headers: { authorization: 'Bearer xai-secret-key-12345' } });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        if (b.redacted_api_key !== 'xai-...2345')
+            return false; // derived from the PRESENTED key
+        if (!Array.isArray(b.acls) || !b.acls.includes('api-key:model:*'))
+            return false;
+        if (b.api_key_blocked !== false || b.team_blocked !== false || b.api_key_disabled !== false)
+            return false;
+        // timestamps derive from the pinned occurredAt (deterministic, not merely a string — §9 hardening)
+        if (!UUID_RE.test(String(b.api_key_id)) || b.create_time !== '2026-01-01T00:00:00.000Z')
+            return false;
+        // the blocked sentinel key can STILL introspect itself — and reports blocked
+        const blocked = await h({ m: 'GET', p: '/v1/api-key', headers: { authorization: 'Bearer xai-blocked' } });
+        return ok(blocked) && blocked.body.api_key_blocked === true;
+    })),
+    // ── tokenize-text ─────────────────────────────────────────────────────────────────────
+    done('xai.tokenize.text', 'tokenize', 'POST /v1/tokenize-text → token_ids[] (id/string_token/token_bytes; tokens re-join to the input)', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/tokenize-text', b: { text: 'hello twin world', model: 'grok-4-0709' } });
+        if (!ok(r))
+            return false;
+        const toks = r.body.token_ids;
+        if (!Array.isArray(toks) || toks.length < 3)
+            return false;
+        if (toks.some((t) => typeof t.token_id !== 'number' || typeof t.string_token !== 'string' || !Array.isArray(t.token_bytes)))
+            return false;
+        if (toks.map((t) => t.string_token).join('') !== 'hello twin world')
+            return false;
+        const noText = await h({ m: 'POST', p: '/v1/tokenize-text', b: { model: 'grok-4-0709' } });
+        const unknown = await h({ m: 'POST', p: '/v1/tokenize-text', b: { text: 'x', model: 'grok-99' } });
+        return noText.status === 400 && unknown.status === 404;
+    })),
+    // ── Errors / protocol ─────────────────────────────────────────────────────────────────
+    done('xai.errors.envelope', 'errors', 'Errors are xAI\'s FLAT {code, error} strings (gRPC-transcoded), never a nested error object', 'api', 'core', () => withRoot(async (h) => {
+        const nf = await h({ m: 'GET', p: '/v1/nonexistent' });
+        if (nf.status !== 404 || !flatError(nf))
+            return false;
+        // the delta vs OpenAI: `error` is a STRING, and there is no nested { error: {...} }
+        if (typeof nf.body.error === 'object')
+            return false;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: { messages: [{ role: 'user', content: 'x' }] } });
+        return bad.status === 400 && flatError(bad) && bad.body.code === 'Client specified an invalid argument';
+    })),
+    done('xai.errors.auth_401', 'errors', 'Modeled auth: missing/invalid bearer → 401 (when a request carries an auth surface)', 'api', 'common', () => withRootH(async (h) => {
+        const missing = await h({ m: 'GET', p: '/v1/models', headers: {} });
+        if (missing.status !== 401 || !flatError(missing))
+            return false;
+        // the 401 code is the gRPC UNAUTHENTICATED description — NOT the 400's invalid-argument
+        // code (§9 caught the 401 reusing it; this pin keeps it fixed)
+        if (missing.body.code !== 'The request does not have valid authentication credentials for the operation')
+            return false;
+        const invalid = await h({ m: 'GET', p: '/v1/models', headers: { authorization: 'Bearer xai-invalid' } });
+        if (invalid.status !== 401 || !String(invalid.body.error).includes('Incorrect API key'))
+            return false;
+        if (invalid.body.code !== missing.body.code)
+            return false;
+        const valid = await h({ m: 'GET', p: '/v1/models', headers: { authorization: 'Bearer xai-any-other-key' } });
+        return valid.status === 200;
+    })),
+    done('xai.errors.blocked_403', 'errors', 'A blocked key → 403 on every route EXCEPT its own /v1/api-key introspection', 'api', 'niche', () => withRootH(async (h) => {
+        const chat = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT(), headers: { authorization: 'Bearer xai-blocked' } });
+        if (chat.status !== 403 || chat.body.code !== 'The caller does not have permission')
+            return false;
+        const models = await h({ m: 'GET', p: '/v1/models', headers: { authorization: 'Bearer xai-blocked' } });
+        if (models.status !== 403)
+            return false;
+        const introspect = await h({ m: 'GET', p: '/v1/api-key', headers: { authorization: 'Bearer xai-blocked' } });
+        return introspect.status === 200 && introspect.body.api_key_blocked === true;
+    })),
+    done('xai.errors.rate_limit_429', 'errors', 'Modeled 429 (deterministic opt-in trigger) → {code,error} + retry-after', 'api', 'niche', () => withRootH(async (h) => {
+        const limited = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT(), headers: { authorization: 'Bearer xai-ok', 'x-twin-force-rate-limit': '1' } });
+        if (limited.status !== 429 || limited.body.code !== 'Resource has been exhausted')
+            return false;
+        if (limited.headers?.['retry-after'] !== '1')
+            return false;
+        const normal = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT(), headers: { authorization: 'Bearer xai-ok' } });
+        return normal.status === 200;
+    })),
+    done('xai.errors.read_only_405', 'errors', 'A read-only twin refuses mutations (405), serves reads, and never advances state via a GET', 'api', 'niche', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'xai-cap-'));
+        try {
+            const write = await handleXaiTwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify(CHAT()), root, readOnly: true, occurredAt: AT });
+            if (write.status !== 405 || typeof write.body.error !== 'string')
+                return false;
+            const read = await handleXaiTwinRequest({ method: 'GET', path: '/v1/models', root, readOnly: true, occurredAt: AT });
+            if (read.status !== 200 || !Array.isArray(read.body.data))
+                return false;
+            // the STATE-ADVANCING GET path (deferred retrieval) must not mutate the kernel log in a
+            // read-only twin (§9 found the consume write unguarded): seed + one writable poll, then
+            // read-only GETs serve the result REPEATEDLY (never consuming), and the writable flow
+            // afterwards still consumes exactly once.
+            const created = await handleXaiTwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify(CHAT({ deferred: true })), root, occurredAt: AT });
+            const reqId = created.body.request_id;
+            const pendingRo = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, readOnly: true, occurredAt: AT });
+            if (pendingRo.status !== 202)
+                return false;
+            // a read-only pending poll did NOT advance polls — the next read-only poll is still 202
+            const pendingRo2 = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, readOnly: true, occurredAt: AT });
+            if (pendingRo2.status !== 202)
+                return false;
+            // one WRITABLE poll advances to servable…
+            const pendingW = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, occurredAt: AT });
+            if (pendingW.status !== 202)
+                return false;
+            // …and read-only retrieval serves the result WITHOUT consuming it (twice)
+            const ro1 = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, readOnly: true, occurredAt: AT });
+            const ro2 = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, readOnly: true, occurredAt: AT });
+            if (ro1.status !== 200 || ro2.status !== 200)
+                return false;
+            // the writable flow still consumes exactly once
+            const w = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, occurredAt: AT });
+            const after = await handleXaiTwinRequest({ method: 'GET', path: `/v1/chat/deferred-completion/${reqId}`, root, occurredAt: AT });
+            if (w.status !== 200 || after.status !== 404)
+                return false;
+            const device = await startXaiTwinDeviceAuthorization({ body: new URLSearchParams({ client_id: 'grok-build', scope: 'grok-cli:access' }), origin: 'http://127.0.0.1', root });
+            const userCode = String(device.body.user_code);
+            const readOnlyServer = await createXaiTwinServer({ readOnly: true, root, port: 0 });
+            try {
+                const origin = `http://127.0.0.1:${readOnlyServer.port}`;
+                const decision = await fetch(`${origin}/oauth2/device/decision`, { method: 'POST', body: new URLSearchParams({ decision: 'approve', user_code: userCode }) });
+                const control = await fetch(`${origin}/twin/oauth/authorizations`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ approved: true, user_code: userCode }) });
+                return decision.status === 405 && control.status === 404 && xaiDeviceAuthView(userCode, root).status === 'pending';
+            }
+            finally {
+                readOnlyServer.stop();
+            }
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    // ── Connector (pull over an injected client; push refuses loudly) ─────────────────────
+    done('xai.connector.read_surface', 'connector', 'Connector read surface (the three model catalogs in one pass)', 'connector', 'core', () => withRoot(async (h) => {
+        const flat = await h({ m: 'GET', p: '/v1/models' });
+        const rich = await h({ m: 'GET', p: '/v1/language-models' });
+        const img = await h({ m: 'GET', p: '/v1/image-generation-models' });
+        return ok(flat) && Array.isArray(flat.body.data)
+            && ok(rich) && Array.isArray(rich.body.models)
+            && ok(img) && Array.isArray(img.body.models);
+    })),
+    done('xai.connector.pull_map', 'connector', 'Connector pulls + maps the real catalogs into the twin; served /v1/models merges them (offline, injected client)', 'connector', 'core', async () => {
+        const { mapModel, mapLanguageModel, syncXaiFromReal } = await import("./xai-connector.js");
+        const root = mkdtempSync(join(tmpdir(), 'xai-cap-'));
+        try {
+            const mapped = mapModel({ id: 'grok-secret-preview', created: 5, owned_by: 'xai' });
+            const mappedRich = mapLanguageModel({ id: 'grok-secret-preview', created: 5, aliases: ['gsp'], input_modalities: ['text'] });
+            if (mapped.type !== 'model' || mappedRich.type !== 'language_model' || mappedRich.fields.aliases[0] !== 'gsp')
+                return false;
+            const fake = async (_m, p) => {
+                if (p === '/v1/models')
+                    return { data: [{ id: 'grok-secret-preview', created: 5, owned_by: 'xai' }] };
+                if (p === '/v1/language-models')
+                    return { models: [{ id: 'grok-secret-preview', created: 5, aliases: ['gsp'], input_modalities: ['text'] }] };
+                return {};
+            };
+            const res = await syncXaiFromReal(fake, { root, occurredAt: AT });
+            if (res.observed < 2 || res.deltasAppended < 1)
+                return false;
+            // the twin's SERVED catalog now merges the observed model over the static list
+            const served = await handleXaiTwinRequest({ method: 'GET', path: '/v1/models', root, occurredAt: AT });
+            const ids = served.body.data.map((m) => m.id);
+            if (!ids.includes('grok-secret-preview') || !ids.includes('grok-4-0709'))
+                return false;
+            const one = await handleXaiTwinRequest({ method: 'GET', path: '/v1/models/grok-secret-preview', root, occurredAt: AT });
+            if (one.status !== 200 || one.body.created !== 5)
+                return false;
+            // idempotent: a second pull of identical state appends nothing
+            const again = await syncXaiFromReal(fake, { root, occurredAt: AT });
+            return again.deltasAppended === 0;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('xai.connector.unsupported_op_fails', 'connector', 'Nothing can cross: the direct push refuses LOUDLY, and the head\'s perform SETTLES each entry with the reason (the xAI API has no client-writable resources) rather than fabricating a write', 'connector', 'common', async () => {
+        const { pushXaiAction, performXaiAction } = await import("./xai-connector.js");
+        const { deployableEntries } = await import('@volter/world-core');
+        const root = mkdtempSync(join(tmpdir(), 'xai-cap-'));
+        try {
+            const fake = async (_m, _p) => ({});
+            // no pending local writes → push is a clean no-op
+            // protocol 2: with nothing deployable there is nothing to perform
+            const clean = { pushed: deployableEntries('xai', root).length };
+            if (clean.pushed !== 0)
+                return false;
+            // a local write (deferred completion) becomes a pending action…
+            const created = await handleXaiTwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify(CHAT({ deferred: true })), root, occurredAt: AT });
+            if (created.status !== 200 || deployableEntries('xai', root).length === 0)
+                return false;
+            // …and pushing it REFUSES loudly (never a silent drop, never a fabricated vendor write)
+            let threwSingle = false;
+            try {
+                await pushXaiAction(fake, { operation: 'deferred_completion.create', subject: { type: 'deferred_completion', id: 'x' } });
+            }
+            catch (e) {
+                threwSingle = e instanceof Error && e.message.includes('unsupported operation');
+            }
+            // …and at the head, the perform adapter SETTLES it with the same fact rather than sending anything:
+            // there is nothing at xAI to write, and the receipt says so instead of claiming a write happened
+            const settled = await performXaiAction(fake, { operation: 'deferred_completion.create', subject: { type: 'deferred_completion', id: 'x' }, fields: {} }, { resolve: (_t, id) => id, service: 'xai', root });
+            const saysWhy = settled.data !== undefined
+                && settled.data.performed === false
+                && String(settled.data.reason ?? '').includes('no client-writable resources');
+            return threwSingle && saysWhy;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    // ── Conformance harness ───────────────────────────────────────────────────────────────
+    done('xai.conformance.envelopes', 'conformance', 'Offline conformance harness passes (envelope shapes across the surface)', 'connector', 'core', async () => {
+        const { checkXaiConformance } = await import("./xai-conformance.js");
+        const report = await checkXaiConformance();
+        // exactly the 9 authored checks ran (a deleted check trips this — checksRun is a tripwire,
+        // not a tautology; §9 hardening) and none reported a violation.
+        return report.ok && report.violations.length === 0 && report.checksRun === 9;
+    }),
+    // ── Honest todos (real vendor surface the twin has not reached) ───────────────────────
+    todo('xai.chat.logprobs', 'chat', 'logprobs + top_logprobs per-token detail on chat completions', 'api', 'niche'),
+    todo('xai.chat.penalties', 'chat', 'presence_penalty / frequency_penalty accepted + validated', 'api', 'niche'),
+    todo('xai.chat.cached_prompt_tokens', 'chat', 'Prompt caching — usage.prompt_tokens_details.cached_tokens reflects cache hits', 'api', 'common'),
+    todo('xai.deferred.expiry', 'deferred', 'Deferred completions expire after the vendor retention window (unretrieved results lapse)', 'api', 'niche'),
+    todo('xai.search.date_range', 'search', 'Live Search from_date/to_date window parameters', 'api', 'common'),
+    todo('xai.search.max_results', 'search', 'Live Search max_search_results caps the consulted sources', 'api', 'common'),
+    todo('xai.search.source_filters', 'search', 'Live Search per-source filters (allowed/excluded websites, X handles, RSS links, safe_search)', 'api', 'common'),
+    todo('xai.messages_compat.streaming', 'messages_compat', 'Anthropic-compatible streaming (message_start → content_block_delta → message_stop SSE events)', 'api', 'common'),
+    todo('xai.messages_compat.system', 'messages_compat', 'Anthropic-style system prompt + multi-block content parts on /v1/messages', 'api', 'niche'),
+    todo('xai.completions_legacy.streaming', 'completions_legacy', 'Legacy completions streaming (text deltas over SSE)', 'api', 'niche'),
+    todo('xai.completions_legacy.echo_suffix', 'completions_legacy', 'Legacy completions echo/suffix/logprobs parameters', 'api', 'niche'),
+    todo('xai.api_key.acl_enforcement', 'api_key', 'ACL-scoped keys: api-key:model:*/api-key:endpoint:* ACLs actually restrict requests', 'api', 'niche'),
+    // The Responses API — xAI's current first-class stateful inference surface (docs.x.ai now
+    // files chat completions under "legacy"). A whole area the twin has not reached yet; found
+    // by the §9 adversarial pass (the area census cannot flag an area its author never listed,
+    // so this entered the denominator through review, not the gate).
+    todo('xai.responses.create', 'responses', 'POST /v1/responses — stateful successor to chat completions (server-side stored responses)', 'api', 'core'),
+    todo('xai.responses.retrieve_delete', 'responses', 'GET/DELETE /v1/responses/{response_id} — retrieve or delete a stored response', 'api', 'common'),
+    todo('xai.responses.compact', 'responses', 'POST /v1/responses/compact — compact a stored conversation', 'api', 'niche'),
+    // Pull-surface coverage audit gap (TWIN-46 / G2) — filed as a manifest todo so the
+    // seed-conformance tooling turns it into real backlog work. See pull-audit.json (repo root).
+    todo('xai.connector.pull_image_generation_models', 'connector', 'Connector: pull the image-generation model catalog (GET /v1/image-generation-models) into the twin', 'connector', 'niche'),
+];
+// Committed area census — the vendor's top-level API product areas (docs.x.ai REST reference),
+// authored top-down independent of what a manifest entry happens to already exist for. The
+// area-census meta-test (assertAreaCensus) fails the gate if a declared area has zero manifest
+// entries OR a manifest entry's `area` drifts outside this list. HONEST LIMIT: the census only
+// protects areas someone LISTED — it cannot flag an area the author never thought of (the §9
+// adversarial pass caught `responses` missing this way); the per-cycle MANIFEST-COMPLETENESS
+// AUDIT re-walking the vendor docs is what closes that loop.
+//
+// Deliberately-excluded neighboring surface (a boundary, not an omission): xAI's Collections
+// API and Management API live on a DIFFERENT host (management-api.x.ai) and are a separate
+// console/administration product — this pack twins the api.x.ai inference surface only. See
+// README ## Coverage.
+export const XAI_AREAS = [
+    'api_key', 'chat', 'cli_proxy', 'completions_legacy', 'conformance', 'connector', 'deferred', 'errors',
+    'images', 'messages_compat', 'models', 'oauth', 'responses', 'search', 'streaming', 'tokenize', 'tools', 'ui',
+];
+export function xaiCapabilities() {
+    return checkCapabilities('xai', XAI_CAPABILITIES);
+}