@volter/twin-x 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@volter/twin-x",
+  "version": "0.1.0",
+  "description": "Local X (Twitter) API v2 twin (post, reply, delete, timelines, user lookup) with an x.com mirror, built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/x"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/x#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-x": "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"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "twitter-api-v2": "^1.29.1",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createXTwinServer } from './x-server.ts';
+import { createXMirrorServer } from './x-mirror-ui.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');
+
+if (cmd === 'serve') {
+  const server = await createXTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`x twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const s = await createXMirrorServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`x mirror UI (x.com: sign in, profile, timeline, post, compose) at ${s.url}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkXConformance } = await import('./x-conformance.ts');
+  const report = await checkXConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-x serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,132 @@
+export { handleXTwinRequest } from './x-twin.ts';
+export type { XRequest } from './x-twin.ts';
+export { createXTwinFetch, createXTwinServer, type XTwinFetchOptions } from './x-server.ts';
+export {
+  budgetedXExecute,
+  liveXExecute,
+  MAX_PROCESSING_POLLS,
+  MAX_PROCESSING_WAIT_MS,
+  XVideoStillProcessingError,
+  mapTimelinePost,
+  pullXMentions,
+  pullXOwnTimeline,
+  pushPendingXActions,
+  pushXAction,
+  performXAction,
+  PULL_TWEET_FIELDS,
+  syncXFromReal,
+  xRequestForAction,
+} from './x-connector.ts';
+export type { LiveXOptions, XExecute } from './x-connector.ts';
+export {
+  forbiddenProblem,
+  invalidRequestProblem,
+  notFoundProblem,
+  rateLimitExceeded,
+  readOnlyRefusal,
+  resourceNotFoundProblem,
+  unauthorizedProblem,
+} from './x-problems.ts';
+export type { XResponse } from './x-problems.ts';
+export {
+  avatarHue,
+  avatarInitial,
+  buildXMirrorClient,
+  createXMirrorServer,
+  displayUrl,
+  durationLabel,
+  fullTimestamp,
+  joinedLabel,
+  mediaByKey,
+  postMedia,
+  PROFILE_READ_QUERY,
+  POST_READ_QUERY,
+  referencedId,
+  relativeTime,
+  textSegments,
+  tweetsById,
+  usersById,
+  videoSource,
+  xMirrorHtml,
+  xMirrorStyles,
+} from './x-mirror-ui.ts';
+export type { TextSegment, XRow } from './x-mirror-ui.ts';
+export { missingScopes, parseScopeList, REQUIRED_SCOPES, X_SCOPES } from './x-scopes.ts';
+// The client-side rate budget — the fail-closed backstop `liveXExecute` routes every live
+// request through. The mechanism is the kernel's (`@volter/world-core` -> rateBudget.ts); these are
+// this vendor's numbers and the typed bindings around them.
+export {
+  X_BUDGET_BURST_CEILING,
+  X_BUDGET_CEILING,
+  X_BUDGET_MAX_RETRY_AFTER_S,
+  X_BUDGET_WINDOW_MS,
+  X_CALL_WEIGHTS,
+  X_RATE_BUDGET,
+  XBudget,
+  XBudgetError,
+  xBudgetPath,
+  xCallWeight,
+} from './x-budget.ts';
+export type { XBudgetErrorKind, XBudgetOptions, XBudgetReservation, XBudgetSnapshot } from './x-budget.ts';
+
+import type { TwinPack } from '@volter/world-core';
+import { X_RATE_BUDGET as RATE_BUDGET } from './x-budget.ts';
+
+/**
+ * The api.x.com / api.twitter.com paths THIS pack serves, as a RegExp SOURCE for the descriptor's
+ * `hosts` path rule (the injector compiles it with `new RegExp` and tests it against the pathname).
+ * The POSTING slice — create/quote/reply (one route), retract, post lookup (single and bulk),
+ * recent search, the three per-user timelines (mentions, the account's own posts, the home
+ * timeline), user lookup by id and by username, and image upload (one-shot and chunked) — plus the
+ * twin-only control prefix. The user-id
+ * rule EXCLUDES `/2/users/me`: that route is xidentity's, and the two claims stay disjoint. ANCHORED: an unanchored claim would swallow
+ * `/2/tweetsomething`. Everything else on api.x.com stays unclaimed, so an unmodelled X call
+ * refuses loudly rather than landing in a twin that cannot serve it.
+ */
+const X_API_PATHS = '^(?:/2/media/upload/?|/2/media/upload/initialize/?|/2/media/upload/[0-9]+/(?:append|finalize)/?|/2/tweets/?|/2/tweets/[^/]+/?|/2/tweets/search/recent/?|/2/users/(?!me/?$)[^/]+/?|/2/users/by/username/[^/]+/?|/2/users/[^/]+/mentions/?|/2/users/[^/]+/tweets/?|/2/users/[^/]+/timelines/reverse_chronological/?)$|^/_twin/';
+
+export const pack: TwinPack = {
+  vendor: 'x',
+  // The SAME object x-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector arm identical numbers.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-x',
+  resources: ['account', 'token', 'post', 'follow', 'rate_limit'],
+  specSource: 'X API v2 posting surface — POST /2/tweets (original post, QUOTE and reply, told apart by quote_tweet_id / reply.in_reply_to_tweet_id), DELETE /2/tweets/:id, GET /2/tweets/:id and GET /2/tweets?ids=, GET /2/tweets/search/recent, GET /2/users/:id/{mentions,tweets,timelines/reverse_chronological}, GET /2/users/:id and GET /2/users/by/username/:username, with tweet.fields/user.fields/expansions projection and next_token paging. Routes and body shapes grounded in the pinned twitter-api-v2@1.29.1 client source; error envelopes and the scope catalog transcribed from packages/twin/xidentity (X API v2 OpenAPI 2.167). See test-fixtures/x-openapi-operations.SOURCE.md.',
+  description: "X twin — the org's public voice: post, quote, reply to a mention, retract, look a post or an account back up, and read the mentions / own / home timelines and recent search, offline, with X's own tweet.fields projection, bearer/scope gate and problem envelopes. OAuth itself is xidentity's and stays there.",
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  //
+  // `twitter-api-v2` is claimed by THIS pack, not by `xidentity`: it is a third-party library
+  // spanning the whole X API (posts, streams, DMs), and this pack models the POSTING surface it is
+  // actually installed for. No env stem is claimed — X_CLIENT_ID / X_CLIENT_SECRET and
+  // TWITTER_CLIENT_ID name the OAuth APP credentials, which is xidentity's surface; a repo that
+  // posts holds a user access token that flow minted, so the app credential and the posting client
+  // are the same integration seen from two sides and both twins report as covered.
+  adoption: {
+    // COMMUNITY: X ships no Python SDK (its official clients are `@xdevplatform/xdk` and the legacy
+    // `twitter-api-sdk`, both TypeScript). `tweepy` is the de-facto Python client of the X API and is
+    // claimed HERE rather than on `xidentity` because its dominant use is exactly this pack's surface
+    // - posting and reading tweets/mentions - not the OAuth token exchange. One name, one pack.
+    pypi: ['tweepy'],
+    sdks: ['twitter-api-v2'],
+  },
+  // The POSTING surface — the org's public voice. Path-scoped for the same reason xidentity is:
+  // api.x.com is the whole X API v2 host and this pack models one slice. The two packs' path sets
+  // are DISJOINT BY CONSTRUCTION: `xidentity` claims `/2/oauth2/{token,revoke}` and `/2/users/me`;
+  // this claims `/2/tweets*`, the per-user timelines, `/2/users/{id}` and
+  // `/2/users/by/username/{username}`. The user-id rule carries a `(?!me/?$)` lookahead and the
+  // timeline rules need a trailing segment, so `/2/users/me` matches none of them and no request
+  // is claimable by both. ANCHORED, the
+  // googleoauth lesson: an unanchored claim swallows `/2/tweetsomething`. Everything else on
+  // api.x.com — DMs, spaces, lists, media metadata — stays unclaimed, so an unmodelled X call
+  // refuses loudly rather than landing in a twin that cannot serve it. api.twitter.com is claimed
+  // alongside api.x.com because that is the host X's own legacy clients still target.
+  hosts: [
+    { host: 'api.x.com', pathPattern: X_API_PATHS },
+    { host: 'api.twitter.com', pathPattern: X_API_PATHS },
+  ],
+  browserRouting: { apiPathPrefix: '/2/', loaderHost: 'https://api.x.com' },
+};

