@volter/twin-x 0.1.0

package/src/x-capabilities.ts

@@ -0,0 +1,1161 @@
+// THE X PACK'S CAPABILITY MANIFEST — the real vendor surface as the DENOMINATOR, not a list of
+// what got built. The denominator here is X API v2's POST OBJECT and the per-user timelines and
+// engagement verbs over it, plus user lookup by id and by username (the curated boundary
+// `x-spec-census.json` declares in `scopePaths`), plus the media a post carries — image and video
+// upload. Follows, lists, spaces, communities, direct messages, compliance and usage
+// are X surface this manifest deliberately does NOT enumerate — they are outside the census's
+// committed boundary, and claiming them here would inflate a denominator nothing measures.
+// (`packages/twin/xidentity` owns X's OAuth + identity surface and its own denominator.)
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { pushXAction, xRequestForAction, syncXFromReal, type XExecute } from './x-connector.ts';
+import { X_BUDGET_CEILING, X_CALL_WEIGHTS, X_RATE_BUDGET, XBudget, XBudgetError, xCallWeight } from './x-budget.ts';
+import { handleXTwinRequest } from './x-twin.ts';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { PostRow, ProfileHeader } from '../client/x-mirror.tsx';
+import { createXMirrorServer, joinedLabel, POST_READ_QUERY, PROFILE_READ_QUERY, tweetsById, usersById, type XRow } from './x-mirror-ui.ts';
+
+type Body = Record<string, any>;
+type Step = { m: string; p: string; b?: unknown; headers?: Record<string, string>; readOnly?: boolean };
+
+const ORG = '1000';
+const MEMBER = '2000';
+const TOKEN = 'org-voice-token';
+const FULL_SCOPES = ['tweet.read', 'tweet.write', 'users.read'];
+const AUTH = { authorization: `Bearer ${TOKEN}` };
+// X returns id/text/edit_history_tweet_ids and NOTHING ELSE unless the caller asks. Every
+// verify below that asserts a threading field therefore REQUESTS it — which is itself half the
+// proof of `x.fields.tweet_fields`: drop the projection and these reads stop carrying the
+// fields they assert on.
+const THREAD_FIELDS = 'tweet.fields=author_id,conversation_id,created_at,in_reply_to_user_id,referenced_tweets';
+
+type Handle = (step: Step) => Promise<{ status: number; body: unknown; headers?: Record<string, string> }>;
+
+/**
+ * A throwaway world with the org's account, a member's account, and a bearer the way xidentity's
+ * flow would have minted one. Every verify below runs against real twin state — a create→read→
+ * assert, never a status-only check.
+ */
+async function withWorld(fn: (h: Handle, root: string) => Promise<boolean>, opts: { scopes?: string[] } = {}): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'x-cap-'));
+  const h: Handle = (step) => handleXTwinRequest({
+    method: step.m,
+    path: step.p,
+    body: step.b === undefined ? undefined : JSON.stringify(step.b),
+    root,
+    readOnly: step.readOnly,
+    occurredAt: new Date().toISOString(),
+    headers: step.headers ?? AUTH,
+  });
+  try {
+    return await verifyBoundary('x.withWorld', async () => {
+      await h({ m: 'POST', p: '/_twin/accounts', b: { id: ORG, username: 'orgvoice', name: 'Org Voice' }, headers: {} });
+      await h({ m: 'POST', p: '/_twin/accounts', b: { id: MEMBER, username: 'member', name: 'A Member' }, headers: {} });
+      await h({ m: 'POST', p: '/_twin/tokens', b: { token: TOKEN, account_id: ORG, scopes: opts.scopes ?? FULL_SCOPES }, headers: {} });
+      return fn(h, root);
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Seed an inbound mention from the member and return its id — the input to the reply class. */
+async function seedMention(h: Handle, text = 'hey @orgvoice can you help?'): Promise<string> {
+  const seeded = await h({ m: 'POST', p: '/_twin/posts', b: { author_id: MEMBER, text }, headers: {} });
+  return String((seeded.body as Body).data.id);
+}
+
+// ── media fixtures: the smallest bytes the twin reads as an image and as a video ─────────────
+function box(type: string, payload: Uint8Array): Uint8Array {
+  const out = new Uint8Array(8 + payload.length);
+  new DataView(out.buffer).setUint32(0, out.length);
+  out.set(new TextEncoder().encode(type), 4);
+  out.set(payload, 8);
+  return out;
+}
+const concat = (...parts: Uint8Array[]): Uint8Array => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+};
+/** A PNG header naming a 64x48 image (the twin reads type and size from the header, as X does). */
+function tinyPng(): Uint8Array {
+  const ihdr = new Uint8Array(13);
+  new DataView(ihdr.buffer).setUint32(0, 64);
+  new DataView(ihdr.buffer).setUint32(4, 48);
+  ihdr.set([8, 2, 0, 0, 0], 8);
+  return concat(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), box('IHDR', ihdr), new Uint8Array(4));
+}
+/** An MP4's boxes for a 3-second 640x360 video: ftyp, then moov with mvhd and a video tkhd. */
+function tinyMp4(): Uint8Array {
+  const mvhd = new Uint8Array(100);
+  new DataView(mvhd.buffer).setUint32(12, 1000);
+  new DataView(mvhd.buffer).setUint32(16, 3000);
+  const tkhd = new Uint8Array(84);
+  new DataView(tkhd.buffer).setUint32(76, 640 << 16);
+  new DataView(tkhd.buffer).setUint32(80, 360 << 16);
+  return concat(box('ftyp', new TextEncoder().encode('isom\0\0\x02\0isom')), box('mdat', new Uint8Array(4096)), box('moov', concat(box('mvhd', mvhd), box('trak', box('tkhd', tkhd)))));
+}
+const b64 = (bytes: Uint8Array): string => Buffer.from(bytes).toString('base64');
+const MEDIA_AUTH = { authorization: 'Bearer org-media-token' };
+/** Register a bearer that also holds `media.write`, which the upload endpoints require. */
+async function mediaToken(h: Handle): Promise<void> {
+  await h({ m: 'POST', p: '/_twin/tokens', b: { token: 'org-media-token', account_id: ORG, scopes: [...FULL_SCOPES, 'media.write'] }, headers: {} });
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const X_CAPABILITIES: CapabilitySpec[] = [
+  // ── streaming + media (X's OAuth 2.0 authorize/token/refresh/revoke round trip is owned by
+  // packages/twin/xidentity; this pack CONSUMES the user access token that flow mints) ─────────
+  todo('x.stream.filtered', 'streaming', 'Filtered stream (GET /2/tweets/search/stream): serve the long-lived streaming connection over the twin\'s stored posts, matching the filtered-stream rules, with reconnect and backfill_minutes semantics', 'api', 'common'),
+  todo('x.stream.sampled', 'streaming', 'Sampled volume streams (GET /2/tweets/sample/stream and sample10): serve the streaming connection over the twin\'s stored posts with the vendor\'s partitioning parameters', 'api', 'niche'),
+  done('x.media.upload', 'media', 'Media upload: POST /2/media/upload for an image, and the chunked initialize/append/finalize protocol with its STATUS-polled processing states for a video, persisting the bytes and returning a media_id attachable to a post', 'api', 'common', () =>
+    withWorld(async (h) => {
+      await mediaToken(h);
+      // an image in one request, base64 in a JSON body: its size and dimensions read from its bytes
+      const image = await h({ m: 'POST', p: '/2/media/upload', b: { media: b64(tinyPng()), media_category: 'tweet_image' }, headers: MEDIA_AUTH });
+      const img = (image.body as Body).data;
+      if (image.status !== 200 || !/^3_\d+$/.test(img?.media_key) || img.image?.w !== 64 || img.image?.h !== 48 || img.expires_after_secs !== 86400) return false;
+      // media.write is required: the posting token without it is refused
+      const noScope = await h({ m: 'POST', p: '/2/media/upload', b: { media: b64(tinyPng()), media_category: 'tweet_image' } });
+      if (noScope.status !== 403) return false;
+      // a video in two segments, then processing walked by STATUS
+      const mp4 = tinyMp4();
+      const init = await h({ m: 'POST', p: '/2/media/upload/initialize', b: { media_type: 'video/mp4', total_bytes: mp4.length, media_category: 'tweet_video' }, headers: MEDIA_AUTH });
+      const id = (init.body as Body).data?.id as string;
+      if (init.status !== 200 || !/^7_\d+$/.test((init.body as Body).data?.media_key)) return false;
+      const half = Math.floor(mp4.length / 2);
+      for (const [index, part] of [[0, mp4.subarray(0, half)], [1, mp4.subarray(half)]] as const) {
+        const appended = await h({ m: 'POST', p: `/2/media/upload/${id}/append`, b: { media: b64(part), segment_index: index }, headers: MEDIA_AUTH });
+        if (appended.status !== 200) return false;
+      }
+      const finalized = (await h({ m: 'POST', p: `/2/media/upload/${id}/finalize`, headers: MEDIA_AUTH })).body as Body;
+      if (finalized.data?.size !== mp4.length || finalized.data?.processing_info?.state !== 'pending') return false;
+      const early = await h({ m: 'POST', p: '/2/tweets', b: { text: 'too soon', media: { media_ids: [id] } }, headers: MEDIA_AUTH });
+      if (early.status !== 400) return false;
+      const states: string[] = [];
+      for (let i = 0; i < 2; i += 1) states.push(((await h({ m: 'GET', p: `/2/media/upload?command=STATUS&media_id=${id}`, headers: MEDIA_AUTH })).body as Body).data?.processing_info?.state);
+      return states.join(',') === 'in_progress,succeeded';
+    })),
+  todo('x.media.video_poster_frame', 'media', "A video's preview_image_url as a frame of the video (the twin decodes nothing and serves a stand-in poster at the video's size)", 'api', 'common'),
+  todo('x.media.video_transcode_variants', 'media', "The variants X's transcoder publishes (an HLS playlist and several MP4 bit rates) rather than the one uploaded file", 'api', 'niche'),
+  todo('x.media.gif', 'media', 'Animated GIF upload (tweet_gif) and its animated_gif media type', 'api', 'common'),
+  todo('x.media.alt_text', 'media', 'Alt text on an image (POST /2/media/metadata) and the alt_text media field', 'api', 'common'),
+
+  // ── the ORIGINAL POST class (POST /2/tweets, no reply object) ────────────────────────────────
+  done('x.tweets.create', 'tweets', 'Create an original post (POST /2/tweets)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'the org speaks' } });
+      const body = created.body as Body;
+      if (created.status !== 201 || typeof body.data?.id !== 'string' || body.data.text !== 'the org speaks') return false;
+      // Read it back through the twin's own state: a create that does not land is not a create.
+      const seenFrom = await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions`, headers: AUTH });
+      // The org's own post mentions nobody, so the member's mentions timeline stays empty —
+      // which is the read-back that proves the post is real STATE, not an echoed request.
+      return seenFrom.status === 200 && (seenFrom.body as Body).meta.result_count === 0;
+    })),
+  done('x.tweets.create_shape', 'tweets', "Create answers X's thin {id, text, edit_history_tweet_ids} envelope", 'api', 'core', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'shape check' } });
+      const data = (created.body as Body).data;
+      return created.status === 201
+        && Object.keys(data).sort().join(',') === 'edit_history_tweet_ids,id,text'
+        && Array.isArray(data.edit_history_tweet_ids)
+        && data.edit_history_tweet_ids.length === 1
+        && data.edit_history_tweet_ids[0] === data.id;
+    })),
+  done('x.tweets.create_is_its_own_conversation', 'tweets', 'An original post starts its own conversation', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member welcome' } });
+      const id = (created.body as Body).data.id;
+      const mentions = await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions?${THREAD_FIELDS}` });
+      const row = (mentions.body as Body).data[0];
+      // conversation_id === its own id, and it carries no referenced_tweets: this is a root post.
+      return row.id === id && row.conversation_id === id && row.referenced_tweets === undefined && row.in_reply_to_user_id === undefined;
+    })),
+  done('x.tweets.create_requires_text', 'tweets', 'A create with no text is the invalid-request problem', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/2/tweets', b: {} });
+      const body = r.body as Body;
+      return r.status === 400
+        && body.type === 'https://api.x.com/2/problems/invalid-request'
+        && body.title === 'Invalid Request'
+        && Array.isArray(body.errors) && body.errors[0].parameters.text !== undefined;
+    })),
+  done('x.tweets.ids_are_snowflake_shaped_and_unique', 'tweets', 'Minted post ids are numeric snowflakes, never a row count', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const ids: string[] = [];
+      for (const text of ['one', 'two', 'three']) {
+        const r = await h({ m: 'POST', p: '/2/tweets', b: { text } });
+        ids.push((r.body as Body).data.id);
+      }
+      // Derived from the id SET already in state, so a pulled vendor id above the row count can
+      // never be clobbered by a later local create.
+      return ids.every((id) => /^\d{19}$/.test(id)) && new Set(ids).size === 3
+        && BigInt(ids[1]!) > BigInt(ids[0]!) && BigInt(ids[2]!) > BigInt(ids[1]!);
+    })),
+
+  // ── the MENTION-REPLY class (POST /2/tweets WITH reply.in_reply_to_tweet_id) ─────────────────
+  // Same route, same method, same vendor operation as the class above. Everything that makes
+  // them two things lives in the body field these verifies exercise.
+  done('x.tweets.reply', 'tweets', 'Reply to a post (POST /2/tweets with reply.in_reply_to_tweet_id)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const mentionId = await seedMention(h);
+      // The text carries `@member` because that is what a reply on X looks like: the client
+      // prepends the parent author's handle, so a reply IS a mention of them. The twin does not
+      // rewrite text, so the verify posts what a client would post.
+      const replied = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member happy to help', reply: { in_reply_to_tweet_id: mentionId } } });
+      if (replied.status !== 201) return false;
+      const replyId = (replied.body as Body).data.id;
+      // Read the reply back out of real twin state through the MEMBER's mentions timeline, and
+      // assert the THREADING the body field caused — not the status the request returned.
+      const conversation = await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions?${THREAD_FIELDS}` });
+      const rows = (conversation.body as Body).data as Body[];
+      const stored = rows.find((r) => r.id === replyId);
+      return stored !== undefined
+        && stored.in_reply_to_user_id === MEMBER
+        && stored.conversation_id === mentionId
+        && stored.referenced_tweets?.[0]?.type === 'replied_to'
+        && stored.referenced_tweets?.[0]?.id === mentionId;
+    })),
+  done('x.tweets.reply_joins_the_parent_conversation', 'tweets', "A reply inherits the parent's conversation_id, not its own", 'api', 'core', () =>
+    withWorld(async (h) => {
+      const rootId = await seedMention(h);
+      const first = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member one', reply: { in_reply_to_tweet_id: rootId } } });
+      const firstId = (first.body as Body).data.id;
+      const second = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member two', reply: { in_reply_to_tweet_id: firstId } } });
+      const secondId = (second.body as Body).data.id;
+      const rows = (await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions?${THREAD_FIELDS}` })).body as Body;
+      const deep = (rows.data as Body[]).find((r) => r.id === secondId);
+      // Two levels down the thread and still in the ROOT's conversation — the vendor's rule.
+      return deep?.conversation_id === rootId && deep?.referenced_tweets?.[0]?.id === firstId;
+    })),
+  done('x.tweets.reply_to_missing_post_refuses', 'tweets', 'A reply to a post that does not exist is resource-not-found', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'to nobody', reply: { in_reply_to_tweet_id: '404404404404404404' } } });
+      const body = r.body as Body;
+      return r.status === 404
+        && body.errors?.[0]?.resource_type === 'tweet'
+        && body.errors?.[0]?.parameter === 'reply.in_reply_to_tweet_id'
+        && body.errors?.[0]?.type === 'https://api.twitter.com/2/problems/resource-not-found';
+    })),
+  done('x.tweets.reply_to_deleted_post_refuses', 'tweets', 'A reply to a RETRACTED post refuses rather than resurrecting the thread', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'temporary' } });
+      const id = (created.body as Body).data.id;
+      await h({ m: 'DELETE', p: `/2/tweets/${id}` });
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'late', reply: { in_reply_to_tweet_id: id } } });
+      return r.status === 404;
+    })),
+  done('x.tweets.reply_and_post_are_one_route', 'tweets', 'Reply and original post are the SAME method+path, told apart only by the body', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const mentionId = await seedMention(h);
+      const post = await h({ m: 'POST', p: '/2/tweets', b: { text: 'a' } });
+      const reply = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member b', reply: { in_reply_to_tweet_id: mentionId } } });
+      const rows = (await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions?${THREAD_FIELDS}` })).body as Body;
+      const stored = (rows.data as Body[]).find((r) => r.id === (reply.body as Body).data.id);
+      // Identical requests apart from one field; two different things stored. THIS is the fact
+      // the census's body-field discriminator exists to make expressible in a grant.
+      return post.status === 201 && reply.status === 201
+        && stored?.referenced_tweets?.[0]?.type === 'replied_to'
+        && stored?.conversation_id === mentionId;
+    })),
+  done('x.tweets.reply_null_discriminator_is_an_original_post', 'tweets', 'A null in_reply_to_tweet_id is an original post, not a broken reply', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'plain', reply: { in_reply_to_tweet_id: null } } });
+      if (r.status !== 201) return false;
+      const id = (r.body as Body).data.id;
+      const seeded = await h({ m: 'POST', p: '/_twin/posts', b: { author_id: MEMBER, text: `@orgvoice re ${id}` }, headers: {} });
+      const rows = (await h({ m: 'GET', p: `/2/users/${ORG}/mentions` })).body as Body;
+      return String((seeded.body as Body).data.id) === (rows.data as Body[])[0]!.id;
+    })),
+
+  // ── the QUOTE class (POST /2/tweets WITH quote_tweet_id) ─────────────────────────────────────
+  // A third body-field discriminator on the same one route. A quote CITES rather than answers, so
+  // for the census's reply/original split it is an ORIGINAL post — the org speaking under its own
+  // name — and it starts its own conversation.
+  done('x.tweets.quote', 'tweets', 'Quote post (POST /2/tweets with quote_tweet_id)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const quotedId = await seedMention(h, 'the member said something quotable');
+      const quote = await h({ m: 'POST', p: '/2/tweets', b: { text: 'worth reading', quote_tweet_id: quotedId } });
+      if (quote.status !== 201) return false;
+      const id = (quote.body as Body).data.id;
+      const row = ((await h({ m: 'GET', p: `/2/tweets/${id}?${THREAD_FIELDS}` })).body as Body).data;
+      const missing = await h({ m: 'POST', p: '/2/tweets', b: { text: 'nope', quote_tweet_id: '404404404404404404' } });
+      // The quoted post is REFERENCED as `quoted`, not `replied_to`; the quote is its own
+      // conversation root and answers nobody. All three follow from the one body field.
+      return row.id === id && row.conversation_id === id && row.in_reply_to_user_id === undefined
+        && row.referenced_tweets?.length === 1
+        && row.referenced_tweets[0].type === 'quoted' && row.referenced_tweets[0].id === quotedId
+        && missing.status === 404
+        && (missing.body as Body).errors?.[0]?.parameter === 'quote_tweet_id'
+        && (missing.body as Body).errors?.[0]?.resource_type === 'tweet';
+    })),
+
+  // ── lookup (GET /2/tweets/:id and GET /2/tweets?ids=) ────────────────────────────────────────
+  done('x.tweets.lookup_by_id', 'tweets', 'Post lookup (GET /2/tweets/:id)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'read me back' } });
+      const id = (created.body as Body).data.id;
+      const found = await h({ m: 'GET', p: `/2/tweets/${id}?tweet.fields=author_id,created_at` });
+      const row = (found.body as Body).data;
+      // NEVER A FABRICATED RECORD. An id nobody created comes back inside `errors`, by name, with
+      // no `data` at all — the difference between a twin and a mock that agrees with any question.
+      const ghost = (await h({ m: 'GET', p: '/2/tweets/404404404404404404' })).body as Body;
+      const malformed = await h({ m: 'GET', p: '/2/tweets/not-a-snowflake' });
+      // …and a RETRACTED post stays gone rather than being resurrected by a later read.
+      await h({ m: 'DELETE', p: `/2/tweets/${id}` });
+      const afterDelete = (await h({ m: 'GET', p: `/2/tweets/${id}` })).body as Body;
+      return found.status === 200 && row.id === id && row.text === 'read me back'
+        && row.author_id === ORG && typeof row.created_at === 'string'
+        && ghost.data === undefined && ghost.errors?.[0]?.resource_type === 'tweet'
+        && ghost.errors[0].value === '404404404404404404' && ghost.errors[0].parameter === 'id'
+        && afterDelete.data === undefined && afterDelete.errors?.[0]?.value === id
+        && malformed.status === 400 && (malformed.body as Body).errors?.[0]?.parameters?.id?.[0] === 'not-a-snowflake';
+    })),
+  done('x.tweets.lookup_by_ids', 'tweets', 'Bulk post lookup (GET /2/tweets?ids=)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const first = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'one' } })).body as Body).data.id;
+      const second = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'two' } })).body as Body).data.id;
+      const r = await h({ m: 'GET', p: `/2/tweets?ids=${first},404404404404404404,${second}` });
+      const body = r.body as Body;
+      const noIds = await h({ m: 'GET', p: '/2/tweets' });
+      const rows = body.data as Body[];
+      // PARTIAL, the way X answers a bulk lookup: the ids that exist in `data`, in the order the
+      // caller asked for them, and the one that does not in `errors` — never three invented rows.
+      return r.status === 200
+        && rows.map((row) => row.id).join(',') === `${first},${second}`
+        && rows.map((row) => row.text).join(',') === 'one,two'
+        && body.errors?.length === 1 && body.errors[0].value === '404404404404404404'
+        && body.errors[0].parameter === 'ids'
+        && noIds.status === 400 && (noIds.body as Body).errors?.[0]?.parameters?.ids !== undefined;
+    })),
+
+  // ── the field projection (tweet.fields / expansions) ─────────────────────────────────────────
+  done('x.fields.tweet_fields', 'fields', 'tweet.fields projection on every post-returning read', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const id = await seedMention(h);
+      const bare = ((await h({ m: 'GET', p: `/2/users/${ORG}/mentions` })).body as Body).data[0];
+      const asked = ((await h({ m: 'GET', p: `/2/users/${ORG}/mentions?tweet.fields=author_id,created_at` })).body as Body).data[0];
+      const lookup = ((await h({ m: 'GET', p: `/2/tweets/${id}?tweet.fields=conversation_id` })).body as Body).data;
+      const unknown = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?tweet.fields=not_a_field` });
+      const unmodelled = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?tweet.fields=public_metrics` });
+      // THE DEFAULT IS X'S THREE FIELDS AND NOTHING ELSE. A twin that returned everything always
+      // would pass an integrator whose client forgets tweet.fields and break them in production.
+      return Object.keys(bare).sort().join(',') === 'edit_history_tweet_ids,id,text'
+        && Object.keys(asked).sort().join(',') === 'author_id,created_at,edit_history_tweet_ids,id,text'
+        && asked.author_id === MEMBER && typeof asked.created_at === 'string'
+        && Object.keys(lookup).sort().join(',') === 'conversation_id,edit_history_tweet_ids,id,text'
+        && lookup.conversation_id === id
+        // an UNDOCUMENTED value is the vendor's refusal; a DOCUMENTED value this twin holds no
+        // state for is refused too, rather than silently omitted (a caller cannot tell an
+        // unmodelled field from an absent one).
+        && unknown.status === 400 && (unknown.body as Body).errors?.[0]?.parameters?.['tweet.fields']?.[0] === 'not_a_field'
+        && unmodelled.status === 400 && (unmodelled.body as Body).errors?.[0]?.parameters?.['tweet.fields']?.[0] === 'public_metrics';
+    })),
+  done('x.fields.expansions', 'fields', 'expansions + the `includes` sidecar (author_id, referenced_tweets.id)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const mentionId = await seedMention(h);
+      const replied = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member on it', reply: { in_reply_to_tweet_id: mentionId } } });
+      const replyId = (replied.body as Body).data.id;
+      const expanded = (await h({ m: 'GET', p: `/2/tweets/${replyId}?expansions=author_id,referenced_tweets.id` })).body as Body;
+      const bare = (await h({ m: 'GET', p: `/2/tweets/${replyId}` })).body as Body;
+      const unmodelled = await h({ m: 'GET', p: `/2/tweets/${replyId}?expansions=geo.place_id` });
+      const unknown = await h({ m: 'GET', p: `/2/tweets/${replyId}?expansions=not_an_expansion` });
+      return expanded.data.author_id === ORG
+        && expanded.data.referenced_tweets?.[0]?.id === mentionId
+        && expanded.includes.users?.length === 1
+        && expanded.includes.users[0].id === ORG && expanded.includes.users[0].username === 'orgvoice'
+        && expanded.includes.users[0].name === 'Org Voice'
+        && expanded.includes.tweets?.length === 1
+        && expanded.includes.tweets[0].id === mentionId
+        && expanded.includes.tweets[0].text === 'hey @orgvoice can you help?'
+        // NOTHING expanded means NO sidecar and no source field — the expansion is what produces
+        // both, so a twin that always shipped `includes` would prove nothing here.
+        && bare.includes === undefined && bare.data.author_id === undefined && bare.data.referenced_tweets === undefined
+        && unmodelled.status === 400 && unknown.status === 400;
+    })),
+
+  done('x.fields.user_fields', 'fields', 'user.fields projection on user lookup and inside `includes`', 'api', 'common', () =>
+    withWorld(async (h) => {
+      await h({ m: 'POST', p: '/_twin/accounts', b: { id: '3000', username: 'profiled', name: 'Profiled', description: 'we build things', location: 'Brooklyn', url: 'https://example.org', verified: true }, headers: {} });
+      const own = ((await h({ m: 'POST', p: '/_twin/posts', b: { author_id: '3000', text: 'from the profiled account' }, headers: {} })).body as Body).data.id;
+      const asked = (await h({ m: 'GET', p: '/2/users/3000?user.fields=description,location,url,verified,protected,created_at,most_recent_tweet_id' })).body as Body;
+      const bare = (await h({ m: 'GET', p: '/2/users/3000' })).body as Body;
+      // The same parser shapes the users a post read expands.
+      const expanded = (await h({ m: 'GET', p: `/2/tweets/${own}?expansions=author_id&user.fields=description` })).body as Body;
+      const unmodelled = await h({ m: 'GET', p: '/2/users/3000?user.fields=public_metrics' });
+      const unknown = await h({ m: 'GET', p: '/2/users/3000?user.fields=not_a_field' });
+      return asked.data.description === 'we build things' && asked.data.location === 'Brooklyn'
+        && asked.data.url === 'https://example.org' && asked.data.verified === true && asked.data.protected === false
+        && typeof asked.data.created_at === 'string' && asked.data.most_recent_tweet_id === own
+        // X's default user object is exactly three fields: nothing rides along unasked.
+        && Object.keys(bare.data).sort().join(',') === 'id,name,username'
+        && expanded.includes.users[0].description === 'we build things'
+        && unmodelled.status === 400 && (unmodelled.body as Body).errors?.[0]?.parameters?.['user.fields']?.[0] === 'public_metrics'
+        && unknown.status === 400;
+    })),
+
+  // ── user lookup ──────────────────────────────────────────────────────────────────────────────
+  done('x.users.lookup_by_id', 'users', 'User lookup by id (GET /2/users/:id)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const found = await h({ m: 'GET', p: `/2/users/${ORG}` });
+      const missing = await h({ m: 'GET', p: '/2/users/424242' });
+      const malformed = await h({ m: 'GET', p: '/2/users/not-an-id' });
+      const missingBody = missing.body as Body;
+      return found.status === 200 && (found.body as Body).data.id === ORG
+        && (found.body as Body).data.username === 'orgvoice' && (found.body as Body).data.name === 'Org Voice'
+        // X's partial-error 200: no `data`, one `errors` row naming the user id.
+        && missing.status === 200 && missingBody.data === undefined
+        && missingBody.errors?.[0]?.resource_type === 'user' && missingBody.errors[0].value === '424242'
+        && malformed.status === 400;
+    })),
+  done('x.users.lookup_by_username', 'users', 'User lookup by username (GET /2/users/by/username/:username)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const exact = (await h({ m: 'GET', p: '/2/users/by/username/orgvoice' })).body as Body;
+      // Handles are case-insensitive at X.
+      const cased = (await h({ m: 'GET', p: '/2/users/by/username/OrgVoice' })).body as Body;
+      const missing = await h({ m: 'GET', p: '/2/users/by/username/nobodyhere' });
+      const malformed = await h({ m: 'GET', p: '/2/users/by/username/has-a-dash' });
+      const anon = await h({ m: 'GET', p: '/2/users/by/username/orgvoice', headers: {} });
+      return exact.data?.id === ORG && cased.data?.id === ORG
+        && missing.status === 200 && (missing.body as Body).errors?.[0]?.parameter === 'username'
+        && (missing.body as Body).errors[0].resource_type === 'user'
+        && malformed.status === 400 && anon.status === 401;
+    })),
+  done('x.users.lookup_scope_gate', 'users', 'User lookup refuses a token without users.read', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const refused = await h({ m: 'GET', p: `/2/users/${ORG}` });
+      return refused.status === 403;
+    }, { scopes: ['tweet.read', 'tweet.write'] })),
+
+  // ── the timelines ────────────────────────────────────────────────────────────────────────────
+  done('x.timelines.user_tweets', 'timelines', 'User posts timeline (GET /2/users/:id/tweets)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const first = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'first thing' } })).body as Body).data.id;
+      const second = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'second thing' } })).body as Body).data.id;
+      await seedMention(h, 'a member post @orgvoice that is NOT ours');
+      const rows = ((await h({ m: 'GET', p: `/2/users/${ORG}/tweets?tweet.fields=author_id` })).body as Body).data as Body[];
+      // DIRTY STATE ON PURPOSE: retract the newer post and read the timeline again. A fresh-root
+      // verify could never see a delete failing to leave the author's own timeline.
+      await h({ m: 'DELETE', p: `/2/tweets/${second}` });
+      const after = ((await h({ m: 'GET', p: `/2/users/${ORG}/tweets` })).body as Body).data as Body[];
+      const theirs = (await h({ m: 'GET', p: `/2/users/${MEMBER}/tweets` })).body as Body;
+      const stranger = await h({ m: 'GET', p: '/2/users/999999/tweets' });
+      return rows.map((r) => r.id).join(',') === `${second},${first}`
+        && rows.every((r) => r.author_id === ORG)
+        && after.map((r) => r.id).join(',') === String(first)
+        && theirs.meta.result_count === 1
+        && stranger.status === 404 && (stranger.body as Body).errors?.[0]?.resource_type === 'user';
+    })),
+  done('x.timelines.reverse_chronological', 'timelines', 'Home timeline (GET /2/users/:id/timelines/reverse_chronological)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const mine = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'our own words' } })).body as Body).data.id;
+      const theirs = await seedMention(h, 'a member post that tags nobody');
+      const before = (await h({ m: 'GET', p: `/2/users/${ORG}/timelines/reverse_chronological` })).body as Body;
+      await h({ m: 'POST', p: '/_twin/follows', b: { follower_id: ORG, followed_id: MEMBER }, headers: {} });
+      const after = (await h({ m: 'GET', p: `/2/users/${ORG}/timelines/reverse_chronological?tweet.fields=author_id` })).body as Body;
+      const someoneElses = await h({ m: 'GET', p: `/2/users/${MEMBER}/timelines/reverse_chronological` });
+      // THE FOLLOW EDGE IS WHAT CHANGES THE ANSWER. Before it the home timeline is the account's
+      // own words; after it, it is those plus the account it follows. A twin with no graph could
+      // not tell these two reads apart, which is why the graph is real seeded state.
+      return before.data.length === 1 && before.data[0].id === mine
+        && (after.data as Body[]).map((r) => r.id).join(',') === `${theirs},${mine}`
+        && (after.data as Body[]).map((r) => r.author_id).join(',') === `${MEMBER},${ORG}`
+        && someoneElses.status === 403 && (someoneElses.body as Body).title === 'Forbidden';
+    })),
+  done('x.timelines.pagination', 'timelines', 'pagination_token / next_token paging on a timeline', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const ids: string[] = [];
+      for (let i = 0; i < 12; i += 1) ids.push(await seedMention(h, `n${i} @orgvoice`));
+      const first = (await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5` })).body as Body;
+      const again = (await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5` })).body as Body;
+      const second = (await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5&pagination_token=${first.meta.next_token}` })).body as Body;
+      const third = (await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5&pagination_token=${second.meta.next_token}` })).body as Body;
+      const bad = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?pagination_token=not-a-token` });
+      const walked = [...(first.data as Body[]), ...(second.data as Body[]), ...(third.data as Body[])].map((r) => r.id);
+      return walked.join(',') === [...ids].reverse().join(',')
+        && new Set(walked).size === 12
+        && (third.data as Body[]).length === 2
+        // the LAST page carries no token — an unconditional one walks a client into an empty page
+        // forever — and the token is a pure function of state, so the same page hands back the same
+        // token every time.
+        && third.meta.next_token === undefined
+        && typeof first.meta.next_token === 'string' && again.meta.next_token === first.meta.next_token
+        && bad.status === 400 && (bad.body as Body).errors?.[0]?.parameters?.pagination_token?.[0] === 'not-a-token';
+    })),
+  done('x.timelines.since_until_id', 'timelines', 'since_id / until_id / start_time / end_time timeline windows', 'api', 'core', () =>
+    withWorld(async (h, root) => {
+      // PINNED, DISTINCT occurredAt values. `created_at` is what the WRITE stored, so a time
+      // window can only be asserted over posts whose times were chosen rather than rolled.
+      const at = (day: number) => `2026-08-2${day}T00:00:00.000Z`;
+      const seed = async (day: number, text: string) => {
+        const r = await handleXTwinRequest({ method: 'POST', path: '/_twin/posts', body: JSON.stringify({ author_id: MEMBER, text }), root, occurredAt: at(day) });
+        return String((r.body as Body).data.id);
+      };
+      const one = await seed(1, 'one @orgvoice');
+      const two = await seed(2, 'two @orgvoice');
+      const three = await seed(3, 'three @orgvoice');
+      const ids = (r: { body: unknown }) => ((r.body as Body).data as Body[] | undefined ?? []).map((row) => row.id).join(',');
+      const since = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?since_id=${one}` });
+      const until = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?until_id=${three}` });
+      const window = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?start_time=${at(2)}&end_time=${at(3)}` });
+      // X'S OWN PRECEDENCE: an id bound and a time bound on the same side cannot both apply, and
+      // the id wins. since_id=one WITH start_time=day-3 must still answer two rows, not one.
+      const precedence = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?since_id=${one}&start_time=${at(3)}` });
+      const badId = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?since_id=not-an-id` });
+      const badTime = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?start_time=yesterday` });
+      return ids(since) === `${three},${two}`
+        && ids(until) === `${two},${one}`
+        && ids(window) === String(two)
+        && ids(precedence) === `${three},${two}`
+        && badId.status === 400 && badTime.status === 400
+        && (badTime.body as Body).errors?.[0]?.parameters?.start_time?.[0] === 'yesterday';
+    })),
+
+  // ── recent search ────────────────────────────────────────────────────────────────────────────
+  done('x.search.recent', 'search', 'Recent search (GET /2/tweets/search/recent)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const ours = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'shipping the twin today' } })).body as Body).data.id;
+      await seedMention(h, 'the member is shipping something else');
+      const term = (await h({ m: 'GET', p: '/2/tweets/search/recent?query=shipping' })).body as Body;
+      const scoped = (await h({ m: 'GET', p: '/2/tweets/search/recent?query=shipping from:orgvoice&tweet.fields=author_id' })).body as Body;
+      const phrase = (await h({ m: 'GET', p: '/2/tweets/search/recent?query="shipping the twin"' })).body as Body;
+      const nothing = (await h({ m: 'GET', p: '/2/tweets/search/recent?query=nobodyeversaidthis' })).body as Body;
+      const noQuery = await h({ m: 'GET', p: '/2/tweets/search/recent' });
+      // Grammar this twin does not model is REFUSED, never ignored: answering a query the twin
+      // did not honour is a fake success wearing a 200 (x.search.query_grammar stays a todo).
+      const ungrammatical = await h({ m: 'GET', p: '/2/tweets/search/recent?query=shipping -twin' });
+      // Search bounds max_results at 10 where the timelines allow 5 — the same value, two answers.
+      const tooSmall = await h({ m: 'GET', p: '/2/tweets/search/recent?query=shipping&max_results=5' });
+      const timelineOk = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5` });
+      // X's keyword operator matches TOKENS, not substrings. Substring matching answered `ship`
+      // — and `hipping` — with these rows, a confident result for a query the vendor returns
+      // nothing for, which is worse than refusing the query.
+      const substring = (await h({ m: 'GET', p: '/2/tweets/search/recent?query=hipp' })).body as Body;
+      const phraseOrder = (await h({ m: 'GET', p: '/2/tweets/search/recent?query="twin the shipping"' })).body as Body;
+      const hashtagLike = (await h({ m: 'GET', p: '/2/tweets/search/recent?query=today' })).body as Body;
+      return substring.meta.result_count === 0
+        && phraseOrder.meta.result_count === 0
+        && hashtagLike.meta.result_count === 1
+        && term.meta.result_count === 2
+        && (scoped.data as Body[]).length === 1
+        && (scoped.data as Body[])[0]!.id === ours && (scoped.data as Body[])[0]!.author_id === ORG
+        && (phrase.data as Body[]).length === 1 && (phrase.data as Body[])[0]!.id === ours
+        && nothing.data === undefined && nothing.meta.result_count === 0
+        && noQuery.status === 400
+        && ungrammatical.status === 400 && (ungrammatical.body as Body).errors?.[0]?.parameters?.query?.[0] === '-twin'
+        && tooSmall.status === 400 && timelineOk.status === 200;
+    })),
+
+  // ── post length ──────────────────────────────────────────────────────────────────────────────
+  done('x.errors.text_length_limit', 'errors', 'Post length limits (280 / long-post tiers) and their refusal', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const at280 = 'a'.repeat(280);
+      const accepted = await h({ m: 'POST', p: '/2/tweets', b: { text: at280 } });
+      const refused = await h({ m: 'POST', p: '/2/tweets', b: { text: 'a'.repeat(281) } });
+      // THE REFUSAL REFUSED. A 400 that still wrote is exactly the bug a status-only verify
+      // cannot see, so the author's own timeline is read back afterwards.
+      const stored = ((await h({ m: 'GET', p: `/2/users/${ORG}/tweets` })).body as Body).data as Body[];
+      // The long-post tier is an ACCOUNT, not a different endpoint.
+      await h({ m: 'POST', p: '/_twin/accounts', b: { id: '3000', username: 'premium', name: 'Premium', post_character_limit: 25000 }, headers: {} });
+      await h({ m: 'POST', p: '/_twin/tokens', b: { token: 'premium-token', account_id: '3000', scopes: FULL_SCOPES }, headers: {} });
+      const premium = { authorization: 'Bearer premium-token' };
+      const long = await h({ m: 'POST', p: '/2/tweets', b: { text: 'b'.repeat(1200) }, headers: premium });
+      const beyondPremium = await h({ m: 'POST', p: '/2/tweets', b: { text: 'b'.repeat(25001) }, headers: premium });
+      const impossibleTier = await h({ m: 'POST', p: '/_twin/accounts', b: { username: 'nope', post_character_limit: 26000 }, headers: {} });
+      return accepted.status === 201 && refused.status === 400
+        && (refused.body as Body).errors?.[0]?.parameters?.text?.[0] === '281'
+        && stored.length === 1 && stored[0]!.text === at280
+        && long.status === 201 && beyondPremium.status === 400 && impossibleTier.status === 400;
+    })),
+
+  // ── retraction (DELETE /2/tweets/:id) ────────────────────────────────────────────────────────
+  done('x.tweets.delete', 'tweets', 'Retract a post (DELETE /2/tweets/:id)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member oops' } });
+      const id = (created.body as Body).data.id;
+      const before = (await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions` })).body as Body;
+      const deleted = await h({ m: 'DELETE', p: `/2/tweets/${id}` });
+      const after = (await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions` })).body as Body;
+      // Deleted AND gone from the timeline — a delete that answers 200 while the post keeps
+      // showing is exactly the bug a status-only verify would miss.
+      return before.meta.result_count === 1
+        && deleted.status === 200 && (deleted.body as Body).data.deleted === true
+        && after.meta.result_count === 0;
+    })),
+  done('x.tweets.delete_unknown_refuses', 'tweets', 'Deleting a post that does not exist is resource-not-found', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'DELETE', p: '/2/tweets/404404404404404404' });
+      return r.status === 404 && (r.body as Body).errors?.[0]?.resource_type === 'tweet';
+    })),
+  done('x.tweets.delete_twice_refuses', 'tweets', 'A second delete of the same post refuses (not a silent success)', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'once' } });
+      const id = (created.body as Body).data.id;
+      const first = await h({ m: 'DELETE', p: `/2/tweets/${id}` });
+      const second = await h({ m: 'DELETE', p: `/2/tweets/${id}` });
+      return first.status === 200 && second.status === 404;
+    })),
+  done('x.tweets.delete_only_your_own', 'tweets', "A public voice cannot retract someone ELSE's post", 'api', 'core', () =>
+    withWorld(async (h) => {
+      const foreignId = await seedMention(h);
+      const r = await h({ m: 'DELETE', p: `/2/tweets/${foreignId}` });
+      const still = (await h({ m: 'GET', p: `/2/users/${ORG}/mentions` })).body as Body;
+      return r.status === 403 && (r.body as Body).title === 'Forbidden' && still.meta.result_count === 1;
+    })),
+
+  // ── the mentions timeline (GET /2/users/:id/mentions) ────────────────────────────────────────
+  done('x.mentions.list', 'mentions', 'Read the mentions timeline (GET /2/users/:id/mentions)', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const mentionId = await seedMention(h);
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?${THREAD_FIELDS}` });
+      const body = r.body as Body;
+      return r.status === 200
+        && body.data.length === 1 && body.data[0].id === mentionId
+        && body.data[0].author_id === MEMBER
+        && body.meta.result_count === 1 && body.meta.newest_id === mentionId && body.meta.oldest_id === mentionId;
+    })),
+  done('x.mentions.empty_omits_data', 'mentions', "An EMPTY timeline omits `data` entirely, as the vendor does", 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions` });
+      const body = r.body as Body;
+      // A client reading `response.data.length` breaks against the real vendor if the twin
+      // invents `[]` here. Faithfulness is the absence.
+      return r.status === 200 && body.data === undefined && body.meta.result_count === 0 && Object.keys(body).join(',') === 'meta';
+    })),
+  done('x.mentions.newest_first', 'mentions', 'The timeline is ordered newest-first by post id', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const first = await seedMention(h, 'first @orgvoice');
+      const second = await seedMention(h, 'second @orgvoice');
+      const third = await seedMention(h, 'third @orgvoice');
+      const rows = ((await h({ m: 'GET', p: `/2/users/${ORG}/mentions` })).body as Body).data as Body[];
+      return rows.map((r) => r.id).join(',') === [third, second, first].join(',');
+    })),
+  done('x.mentions.excludes_own_posts', 'mentions', "The org's own posts are not its own mentions", 'api', 'core', () =>
+    withWorld(async (h) => {
+      await h({ m: 'POST', p: '/2/tweets', b: { text: 'talking about @orgvoice, i.e. me' } });
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions` });
+      return (r.body as Body).meta.result_count === 0;
+    })),
+  done('x.mentions.handle_boundaries', 'mentions', '@handle matching respects word boundaries and is case-insensitive', 'api', 'common', () =>
+    withWorld(async (h) => {
+      await h({ m: 'POST', p: '/_twin/posts', b: { author_id: MEMBER, text: 'ping @OrgVoice!' }, headers: {} });
+      await h({ m: 'POST', p: '/_twin/posts', b: { author_id: MEMBER, text: 'not @orgvoicebot though' }, headers: {} });
+      await h({ m: 'POST', p: '/_twin/posts', b: { author_id: MEMBER, text: 'nor foo@orgvoice' }, headers: {} });
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions` });
+      return (r.body as Body).meta.result_count === 1;
+    })),
+  done('x.mentions.max_results_bounds', 'mentions', 'max_results is bounded 5..100, out of range is the invalid-request problem', 'api', 'common', () =>
+    withWorld(async (h) => {
+      await seedMention(h);
+      const low = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=1` });
+      const high = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=500` });
+      const okRange = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5` });
+      return low.status === 400 && high.status === 400 && okRange.status === 200
+        && (low.body as Body).errors?.[0]?.parameters?.max_results?.[0] === '1';
+    })),
+  done('x.mentions.max_results_pages', 'mentions', 'max_results actually bounds the page', 'api', 'common', () =>
+    withWorld(async (h) => {
+      for (let i = 0; i < 7; i += 1) await seedMention(h, `n${i} @orgvoice`);
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions?max_results=5` });
+      const body = r.body as Body;
+      return body.data.length === 5 && body.meta.result_count === 5;
+    })),
+  done('x.mentions.unknown_user_refuses', 'mentions', 'A mentions read for an account that does not exist is resource-not-found', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'GET', p: '/2/users/999999/mentions' });
+      return r.status === 404 && (r.body as Body).errors?.[0]?.resource_type === 'user';
+    })),
+  done('x.mentions.excludes_retracted', 'mentions', 'A retracted post leaves the mentions timeline', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member hi' } });
+      await h({ m: 'DELETE', p: `/2/tweets/${(created.body as Body).data.id}` });
+      const r = await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions` });
+      return (r.body as Body).meta.result_count === 0;
+    })),
+
+  // ── auth: the bearer xidentity's flow mints, and the scopes it carries ────────────────────────
+  done('x.auth.bearer_required', 'auth', 'An absent bearer is the about:blank 401 problem', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions`, headers: {} });
+      const body = r.body as Body;
+      return r.status === 401 && body.type === 'about:blank' && body.title === 'Unauthorized' && body.status === 401;
+    })),
+  done('x.auth.unknown_bearer_refuses', 'auth', 'An unregistered bearer is refused, not silently accepted', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'sneaky' }, headers: { authorization: 'Bearer not-a-real-token' } });
+      return r.status === 401;
+    })),
+  done('x.auth.malformed_authorization_refuses', 'auth', 'A non-Bearer Authorization header is refused', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const basic = await h({ m: 'POST', p: '/2/tweets', b: { text: 'x' }, headers: { authorization: `Basic ${TOKEN}` } });
+      const bare = await h({ m: 'POST', p: '/2/tweets', b: { text: 'x' }, headers: { authorization: TOKEN } });
+      return basic.status === 401 && bare.status === 401;
+    })),
+  done('x.auth.write_scope_gate', 'auth', 'Posting without tweet.write is the 403 problem', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'unauthorized voice' } });
+      const body = r.body as Body;
+      return r.status === 403 && body.title === 'Forbidden' && String(body.detail).includes('tweet.write');
+    }, { scopes: ['tweet.read', 'users.read'] })),
+  done('x.auth.read_scope_gate', 'auth', 'Reading mentions without tweet.read is the 403 problem', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions` });
+      return r.status === 403 && String((r.body as Body).detail).includes('tweet.read');
+    }, { scopes: ['tweet.write', 'users.read'] })),
+  done('x.auth.reply_scope_equals_post_scope', 'auth', 'A reply requires the same vendor scope an original post does', 'api', 'core', () =>
+    withWorld(async (h) => {
+      // The VENDOR does not distinguish them — one operation, one scope. The estate's ladder
+      // lives in the census/grant layer, not in a scope X does not publish. Recording that here
+      // keeps a future reader from inventing a `tweet.reply` scope X has never had.
+      const mention = await h({ m: 'POST', p: '/_twin/posts', b: { author_id: MEMBER, text: '@orgvoice hi' }, headers: {} });
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'hello', reply: { in_reply_to_tweet_id: (mention.body as Body).data.id } } });
+      return r.status === 403 && String((r.body as Body).detail).includes('tweet.write');
+    }, { scopes: ['tweet.read', 'users.read'] })),
+
+  // ── error surface ────────────────────────────────────────────────────────────────────────────
+  done('x.errors.unmodelled_route_404s', 'errors', 'An unmodelled /2 route fails like the vendor, never a fake success', 'api', 'core', () =>
+    withWorld(async (h) => {
+      // Recent search IS modelled now, so the unmodelled-route claim moved to routes that are
+      // genuinely still absent: post COUNTS and the engagement verbs.
+      const counts = await h({ m: 'GET', p: '/2/tweets/counts/recent?query=volter' });
+      const like = await h({ m: 'POST', p: `/2/users/${ORG}/likes`, b: { tweet_id: '1' } });
+      const hidden = await h({ m: 'PUT', p: '/2/tweets/1900000000000000001/hidden', b: { hidden: true } });
+      return counts.status === 404 && (counts.body as Body).title === 'Not Found Error'
+        && like.status === 404 && hidden.status === 404;
+    })),
+  done('x.errors.problem_content_type', 'errors', 'Problem envelopes carry application/problem+json', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'GET', p: `/2/users/${ORG}/mentions`, headers: {} });
+      return r.headers?.['content-type'] === 'application/problem+json';
+    })),
+  done('x.errors.malformed_body_refuses', 'errors', 'An unparseable request body is the invalid-request problem', 'api', 'common', () =>
+    withWorld(async (h, root) => {
+      const r = await handleXTwinRequest({ method: 'POST', path: '/2/tweets', body: '{not json', headers: AUTH, root });
+      return r.status === 400 && (r.body as Body).type === 'https://api.x.com/2/problems/invalid-request';
+    })),
+  done('x.errors.rate_limit_429_code_88', 'errors', 'The armed 15-minute-window refusal is 429 with legacy code 88', 'api', 'common', () =>
+    withWorld(async (h) => {
+      await h({ m: 'POST', p: '/_twin/rate_limit', b: { armed: true, limit: 200 }, headers: {} });
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'blocked' } });
+      const body = r.body as Body;
+      return r.status === 429
+        && body.errors?.[0]?.code === 88 && body.errors?.[0]?.message === 'Rate limit exceeded'
+        && r.headers?.['x-rate-limit-remaining'] === '0'
+        && typeof r.headers?.['x-rate-limit-reset'] === 'string';
+    })),
+  done('x.errors.read_only_refuses_writes', 'errors', 'A read-only twin refuses every write with 405', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const post = await h({ m: 'POST', p: '/2/tweets', b: { text: 'nope' }, readOnly: true });
+      const del = await h({ m: 'DELETE', p: '/2/tweets/1', readOnly: true });
+      const read = await h({ m: 'GET', p: `/2/users/${ORG}/mentions`, readOnly: true });
+      return post.status === 405 && del.status === 405 && read.status === 200;
+    })),
+
+  // ── connector (pull/push over an INJECTED client) ────────────────────────────────────────────
+  done('x.connector.pull_mentions', 'connector', 'Pull the mentions timeline from the real vendor into observed state', 'connector', 'core', () =>
+    withWorld(async (h, root) => {
+      // A PATH-AWARE fake, because the pull now reads two timelines: what was said to the org
+      // and what the org itself said. A fake that answered every path identically would fold the
+      // same rows twice and prove nothing about either read.
+      const execute: XExecute = async (_m, path) => (path.includes('/mentions')
+        ? { data: [{ id: '1900000000000000001', text: 'hey @orgvoice', author_id: MEMBER, created_at: '2026-08-24T00:00:00.000Z', conversation_id: '1900000000000000001' }], meta: { result_count: 1 } }
+        : { meta: { result_count: 0 } });
+      const result = await syncXFromReal(execute, { userId: ORG, root });
+      const rows = ((await h({ m: 'GET', p: `/2/users/${ORG}/mentions?${THREAD_FIELDS}` })).body as Body).data as Body[];
+      return result.observed === 1 && result.deltasAppended > 0 && rows.length === 1
+        && rows[0]!.id === '1900000000000000001' && rows[0]!.author_id === MEMBER;
+    })),
+  done('x.connector.pull_idempotent', 'connector', 'A second identical pull appends zero deltas', 'connector', 'core', () =>
+    withWorld(async (_h, root) => {
+      const execute: XExecute = async (_m, path) => (path.includes('/mentions')
+        ? { data: [{ id: '1900000000000000002', text: 'hey @orgvoice', author_id: MEMBER, created_at: '2026-08-24T00:00:00.000Z' }], meta: { result_count: 1 } }
+        : { meta: { result_count: 0 } });
+      await syncXFromReal(execute, { userId: ORG, root });
+      const second = await syncXFromReal(execute, { userId: ORG, root });
+      return second.observed === 1 && second.deltasAppended === 0;
+    })),
+  done('x.connector.empty_timeline_is_not_a_refusal', 'connector', "An empty timeline (meta only, no data) pulls as zero rows, not an error", 'connector', 'core', () =>
+    withWorld(async (_h, root) => {
+      const execute: XExecute = async () => ({ meta: { result_count: 0 } });
+      const result = await syncXFromReal(execute, { userId: ORG, root });
+      return result.observed === 0 && result.deltasAppended === 0;
+    })),
+  // COUNTING THROWS IS NOT A TEST. The first version of this verify counted exceptions, and a
+  // DEAD connector seam throws too — so it was green against the saboteur that exists to catch
+  // exactly this (scripts/mutation-test.ts, `connectorDead`). A refusal has to be identified by
+  // the REFUSAL: the vendor's own reply has to reach the caller inside the error, real observed
+  // state has to survive it untouched, and a legitimate pull in the same run has to still fold.
+  // All three break under a dead seam; none of them breaks because "an exception happened".
+  done('x.connector.refused_pull_throws', 'connector', 'A refusal-shaped reply THROWS naming the refusal, and folds NOTHING over observed state', 'connector', 'core', () =>
+    withWorld(async (h, root) => {
+      // A LEGITIMATE pull FIRST, so there is real observed state for a refusal to damage — and so
+      // this verify can never be satisfied by everything throwing.
+      const good: XExecute = async (_m, path) => (path.includes('/mentions')
+        ? { data: [{ id: '1900000000000000001', text: 'hey @orgvoice', author_id: MEMBER, created_at: '2026-08-24T00:00:00.000Z', conversation_id: '1900000000000000001' }], meta: { result_count: 1 } }
+        : { meta: { result_count: 0 } });
+      const folded = await syncXFromReal(good, { userId: ORG, root });
+      if (folded.observed !== 1 || folded.deltasAppended === 0) return false;
+
+      // Each case asserts a fragment of the VENDOR'S OWN REPLY in the message the caller sees.
+      // The saboteur's message ('connector seam is dead') carries none of them.
+      const cases: Array<{ execute: XExecute; names: string }> = [
+        // a 200 carrying a problem envelope: neither `data` nor `meta`
+        { execute: async () => ({ title: 'Unauthorized', type: 'about:blank', status: 401 }), names: 'about:blank' },
+        // a row whose id is not an X-shaped snowflake — a foreign id entering the projection
+        { execute: async () => ({ data: [{ id: 'not-a-snowflake', text: 'x' }], meta: { result_count: 1 } }), names: 'not-a-snowflake' },
+        // `data` present but not an array
+        { execute: async () => ({ data: { id: '1900000000000000009' }, meta: { result_count: 1 } }), names: '1900000000000000009' },
+      ];
+      for (const { execute, names } of cases) {
+        let message: string | undefined;
+        try {
+          await syncXFromReal(execute, { userId: ORG, root });
+        } catch (error) {
+          message = error instanceof Error ? error.message : String(error);
+        }
+        if (message === undefined) return false;
+        if (!/^x mentions pull (refused or malformed|returned a row)/.test(message)) return false;
+        if (!message.includes(names)) return false;
+      }
+
+      // And the refusals folded NOTHING: the legitimately observed post is still the only row,
+      // unchanged. A refusal that quietly emptied the timeline would pass every assertion above.
+      const rows = ((await h({ m: 'GET', p: `/2/users/${ORG}/mentions` })).body as Body).data as Body[];
+      return rows.length === 1 && rows[0]!.id === '1900000000000000001' && rows[0]!.text === 'hey @orgvoice';
+    })),
+  done('x.connector.push_request_shape', 'connector', 'The push request shape carries the reply discriminator unchanged', 'connector', 'core', () => {
+    const post = xRequestForAction({ operation: 'x.post.create', subject: { type: 'post', id: '9000000000000000001' }, fields: { text: 'hello' } });
+    const reply = xRequestForAction({ operation: 'x.post.reply', subject: { type: 'post', id: '9000000000000000002' }, fields: { text: 'hi', referenced_tweets: [{ type: 'replied_to', id: '1900000000000000001' }] } });
+    const quote = xRequestForAction({ operation: 'x.post.quote', subject: { type: 'post', id: '9000000000000000003' }, fields: { text: 'worth reading', referenced_tweets: [{ type: 'quoted', id: '1900000000000000002' }] } });
+    const del = xRequestForAction({ operation: 'x.post.delete', subject: { type: 'post', id: '1900000000000000009' }, fields: {} });
+    return post?.method === 'POST' && post.path === '/2/tweets' && JSON.parse(post.body!).reply === undefined
+      && reply?.method === 'POST' && reply.path === '/2/tweets' && JSON.parse(reply.body!).reply.in_reply_to_tweet_id === '1900000000000000001'
+      && quote?.method === 'POST' && quote.path === '/2/tweets'
+      && JSON.parse(quote.body!).quote_tweet_id === '1900000000000000002' && JSON.parse(quote.body!).reply === undefined
+      && del?.method === 'DELETE' && del.path === '/2/tweets/1900000000000000009';
+  }),
+  done('x.connector.push_confirms_the_real_id', 'connector', "A pushed post is confirmed under the id the VENDOR minted, retiring the local one", 'connector', 'core', () =>
+    withWorld(async (h, root) => {
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: '@member pushed' } });
+      const localId = (created.body as Body).data.id;
+      const { pendingActions } = await import('@volter/world-core');
+      const action = pendingActions('x', root).find((a) => a.operation === 'x.post.create');
+      if (!action) return false;
+      const execute: XExecute = async () => ({ data: { id: '1911111111111111111', text: '@member pushed' } });
+      const result = await pushXAction(execute, action as never, { root });
+      const rows = ((await h({ m: 'GET', p: `/2/users/${MEMBER}/mentions` })).body as Body).data as Body[];
+      // The public id is live and the locally minted one is retired IN THE SAME confirmation, so
+      // no window exists in which a later delete could address a post that does not exist.
+      return result.realId === '1911111111111111111'
+        && rows.length === 1 && rows[0]!.id === '1911111111111111111'
+        && !rows.some((r) => r.id === localId);
+    })),
+  done('x.connector.pull_own_timeline', 'connector', "Pull the org's OWN posted timeline from the real vendor", 'connector', 'core', () =>
+    withWorld(async (h, root) => {
+      // A post the org made SOMEWHERE ELSE — on x.com, or in a run this twin never saw. Nothing
+      // local knows it exists, so a pull that reads only mentions comes back still believing the
+      // org never spoke.
+      const execute: XExecute = async (_m, path) => (path.includes('/mentions')
+        ? { meta: { result_count: 0 } }
+        : { data: [{ id: '1900000000000000077', text: 'said this from a phone', author_id: ORG, created_at: '2026-08-24T00:00:00.000Z', conversation_id: '1900000000000000077' }], meta: { result_count: 1 } });
+      const before = (await h({ m: 'GET', p: `/2/users/${ORG}/tweets` })).body as Body;
+      const result = await syncXFromReal(execute, { userId: ORG, root });
+      const rows = ((await h({ m: 'GET', p: `/2/users/${ORG}/tweets?tweet.fields=author_id,created_at` })).body as Body).data as Body[];
+      // …and the read really is the OWN-timeline leg: opting out of it observes nothing at all.
+      const optedOut = await syncXFromReal(execute, { userId: ORG, root, includeOwnTimeline: false });
+      return before.meta.result_count === 0
+        && result.observed === 1 && result.deltasAppended > 0
+        && rows.length === 1 && rows[0]!.id === '1900000000000000077'
+        && rows[0]!.text === 'said this from a phone' && rows[0]!.author_id === ORG
+        && rows[0]!.created_at === '2026-08-24T00:00:00.000Z'
+        && optedOut.observed === 0;
+    })),
+  done('x.connector.pull_pagination', 'connector', 'Follow next_token across a multi-page mentions pull', 'connector', 'core', () =>
+    withWorld(async (h, root) => {
+      const asked: string[] = [];
+      const page = (ids: string[], author: string, next?: string) => ({
+        data: ids.map((id) => ({ id, text: author === MEMBER ? `hey @orgvoice ${id}` : `the org said ${id}`, author_id: author, created_at: '2026-08-24T00:00:00.000Z' })),
+        meta: { result_count: ids.length, ...(next === undefined ? {} : { next_token: next }) },
+      });
+      // BOTH legs page. The own-timeline leg answering a single empty page left half the claim
+      // ("both pull legs follow next_token") resting on the mentions leg alone — and the two legs
+      // carry DIFFERENT authors, so the mentions read below can only see the mentions leg's rows.
+      const execute: XExecute = async (_m, path) => {
+        asked.push(path);
+        if (path.includes('/mentions')) {
+          return path.includes('pagination_token=PAGE2') ? page(['1900000000000000012'], MEMBER) : page(['1900000000000000011'], MEMBER, 'PAGE2');
+        }
+        return path.includes('pagination_token=OWN2') ? page(['1900000000000000022'], ORG) : page(['1900000000000000021'], ORG, 'OWN2');
+      };
+      const result = await syncXFromReal(execute, { userId: ORG, root });
+      const rows = ((await h({ m: 'GET', p: `/2/users/${ORG}/mentions` })).body as Body).data as Body[];
+      const own = ((await h({ m: 'GET', p: `/2/users/${ORG}/tweets` })).body as Body).data as Body[];
+      // A vendor that keeps handing back the SAME token is refused by name rather than paged
+      // forever — and, just as important, rather than truncated in silence.
+      let looped: string | undefined;
+      try {
+        await syncXFromReal(async () => page(['1900000000000000013'], MEMBER, 'SAME'), { userId: ORG, root });
+      } catch (error) {
+        looped = error instanceof Error ? error.message : String(error);
+      }
+      // …and a vendor that keeps handing back DISTINCT tokens forever hits the page cap, which
+      // the repeated-token guard would otherwise always reach first.
+      let capped: string | undefined;
+      try {
+        let issued = 0;
+        await syncXFromReal(async () => page([`19000000000000001${(issued += 1) % 10}`], MEMBER, `T${issued}`), { userId: ORG, root });
+      } catch (error) {
+        capped = error instanceof Error ? error.message : String(error);
+      }
+      return result.observed === 4
+        && own.map((r) => r.id).sort().join(',') === '1900000000000000021,1900000000000000022'
+        && asked.filter((path) => path.includes('/mentions')).length === 2
+        && asked.filter((path) => path.includes('/tweets') && !path.includes('/mentions')).length === 2
+        && asked.some((path) => path.includes('pagination_token=PAGE2'))
+        && asked.some((path) => path.includes('pagination_token=OWN2'))
+        && rows.map((r) => r.id).sort().join(',') === '1900000000000000011,1900000000000000012'
+        && looped !== undefined && /repeated next_token \(SAME\)/.test(looped)
+        && capped !== undefined && /exceeded 32 pages/.test(capped);
+    })),
+  done('x.connector.live_refuses_unmapped_paths', 'connector', 'The live executor refuses any X path this pack has not modelled', 'connector', 'core', async () => {
+    let calls = 0;
+    const execute = (await import('./x-connector.ts')).liveXExecute('token', { fetchImpl: (async () => { calls += 1; return new Response('{}'); }) as unknown as typeof fetch, budgetOptions: { path: join(mkdtempSync(join(tmpdir(), 'x-budget-')), 'ledger.json') } });
+    // Same rule as x.connector.refused_pull_throws: the refusal is identified by NAMING the path
+    // it refused, not by an exception having occurred.
+    for (const path of ['/2/users/1/likes', '/1.1/statuses/update.json', '/2/dm_conversations']) {
+      let message: string | undefined;
+      try {
+        await execute('POST', path, { body: '{}' });
+      } catch (error) {
+        message = error instanceof Error ? error.message : String(error);
+      }
+      if (message === undefined) return false;
+      if (!message.startsWith('liveXExecute: refusing to call an unmapped X path:')) return false;
+      if (!message.endsWith(path)) return false;
+    }
+    // And it refused BEFORE any I/O: the injected fake was never called.
+    return calls === 0;
+  }),
+  done('x.connector.live_refuses_injected_authorization', 'connector', 'The live executor refuses a caller-supplied Authorization header', 'connector', 'core', async () => {
+    let calls = 0;
+    const execute = (await import('./x-connector.ts')).liveXExecute('token', { fetchImpl: (async () => { calls += 1; return new Response('{}'); }) as unknown as typeof fetch, budgetOptions: { path: join(mkdtempSync(join(tmpdir(), 'x-budget-')), 'ledger.json') } });
+    // /2/tweets IS a mapped path, so an exception here can only come from the header refusal —
+    // and it must say so, by name, before any I/O.
+    let message: string | undefined;
+    try {
+      await execute('POST', '/2/tweets', { headers: { Authorization: 'Bearer someone-elses' }, body: '{}' });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+    return message === 'liveXExecute: refusing an injected Authorization header; the guarded credential is fixed at construction' && calls === 0;
+  }),
+
+  // ── the rate budget (the fail-closed backstop on the live path) ──────────────────────────────
+  // A TRAP THIS PACK WALKED INTO ONCE, WRITTEN DOWN SO THE NEXT READER DOES NOT. `write` and
+  // `other` are BOTH 5 — deliberately, so unmodelled surface is priced at the write. That makes
+  // `xCallWeight('POST', '/2/tweets') === X_CALL_WEIGHTS.write` a TAUTOLOGY: delete the
+  // `^POST /2/tweets$` rule and the default answers 5 and the assertion still passes. The
+  // mutation gate cannot see it either, because it sabotages module seams, not a data table.
+  // So every assertion below is one the DEFAULT would answer differently.
+  done('x.budget.prices_a_write_above_a_read', 'rate_limit', 'A post costs more budget than reading the mentions timeline', 'connector', 'core', () => {
+    const read = xCallWeight('GET', '/2/users/1000/mentions?tweet.fields=author_id');
+    const unruled = xCallWeight('GET', '/2/tweets/1900000000000000001');
+    // The READ rule is the only weight distinguishable from the fallback, so it carries the
+    // behavioural half: a path the rules do not name falls to `other`, and the mentions read
+    // must NOT, or the rule never fired.
+    // (No `read === unruled` guard: the compiler narrows both to their literal weights after the
+    // checks above and rejects the comparison as provably false — which is the property itself.)
+    if (read !== X_CALL_WEIGHTS.read || unruled !== X_CALL_WEIGHTS.other) return false;
+    // The WRITE rules cannot be told from the fallback by their weight, so they are asserted
+    // where they actually live: the committed declaration the kernel registry is armed from.
+    const matchers = X_RATE_BUDGET.rules?.map((rule) => `${rule.match} ${rule.weight}`) ?? [];
+    return matchers.includes(`^POST /2/tweets$ ${X_CALL_WEIGHTS.write}`)
+      && matchers.includes(`^DELETE /2/tweets/ ${X_CALL_WEIGHTS.write}`)
+      && matchers.includes(`^GET /2/users/[^/]+/mentions$ ${X_CALL_WEIGHTS.read}`)
+      && X_CALL_WEIGHTS.write > X_CALL_WEIGHTS.read;
+  }),
+  done('x.budget.case_insensitive_method', 'rate_limit', "A lower-cased method and a trailing slash are priced as the call really is", 'connector', 'core', () => {
+    // Priced on the READ path for the reason above: an un-normalized key misses the rule and
+    // falls to `other` (5), which is distinguishable from `read` (1). On a write path it would
+    // fall to 5 and look identical to a hit, proving nothing.
+    return xCallWeight('get', '/2/users/1000/mentions') === X_CALL_WEIGHTS.read
+      && xCallWeight('GET', '/2/users/1000/mentions/') === X_CALL_WEIGHTS.read
+      && xCallWeight('get', '/2/users/1000/mentions/?tweet.fields=author_id') === X_CALL_WEIGHTS.read;
+  }),
+  done('x.budget.enforced_fail_closed', 'rate_limit', 'The declared ceiling stops the live path BEFORE the request goes out', 'connector', 'core', async () => {
+    let calls = 0;
+    const ledger = join(mkdtempSync(join(tmpdir(), 'x-budget-')), 'ledger.json');
+    const execute = (await import('./x-connector.ts')).liveXExecute('token', {
+      fetchImpl: (async () => { calls += 1; return new Response(JSON.stringify({ data: { id: '1900000000000000001', text: 'x' } }), { headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch,
+      budgetOptions: { path: ledger },
+    });
+    // Ten writes at weight 5 exhaust the 50-unit window exactly; the eleventh must never reach
+    // fetch. Nothing here waits on a wall clock: the guard refuses synchronously.
+    let refusedAt = 0;
+    for (let i = 0; i < 20; i += 1) {
+      try { await execute('POST', '/2/tweets', { body: '{"text":"x"}' }); } catch (error) { if (error instanceof XBudgetError) { refusedAt = i; break; } throw error; }
+    }
+    return refusedAt > 0 && calls === refusedAt && calls * X_CALL_WEIGHTS.write <= X_BUDGET_CEILING;
+  }),
+  done('x.budget.declared_ceiling_is_the_pack_descriptor', 'rate_limit', "The pack descriptor arms the SAME declaration the connector imports", 'connector', 'common', async () => {
+    const { pack } = await import('./index.ts');
+    const { X_RATE_BUDGET } = await import('./x-budget.ts');
+    return pack.rateBudget === X_RATE_BUDGET && new XBudget({ path: join(mkdtempSync(join(tmpdir(), 'x-budget-')), 'l.json') }).path.endsWith('l.json');
+  }),
+
+  // ── the twin control plane (how a WORLD seeds a rehearsal) ───────────────────────────────────
+  done('x.twin_control.seed_account_and_token', 'twin_control', 'A world seeds an account and the bearer xidentity would have minted', 'api', 'core', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/2/tweets', b: { text: 'seeded and speaking' } });
+      return r.status === 201;
+    })),
+  done('x.twin_control.rejects_unshaped_username', 'twin_control', 'A seeded account must carry an X-shaped username', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const tooLong = await h({ m: 'POST', p: '/_twin/accounts', b: { username: 'averyveryverylongusername' }, headers: {} });
+      const punctuation = await h({ m: 'POST', p: '/_twin/accounts', b: { username: 'has.a.dot' }, headers: {} });
+      return tooLong.status === 400 && punctuation.status === 400;
+    })),
+  done('x.twin_control.token_must_name_a_real_account', 'twin_control', 'A seeded token cannot name an account that does not exist', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const r = await h({ m: 'POST', p: '/_twin/tokens', b: { token: 'orphan', account_id: '777777' }, headers: {} });
+      return r.status === 400;
+    })),
+  done('x.twin_control.is_not_vendor_surface', 'twin_control', 'The control plane is refused in read-only mode and is not under /2', 'api', 'common', () =>
+    withWorld(async (h) => {
+      const readOnly = await h({ m: 'POST', p: '/_twin/accounts', b: { username: 'nope' }, headers: {}, readOnly: true });
+      const unknown = await h({ m: 'POST', p: '/_twin/nothing', b: {}, headers: {} });
+      return readOnly.status === 405 && unknown.status === 404;
+    })),
+
+  // ── the enumerated surface this pack does NOT model yet ──────────────────────────────────────
+  todo('x.tweets.poll', 'tweets', 'Post with a poll (POST /2/tweets with poll.options/duration_minutes)', 'api', 'common'),
+  done('x.tweets.media_attachment', 'tweets', 'Post with media (POST /2/tweets with media.media_ids), read back through attachments.media_keys and includes.media', 'api', 'common', () =>
+    withWorld(async (h) => {
+      await mediaToken(h);
+      const up = (await h({ m: 'POST', p: '/2/media/upload', b: { media: b64(tinyPng()), media_category: 'tweet_image' }, headers: MEDIA_AUTH })).body as Body;
+      const mediaId = up.data?.id as string;
+      // another account's media id is X's own refusal, and nothing lands
+      await h({ m: 'POST', p: '/_twin/tokens', b: { token: 'member-token', account_id: MEMBER, scopes: FULL_SCOPES }, headers: {} });
+      const foreign = await h({ m: 'POST', p: '/2/tweets', b: { text: 'not mine', media: { media_ids: [mediaId] } }, headers: { authorization: 'Bearer member-token' } });
+      if (foreign.status !== 400 || (foreign.body as Body).errors?.[0]?.message !== 'Your media IDs are invalid.') return false;
+      const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'with a picture', media: { media_ids: [mediaId] } } });
+      const postId = (created.body as Body).data?.id as string;
+      if (created.status !== 201) return false;
+      const read = (await h({ m: 'GET', p: `/2/tweets/${postId}?expansions=attachments.media_keys&media.fields=url,type,width,height` })).body as Body;
+      const media = read.includes?.media?.[0];
+      // the default projection carries no attachments; the expansion brings them and the sidecar
+      const plain = (await h({ m: 'GET', p: `/2/tweets/${postId}` })).body as Body;
+      return read.data?.attachments?.media_keys?.[0] === up.data.media_key && media?.media_key === up.data.media_key
+        && media.type === 'photo' && media.width === 64 && media.height === 48 && /^https:\/\/pbs\.twimg\.com\/media\/[0-9a-f]{64}\.png$/.test(media.url)
+        && plain.data?.attachments === undefined && plain.includes === undefined;
+    })),
+  todo('x.tweets.reply_settings', 'tweets', 'reply_settings (mentionedUsers / following / subscribers)', 'api', 'common'),
+  todo('x.tweets.exclude_reply_user_ids', 'tweets', 'reply.exclude_reply_user_ids on a reply', 'api', 'niche'),
+  todo('x.tweets.super_followers_only', 'tweets', 'for_super_followers_only posts', 'api', 'niche'),
+  todo('x.tweets.geo_place', 'tweets', 'geo.place_id tagging on a post', 'api', 'niche'),
+  todo('x.tweets.hide_reply', 'tweets', 'Hide/unhide a reply (PUT /2/tweets/:id/hidden)', 'api', 'common'),
+  todo('x.tweets.quote_tweets_list', 'tweets', 'Quote posts of a post (GET /2/tweets/:id/quote_tweets)', 'api', 'common'),
+  todo('x.tweets.liking_users', 'tweets', 'Users who liked a post (GET /2/tweets/:id/liking_users)', 'api', 'common'),
+  todo('x.tweets.retweeted_by', 'tweets', 'Users who reposted a post (GET /2/tweets/:id/retweeted_by)', 'api', 'common'),
+  todo('x.fields.entities', 'fields', 'entities (mentions, urls, hashtags) on a returned post', 'api', 'common'),
+  todo('x.fields.public_metrics', 'fields', 'public_metrics (reply/repost/like/quote counts) on a post', 'api', 'common'),
+  todo('x.timelines.exclude', 'timelines', 'exclude=retweets,replies on a timeline read', 'api', 'common'),
+  todo('x.search.seven_day_window', 'search', "Recent search's seven-day corpus window, and the refusal for a start_time older than it", 'api', 'common'),
+  todo('x.search.all', 'search', 'Full-archive search (GET /2/tweets/search/all)', 'api', 'niche'),
+  todo('x.search.counts', 'search', 'Post counts (GET /2/tweets/counts/recent and /all)', 'api', 'niche'),
+  todo('x.search.query_grammar', 'search', "X's search query grammar (operators, groups, negation)", 'api', 'niche'),
+  todo('x.engagement.like', 'engagement', 'Like / unlike a post (POST and DELETE /2/users/:id/likes)', 'api', 'common'),
+  todo('x.engagement.retweet', 'engagement', 'Repost / un-repost (POST and DELETE /2/users/:id/retweets)', 'api', 'common'),
+  todo('x.engagement.bookmark', 'engagement', 'Bookmarks (GET, POST and DELETE /2/users/:id/bookmarks)', 'api', 'niche'),
+  todo('x.engagement.liked_tweets', 'engagement', 'Posts a user liked (GET /2/users/:id/liked_tweets)', 'api', 'niche'),
+  todo('x.streaming.rules', 'streaming', 'Filtered-stream rule management (GET and POST /2/tweets/search/stream/rules)', 'api', 'niche'),
+  todo('x.rate_limit.published_figures', 'rate_limit', "Pin the budget to X's published per-endpoint posting limits (the ceiling here is conservative, not transcribed)", 'connector', 'core'),
+  todo('x.rate_limit.response_headers', 'rate_limit', 'x-rate-limit-limit/remaining/reset headers on every /2 response, counted per window', 'api', 'common'),
+  todo('x.rate_limit.window_enforcement', 'rate_limit', 'Enforce the real 15-minute window in the twin rather than only on an armed refusal', 'api', 'common'),
+  todo('x.errors.scope_wording', 'errors', "Pin X's own wording for the insufficient-scope 403 (the twin states the refusal plainly)", 'api', 'common'),
+  todo('x.errors.resource_not_found_wording', 'errors', "Pin X's own detail/title wording for the resource-not-found problem", 'api', 'common'),
+  todo('x.errors.text_length_weighting', 'errors', "X's WEIGHTED character count (CJK and emoji cost two, a URL counts 23) rather than the twin's plain code-point count", 'api', 'common'),
+  todo('x.errors.duplicate_content', 'errors', "X's duplicate-content refusal for posting the same text twice", 'api', 'common'),
+  todo('x.auth.app_only_bearer', 'auth', 'App-only (OAuth 2.0 client-credentials) bearer for the public read endpoints', 'api', 'common'),
+  todo('x.auth.oauth1_user_context', 'auth', "OAuth 1.0a user-context signing, X's alternate auth for these endpoints", 'api', 'niche'),
+  todo('x.auth.access_tier_gate', 'auth', "Access-tier gating (Free/Basic/Pro), which decides whether an endpoint exists for a token at all", 'api', 'common'),
+  // ══ MIRROR (dimension: 'ui' — every one is DATA-COUPLED: seed through the handler, read the
+  // SAME route the screen reads, render the mirror's OWN component over it) ══════════════════════
+  done('x.mirror.profile_header', 'mirror', "The profile header renders the account the user-lookup route serves", 'ui', 'core', () =>
+    withWorld(async (h) => {
+      await h({ m: 'POST', p: '/_twin/accounts', b: { id: '3000', username: 'profiled', name: 'Profiled Org', description: 'we build things', location: 'Brooklyn', verified: true }, headers: {} });
+      const user = ((await h({ m: 'GET', p: `/2/users/by/username/profiled?${PROFILE_READ_QUERY}` })).body as Body).data as XRow | undefined;
+      if (!user) return false;
+      const markup = renderToStaticMarkup(createElement(ProfileHeader, { user }));
+      return markup.includes('Profiled Org') && markup.includes('@profiled') && markup.includes('we build things')
+        && markup.includes('Brooklyn') && markup.includes(joinedLabel(user.created_at)) && markup.includes('class="badge"');
+    })),
+  done('x.mirror.timeline', 'mirror', "The timeline renders the account's own posts newest first, each with name, @handle, time and text", 'ui', 'core', () =>
+    withWorld(async (h) => {
+      const older = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'the older post' } })).body as Body).data.id as string;
+      const newer = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'the newer post, see @member' } })).body as Body).data.id as string;
+      const page = (await h({ m: 'GET', p: `/2/users/${ORG}/tweets?${POST_READ_QUERY}` })).body as Body;
+      const rows = (page.data ?? []) as XRow[];
+      const users = usersById(page.includes);
+      const tweets = tweetsById(page.includes);
+      const markup = rows.map((post) => renderToStaticMarkup(createElement(PostRow, { post, users, tweets, nowMs: Date.parse(String(post.created_at)) + 120_000 }))).join('');
+      const iNewer = markup.indexOf(`data-post-id="${newer}"`);
+      const iOlder = markup.indexOf(`data-post-id="${older}"`);
+      return rows.length === 2 && iNewer !== -1 && iOlder !== -1 && iNewer < iOlder
+        && markup.includes('Org Voice') && markup.includes('@orgvoice') && markup.includes('>2m<')
+        // the mention is an entity link, as x.com draws it
+        && markup.includes('href="#/member"');
+    })),
+  done('x.mirror.quote_card', 'mirror', 'A quote post renders the quoted post inside its card, from the `includes` the read expanded', 'ui', 'common', () =>
+    withWorld(async (h) => {
+      const mentionId = await seedMention(h, 'a member said something @orgvoice');
+      const quote = ((await h({ m: 'POST', p: '/2/tweets', b: { text: 'worth reading', quote_tweet_id: mentionId } })).body as Body).data.id as string;
+      const read = (await h({ m: 'GET', p: `/2/tweets/${quote}?${POST_READ_QUERY}` })).body as Body;
+      if (!read.data) return false;
+      const markup = renderToStaticMarkup(createElement(PostRow, { post: read.data as XRow, users: usersById(read.includes), tweets: tweetsById(read.includes), nowMs: Date.now() }));
+      return markup.includes('class="quote"') && markup.includes('a member said something') && markup.includes('@member') && markup.includes('worth reading');
+    })),
+  done('x.mirror.serves_the_vendor_api_on_its_own_origin', 'mirror', 'The mirror origin serves the REAL X handler — one serving code path, not a second app', 'ui', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'x-cap-mirror-'));
+    const server = await createXMirrorServer({ root, port: 0 });
+    try {
+      const json = { 'content-type': 'application/json' };
+      await fetch(`${server.url}/_twin/accounts`, { method: 'POST', headers: json, body: JSON.stringify({ id: ORG, username: 'orgvoice', name: 'Org Voice' }) });
+      await fetch(`${server.url}/_twin/tokens`, { method: 'POST', headers: json, body: JSON.stringify({ token: TOKEN, account_id: ORG, scopes: FULL_SCOPES }) });
+      // 1. a WRITE to X's real path, through the MIRROR origin
+      const posted = await fetch(`${server.url}/2/tweets`, { method: 'POST', headers: { ...json, ...AUTH }, body: JSON.stringify({ text: 'written through the mirror origin' }) });
+      if (posted.status !== 201) return false;
+      const id = ((await posted.json()) as Body).data.id;
+      // 2. it landed in the SAME projection the API serves — read back through the handler directly
+      const direct = await handleXTwinRequest({ method: 'GET', path: `/2/tweets/${id}`, headers: AUTH, root });
+      // 3. the mirror origin enforces the twin's OWN auth: no bearer is X's 401, not a mirror bypass
+      const anon = await fetch(`${server.url}/2/users/by/username/orgvoice`);
+      const shell = await (await fetch(`${server.url}/`)).text();
+      return direct.status === 200 && (direct.body as Body).data?.text === 'written through the mirror origin'
+        && anon.status === 401 && shell.includes('<div id="root">');
+    } finally {
+      server.stop();
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  todo('x.mirror.notifications_all', 'mirror', "Notifications beyond Mentions (likes, reposts, follows) — the twin models no engagement events to list", 'ui', 'common'),
+  todo('x.mirror.profile_counts', 'mirror', "The Following / Followers counts under the profile header (needs user public_metrics)", 'ui', 'common'),
+
+  // ── Pull-surface coverage audit gaps — filed as manifest todos so
+  // the demand-ordered build list is drawn from manifest todos. See pull-audit.json.
+  todo('x.connector.pull_conversation', 'connector', 'Connector: pull the replies under a conversation from the real vendor', 'connector', 'common'),
+];
+
+export async function xCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('x', X_CAPABILITIES);
+}