@volter/twin-xai 0.1.0

package/dist/src/xai-types.d.ts

@@ -0,0 +1,118 @@
+/** A chat message param as the caller sends it (content is a string OR a content-part array). */
+export type ChatMessageParam = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | Array<Record<string, unknown>> | null;
+    name?: string;
+    tool_calls?: ChatToolCall[];
+    tool_call_id?: string;
+};
+/** A function tool_call inside an assistant message (faithful shape). */
+export type ChatToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/** xAI reports token detail objects inside `usage` (prompt_tokens_details with text/audio/
+ *  image/cached splits; completion_tokens_details with reasoning tokens), plus the Live Search
+ *  `num_sources_used` counter. Deterministic in the twin. */
+export type ChatUsage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details: {
+        text_tokens: number;
+        audio_tokens: number;
+        image_tokens: number;
+        cached_tokens: number;
+    };
+    completion_tokens_details: {
+        reasoning_tokens: number;
+        audio_tokens: number;
+        accepted_prediction_tokens: number;
+        rejected_prediction_tokens: number;
+    };
+    num_sources_used: number;
+};
+export type ChatChoice = {
+    index: number;
+    message: {
+        role: 'assistant';
+        content: string | null;
+        /** xAI delta: grok-3-mini exposes its chain-of-thought here (the twin's is a labeled stub);
+         *  grok-4-family reasoning models spend reasoning tokens but never expose the content. */
+        reasoning_content?: string;
+        tool_calls?: ChatToolCall[];
+        refusal?: null;
+    };
+    logprobs: null;
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+/** The unary chat.completion response envelope (faithful shape; xAI ids are UUID-formatted). */
+export type ChatCompletion = {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage: ChatUsage;
+    system_fingerprint: string;
+    /** Live Search: the source URLs consulted (deterministic labeled stubs in the twin). Present
+     *  only when search ran and return_citations was not disabled. */
+    citations?: string[];
+};
+export type TextCompletion = {
+    id: string;
+    object: 'text_completion';
+    created: number;
+    model: string;
+    choices: Array<{
+        text: string;
+        index: number;
+        logprobs: null;
+        finish_reason: 'stop' | 'length';
+    }>;
+    usage: ChatUsage;
+    system_fingerprint: string;
+};
+export type MessagesContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+export type MessagesResponse = {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    model: string;
+    content: MessagesContentBlock[];
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+    stop_sequence: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+};
+/** The xAI error envelope. Unlike OpenAI's nested `{ error: {...} }`, xAI's REST layer is a
+ *  gRPC transcoding and returns TWO FLAT STRINGS: `code` (a gRPC status description, e.g.
+ *  "Client specified an invalid argument") and `error` (the human message). The real
+ *  `@ai-sdk/xai` provider parses exactly this shape. */
+export type XaiError = {
+    code: string;
+    error: string;
+};
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = {
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;

package/dist/src/xai-types.js

@@ -0,0 +1,6 @@
+// Shared wire-shape types for the xAI (Grok) API surface. These mirror the real vendor JSON
+// shapes (not any SDK's internal types — the twin never imports an SDK at runtime; the real
+// `@ai-sdk/xai` provider is exercised only in *.test.ts). xAI's chat surface is OpenAI-chat-
+// compatible with xAI-specific deltas (Live Search citations, reasoning_content, deferred
+// completions, the {code, error} error envelope), and those deltas are modeled here explicitly.
+export {};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@volter/twin-xai",
+  "version": "0.1.0",
+  "description": "Local xAI (Grok) twin — a faithful, stateful local API plus the Grok Build device-OAuth browser surface. The model is stubbed (deterministic) and Live Search citations are labeled stubs, while the OAuth/account/usage world and API protocol envelopes remain coherent and vendor-shaped. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "xai",
+    "grok",
+    "llm"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/xai"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/xai#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-xai": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@ai-sdk/xai": "^3.0.111",
+    "ai": "^6.0.0",
+    "zod": "^4.0.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-xai CLI: serve the xAI/Grok API, OAuth protocol UI, or run conformance. `mirror` is an
+// alias for the SAME server because entry and consent are the vendor-owned browser leg of OAuth;
+// denial and completion are explicitly Twin-local terminal states, not a second dashboard.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createXaiTwinServer } from './xai-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON scenario file)
+
+if (cmd === 'serve' || cmd === 'mirror') {
+  const s = await createXaiTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+  process.stdout.write(`xai twin (chat/completions/messages output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling
+  const { checkXaiConformance } = await import('./xai-conformance.ts');
+  const report = await checkXaiConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-xai serve|mirror|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/src/index.ts

@@ -0,0 +1,120 @@
+// @volter/twin-xai — the xAI (Grok) twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The xAI API: an OpenAI-chat-compatible protocol envelope with xAI's
+// deltas modeled explicitly — the grok-4-family model catalogs (/v1/models,
+// /v1/language-models, /v1/image-generation-models), the flat {code, error} error envelope,
+// deferred completions (stateful, kernel-backed), Live Search parameters + citations,
+// reasoning_content/reasoning-token accounting, the Anthropic-compatible /v1/messages
+// endpoint, legacy /v1/completions, api-key introspection, tokenize-text, the vendor-owned Grok
+// Build device-entry/consent UI, and explicitly Twin-local terminal result states. The xAI console
+// itself remains outside this API-first pack.
+//
+// THE DETERMINISTIC STUBS ARE THE ANSWER: every inference endpoint returns a clearly-labeled
+// STUB completion, and Live Search returns deterministic labeled citations. Everything around
+// them — the wire protocol — is faithful. (Conformance + capability tooling live in @volter/world-tooling, a dev
+// dependency — NOT re-exported here, per E2.)
+export { handleXaiTwinRequest, streamChat, buildChatCompletion } from './xai-twin.ts';
+export type { XaiRequest, XaiResponseEnvelope } from './xai-twin.ts';
+export { createXaiTwinFetch, createXaiTwinServer, type XaiTwinFetchOptions } from './xai-server.ts';
+export {
+  deviceConsentPageHtml,
+  deviceDonePageHtml,
+  deviceEntryPageHtml,
+  xaiDeviceAuthView,
+  XAI_DEVICE_STYLE_PATH,
+} from './xai-device-auth-ui.ts';
+export {
+  XAI_MODELS, XAI_LANGUAGE_MODELS, XAI_IMAGE_GENERATION_MODELS,
+  findModel, findLanguageModel, findImageGenerationModel, modelBehavior, canonicalModelId,
+} from './xai-models.ts';
+export type { XaiModel, XaiLanguageModel, XaiImageGenerationModel, XaiModelBehavior } from './xai-models.ts';
+export {
+  contentToText, countPromptTokens, countPromptTokenDetails, estimateTokens, lastUserText,
+  pseudoTokenize, stubAssistantText, stubCitations, stubJsonObject, stubReasoningText,
+  stubToolArguments, stubToolCall, uuidFromSeed,
+} from './xai-stub.ts';
+export type { XaiToken } from './xai-stub.ts';
+export type {
+  ChatMessageParam, ChatToolCall, ChatCompletion, ChatChoice, ChatUsage,
+  TextCompletion, MessagesResponse, MessagesContentBlock, XaiError, SseEvent, SseSink,
+} from './xai-types.ts';
+export { createXaiScenarioEngine, loadXaiScenarioDocument, realizeXaiRespond, xaiScenarioAdapter } from './xai-scenario.ts';
+export type { ScenarioToolCall, ScriptedResult, XaiScenarioEngine, XaiScenarioRequest, XaiScenarioRespond } from './xai-scenario.ts';
+export {
+  XAI_BUDGET_CEILING,
+  XAI_BUDGET_MAX_RETRY_AFTER_S,
+  XAI_BUDGET_WINDOW_MS,
+  XAI_CALL_WEIGHTS,
+  XAI_RATE_BUDGET,
+  XaiBudget,
+  XaiBudgetError,
+  xaiBudgetPath,
+  xaiCallWeight,
+  splitXaiPath,
+} from './xai-budget.ts';
+export type {
+  XaiBudgetErrorKind,
+  XaiBudgetOptions,
+  XaiBudgetReservation,
+  XaiBudgetSnapshot,
+} from './xai-budget.ts';
+export {
+  XAI_API_BASE,
+  liveXaiExecute,
+  mapModel,
+  mapLanguageModel,
+  pullXaiModels,
+  syncXaiFromReal,
+  pushXaiAction,
+} from './xai-connector.ts';
+export type { XaiExecute, LiveXaiOptions } from './xai-connector.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { XAI_RATE_BUDGET as RATE_BUDGET } from './xai-budget.ts';
+import { performXaiAction, syncXaiFromRemote } from './xai-connector.ts';
+
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system. Moved 2026-09-08. The xAI API has NO client-writable resource, so `perform` settles every
+  // entry with that reason and only `refresh` reads; the pack's executor is GET-only by type to say so.
+  protocol: '2',
+  refresh: { every: '30m', onDemand: { atMost: '60s' } }, // a model catalogue moves slowly
+  stateSystem: { perform: performXaiAction, refresh: syncXaiFromRemote },
+  // the round trip: a DEFERRED completion — a plain completion is answered and forgotten, but xAI's
+  // deferred mode persists the request so a caller can poll it, which is the row this twin keeps
+  roundTrip: { method: 'POST', path: '/v1/chat/completions', body: { model: 'grok-4-latest', deferred: true, messages: [{ role: 'user', content: 'round trip' }] }, headers: { authorization: 'Bearer round-trip' } },
+  parityOrigin: 'http://twin',
+  vendor: 'xai',
+  // The client-side rate budget, armed by `registerPack` as well as by importing the budget module.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'generative',
+  bin: 'world-xai',
+  // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+  resourcesUnreachable: {
+    'language_model': 'the vendor catalog',
+    'model': 'the vendor catalog',
+  },
+  resources: ['deferred_completion', 'language_model', 'model', 'oauth_account', 'oauth_device_authorization', 'oauth_usage'],
+  specSource: 'xAI (Grok) REST API + Grok Build OAuth/device and chat-proxy protocols (envelope-faithful; model output is a deterministic stub, Live Search citations are deterministic labeled stubs)',
+  description: 'xAI (Grok) twin — coherent virtual account/device OAuth/refresh/usage plus the Grok CLI proxy and OpenAI-chat-compatible API envelope; generative output is a labeled stub.',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31). Both credential-env spellings the vendor and its users write —
+  // XAI_* and GROK_*.
+  adoption: {
+    // xAI's official Python SDK (xai-org/xai-sdk-python). An `openai` client pointed at api.x.ai is NOT
+    // claimed here: that distribution is the openai pack's and XAI_API_BASE is what routes it.
+    pypi: ['xai-sdk'],
+    sdks: ['@ai-sdk/xai'], envStems: ['XAI', 'GROK'],
+  },
+  // Inference lives on https://api.x.ai — the pack's connector pins XAI_API_BASE =
+  // 'https://api.x.ai' (xai-connector.ts). management-api.x.ai is a separate console/
+  // administration product the pack deliberately does NOT twin (README §Management API) — left
+  // unclaimed so strict egress fails closed rather than letting a half-modeled flow through.
+  hosts: [{ host: 'api.x.ai' }],
+  // The SDK calls the same-origin '/v1/…' and loads from api.x.ai — the dev proxy forwards
+  // '/v1/' to the twin and strips the absolute host so calls come back same-origin.
+  browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.x.ai' },
+};
+
+registerPack(pack);

package/src/xai-budget.ts

@@ -0,0 +1,165 @@
+// xAI's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed bindings
+// `liveXaiExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling window,
+// reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger — lives ONCE
+// in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's header for
+// the full rationale AND for the honest list of what the guard does not guarantee (an injected clock
+// or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ──────────────────────────────────────────────────────────────────────────
+// A ~4.5-day Figma token lockout (2026-07-25) came from a burst of raw vendor calls made OUTSIDE any
+// guarded client. `liveXaiExecute` was exactly that shape: this pack's one construction site for a
+// real client, and a BARE `fetch` with the credential attached as `Authorization: Bearer` and
+// NOTHING in front of it — no ceiling, no cooldown, no ledger. `scripts/rate-budget-coverage.test.ts`
+// is the gate that found it; this module is the fix.
+//
+// ── HOW THE CEILING WAS CHOSEN: xAI PUBLISHES NO SCALAR LIMIT AT ALL ─────────────────────────
+// This is a DISCLAIMER, not a model of a limit, and it is a stronger disclaimer than gemini's.
+//
+// xAI's public documentation states no rate limit anywhere that could bind this connector: neither
+// the API reference (docs.x.ai/docs/api-reference), nor the models page (docs.x.ai/docs/models,
+// which carries pricing and capability tables but no RPM/RPS/TPM figures), nor the overview or
+// quickstart pages publish a requests-per-minute, requests-per-second or tokens-per-minute number,
+// and none of them even direct the reader to a dashboard where one could be read. (The URL commonly
+// cited for this, docs.x.ai/docs/consumption-and-rate-limits, returns 404.)
+//
+// So there is no vendor figure to size against, and the rule for that case is to SAY SO and pin to
+// the kernel's austere fallback rather than borrow an adjacent-but-different number. Copying, say,
+// OpenAI's tier limits because xAI's API is OpenAI-chat-compatible would be exactly the fabrication
+// this rule exists to prevent — protocol compatibility is not quota compatibility.
+//
+// Therefore: 60 weighted units per 60s at a default weight of 2 — EXACTLY `DEFAULT_RATE_BUDGET`.
+// 30 calls a minute, one every two seconds. Comfortably above any real pull (the whole pull surface
+// is TWO calls: the flat catalog and the rich one) and far below the shape that causes lockouts.
+// Nothing here is more permissive than the fallback.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN: THEY ARE FLAT, DELIBERATELY ─────────────────────────────────
+// There are NO pricing rules, and their absence is a decision rather than an omission.
+//
+// `XaiExecute` is typed `method: 'GET'` — the pull surface is read-only catalogs
+// (`/v1/models`, `/v1/language-models`) and the push surface REFUSES LOUDLY for every operation,
+// because the xAI API has no client-writable resources. So no caller of this execute can reach the
+// token-billed inference endpoints (`POST /v1/chat/completions`, `/v1/messages`), and there is no
+// endpoint in reach that is credibly dearer than another.
+//
+// Inventing a ratio anyway — pricing some GET at 4 "to be safe" — would be a made-up number wearing
+// the costume of a vendor fact, which is precisely what the anti-fabrication rule forbids. Every
+// call therefore costs the same 2, and nothing is free.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'xai';
+
+/** Rolling window, in ms. The fallback's, because xAI publishes no per-minute figure to match. */
+export const XAI_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s at the default weight of 2 = 30 calls a minute —
+ * the kernel's austere fallback exactly, adopted deliberately because xAI publishes no scalar limit.
+ */
+export const XAI_BUDGET_CEILING = 60;
+
+/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const XAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/**
+ * Per-call cost. FLAT by design — see the header: the execute is GET-only over read-only catalogs,
+ * so no reachable endpoint is credibly dearer than another, and inventing a ratio would be a
+ * fabricated vendor fact. `other` is the only weight, and it is never zero.
+ */
+export const XAI_CALL_WEIGHTS = {
+  /** Every call. xAI publishes no per-endpoint cost, and this execute reaches only catalog reads. */
+  other: 2,
+} as const;
+
+/**
+ * THE PACK'S DECLARATION — pure data, the only xAI-specific thing in the whole budget.
+ *
+ * `rules` is EMPTY on purpose (see the header). Also exported as `pack.rateBudget` (see index.ts),
+ * so `registerPack` arms it too.
+ */
+export const XAI_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: XAI_BUDGET_WINDOW_MS,
+  ceiling: XAI_BUDGET_CEILING,
+  defaultWeight: XAI_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: XAI_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [],
+  reason:
+    'xAI publishes NO scalar rate limit anywhere in its public documentation that could bind this ' +
+    'connector: neither the API reference (docs.x.ai/docs/api-reference), nor the models page (which ' +
+    'carries pricing and capability tables but no RPM/RPS/TPM figures), nor the overview or quickstart ' +
+    'pages state a requests-per-minute, requests-per-second or tokens-per-minute number, and none even ' +
+    'points at a dashboard where one could be read (the commonly-cited consumption-and-rate-limits URL ' +
+    '404s). With no vendor figure to model, this pins to the kernel\'s austere fallback rather than ' +
+    'borrowing OpenAI\'s tier limits on the strength of xAI\'s OpenAI-compatible protocol — protocol ' +
+    'compatibility is not quota compatibility. 60 weighted units / 60s at 2 per call = 30 calls a ' +
+    'minute, identical to DEFAULT_RATE_BUDGET and no more permissive than it. Pricing is FLAT and that ' +
+    'is deliberate: XaiExecute is typed GET-only over read-only catalogs and the push surface refuses ' +
+    'loudly, so no caller can reach a token-billed inference endpoint and no reachable endpoint is ' +
+    'credibly dearer than another; inventing a ratio would be a made-up number dressed as vendor fact.',
+};
+
+// Declared at module load, so merely importing this module (which `xai-connector.ts` does) is enough
+// to arm the real ceiling. Here the declaration and the kernel's DEFAULT_RATE_BUDGET happen to be
+// numerically identical, so the usual "the fallback is not uniformly tighter" hazard does not bite —
+// but `RateBudget` still reads its policy live, and constructing through the subclass below (which
+// imports this module) is what keeps the ordering a non-issue in general.
+declareRateBudget(VENDOR, XAI_RATE_BUDGET);
+
+/** Split a connector path (which may carry its own query string) into pathname + parsed query. */
+export function splitXaiPath(path: string): { pathname: string; query: Record<string, string> } {
+  const q = path.indexOf('?');
+  if (q < 0) return { pathname: path, query: {} };
+  const query: Record<string, string> = {};
+  for (const [k, v] of new URLSearchParams(path.slice(q + 1))) query[k] = v;
+  return { pathname: path.slice(0, q), query };
+}
+
+/**
+ * Price one call. Keyed off the request the connector is ABOUT to make. With no rules declared every
+ * call takes `defaultWeight` — which is the point: an unclassified endpoint must never be free.
+ */
+export function xaiCallWeight(method: string, path: string): number {
+  const { pathname, query } = splitXaiPath(path);
+  return rateBudgetWeight(VENDOR, `${(method || 'GET').toUpperCase()} ${pathname}`, query);
+}
+
+/** Where xAI's ledger lives. API-key-keyed and cwd-independent by default (the limit, whatever it
+ *  is, is per key, so a cwd-scoped ledger would hand the same key a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting instead. */
+export function xaiBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for xAI's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type XaiBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * xAI's budget — the shared kernel guard bound to this vendor's declaration. A real subclass, not an
+ * alias, so the guard check in `liveXaiExecute` still means "a budget that accounts against XAI's
+ * ledger under XAI's ceiling": another vendor's `RateBudget` (with its own, possibly larger,
+ * ceiling) is NOT assignable there.
+ */
+export class XaiBudget extends RateBudget {
+  constructor(opts: XaiBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as XaiBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as XaiBudgetErrorKind } from '@volter/world-core';
+export type XaiBudgetReservation = RateBudgetReservation;
+export type XaiBudgetSnapshot = RateBudgetSnapshot;