package/src/x-budget.ts

@@ -0,0 +1,150 @@
+// The X posting surface's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus
+// the thin typed bindings `liveXExecute` 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).
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// The vendor's SCHEME is first-party and recorded in this repo: X publishes per-endpoint rate
+// limits on 15-minute windows and answers an exceeded window with HTTP 429 and legacy error
+// code 88 (docs.x.com/x-api/fundamentals/rate-limits, fetched 2026-08-21 — the fetch recorded in
+// spec-sources.json's `xidentity` entry, and transcribed by
+// packages/twin/xidentity/src/xidentity-budget.ts). This declaration transcribes the SCHEME: the
+// window is the vendor's own 15 minutes, and 429/code-88 is what the guard expects back.
+//
+// EVIDENCE BOUNDARY — READ THIS BEFORE TRUSTING THE NUMBER. The per-endpoint FIGURES for the
+// POSTING endpoints (`POST /2/tweets`, `DELETE /2/tweets/:id`, `GET /2/users/:id/mentions`) were
+// NOT fetched by this build: no X call is made anywhere in this pack, by standing rule, and the
+// figure recorded in this repo covers `GET /2/users/me` only. So the ceiling here is NOT a
+// transcription — it is a deliberately CONSERVATIVE choice: 50 weighted units per 15 minutes,
+// BELOW every posting figure X is reported to publish, with a WRITE priced at 5 and a read at 1
+// so a runaway poster exhausts the budget an order of magnitude before a runaway reader does.
+// Pinning these to the vendor's published figures is `x.rate_limit.published_figures` (todo).
+// A budget that is too tight fails closed and costs a retry; one that is too loose spends a real
+// org's real posting allowance, so the asymmetry decides the direction.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'x';
+
+/** Rolling window, in ms — X's own 15-minute rate-limit window. */
+export const X_BUDGET_WINDOW_MS = 15 * 60_000;
+
+/** Weighted units allowed inside one window. See the EVIDENCE BOUNDARY above: conservative, not
+ *  transcribed. */
+export const X_BUDGET_CEILING = 50;
+
+/** Weighted units allowed in any 60s (the kernel's burst sub-window): 10, well under the kernel
+ *  fallback's burst of 30, so no VENDOR_BURST_ANCHOR entry is required in
+ *  scripts/rate-budget-isolation.test.ts. */
+export const X_BUDGET_BURST_CEILING = 10;
+
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const X_BUDGET_MAX_RETRY_AFTER_S = 900;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. */
+export const X_CALL_WEIGHTS = {
+  /** A post or a reply — the org's public voice SPEAKING. The expensive act. */
+  write: 5,
+  /** Reading who mentioned the org. Cheap: it is the input to a decision, not an act. */
+  read: 1,
+  /** A media upload call (one-shot, initialize, append, finalize) and its STATUS read. Staging a
+   *  file publishes nothing — only the post that attaches it speaks — so it is priced as a read:
+   *  the smallest weight the kernel allows, the post itself still paying the write. */
+  media: 1,
+  /** Everything else on the vendor: no figure of our own → priced at the write. */
+  other: 5,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only X-specific thing in the whole budget. */
+export const X_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: X_BUDGET_WINDOW_MS,
+  ceiling: X_BUDGET_CEILING,
+  burstCeiling: X_BUDGET_BURST_CEILING,
+  defaultWeight: X_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: X_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /2/tweets$', weight: X_CALL_WEIGHTS.write },
+    { match: '^DELETE /2/tweets/', weight: X_CALL_WEIGHTS.write },
+    { match: '^GET /2/users/[^/]+/mentions$', weight: X_CALL_WEIGHTS.read },
+    { match: '^POST /2/media/upload(?:/initialize|/[0-9]+/(?:append|finalize))?$', weight: X_CALL_WEIGHTS.media },
+    { match: '^GET /2/media/upload$', weight: X_CALL_WEIGHTS.media },
+  ],
+  reason:
+    "X publishes per-endpoint rate limits on 15-minute windows and answers an exceeded window with "
+    + 'HTTP 429 and legacy error code 88 (docs.x.com/x-api/fundamentals/rate-limits, fetched '
+    + '2026-08-21 and recorded in spec-sources.json under xidentity). The WINDOW here is the '
+    + "vendor's own 15 minutes and the 429/code-88 pair is what the guard expects back. The "
+    + 'per-endpoint FIGURES for the posting endpoints were NOT fetched by this build — no X call is '
+    + 'made anywhere in this pack, and the figure this repo holds covers GET /2/users/me only — so '
+    + 'the ceiling of 50 units is a deliberately CONSERVATIVE choice rather than a transcription, '
+    + 'sitting below every posting figure X is reported to publish. A write (a post or a reply — the '
+    + "org's public voice speaking, on a real account, in public) costs 5; reading the mentions "
+    + 'timeline costs 1, because reading is the input to a decision and posting is the act. So a '
+    + 'runaway poster exhausts the window after ten posts while a runaway reader gets fifty reads. '
+    + 'A media upload call (one-shot, initialize, append, finalize, STATUS) costs 1: staging a file '
+    + 'publishes nothing, and the post that attaches it still pays the write. '
+    + 'Pinning these to the vendor\'s published posting figures is x.rate_limit.published_figures '
+    + '(todo). A budget that is too tight fails closed and costs a retry; one that is too loose '
+    + "spends a real org's real posting allowance in public, so the asymmetry decides the direction. "
+    + "The burstCeiling of 10 units/60s bounds the instant and stays under the kernel fallback's 30.",
+};
+
+// Declared at module load, so merely importing this module (which `x-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, X_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise
+ * trivially evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/2/tweets')` really does post in public and must be priced as one.
+ */
+export function xCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export function xBudgetPath(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 must not
+  // redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type XBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof XBudget` means "a budget that accounts against X's ledger under
+ * X's ceiling".
+ */
+export class XBudget extends RateBudget {
+  constructor(opts: XBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export { RateBudgetError as XBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as XBudgetErrorKind } from '@volter/world-core';
+export type XBudgetReservation = RateBudgetReservation;
+export type XBudgetSnapshot = RateBudgetSnapshot;