@volter/twin-x 0.1.0

package/src/x-twin.ts

@@ -0,0 +1,1545 @@
+// The X (Twitter) API v2 POSTING surface, twinned: an org's public voice can post, quote, reply
+// to a mention, retract a post, look a post back up, read its own and its mentions' timelines,
+// and search the corpus — offline, against local state.
+//
+// SCOPE. The demo this pack exists for (DEMO-AUTONOMOUS-ORG §9b) names one job: "the org's
+// public voice posts through the X pack's boundary", and §5 graduates mention-REPLIES before
+// ORIGINAL POSTS. That is the write half. The READ half exists because a public voice that
+// cannot read back what it said has no way to check itself: post lookup, the user timeline, the
+// home timeline and recent search all fold the same projection the writes append to. A post can
+// carry IMAGES or a VIDEO: `POST /2/media/upload` (one-shot, or initialize/append/finalize, with a
+// video's processing walked through STATUS) stages the bytes (x-media.ts — not a kernel action),
+// and the post that attaches the media id records each one by key, id and digest. Spaces, lists,
+// DMs, GIFs, likes/reposts/bookmarks and streaming are real
+// X surface this pack does not model; they stay `unmapped` in x-spec-census.json rather than
+// absent, which is what a denominator sensor is for.
+//
+// THE ONE THING THIS FILE EXISTS TO GET RIGHT. An original post, a QUOTE and a reply are the
+// SAME HTTP operation at X — `POST /2/tweets`, differing only by a field in the body (grounded
+// from the pinned `twitter-api-v2@1.29.1` client's own source: `tweet()` posts `{text}` to
+// `tweets`, `reply()` posts `{text, reply:{in_reply_to_tweet_id}}` and `quote()` posts
+// `{text, quote_tweet_id}` to that same `tweets`; dist/cjs/v2/client.v2.write.js:89, :180, :187 —
+// see test-fixtures/x-openapi-operations.SOURCE.md). This handler therefore dispatches on those
+// body fields, and the census (`x-spec-census.json`, requestKey "method+path+body-field") names
+// the reply/original split as two capability ids so a grant can cover one and refuse the other.
+// The discriminator is the PACK'S OWN, not a new vocabulary invented for the census: it is the
+// field this file branches on to decide what to write. (A QUOTE is an ORIGINAL post for that
+// split — the org speaking under its own name, not answering someone — so it lands on the
+// census's `x.tweets.create` side rather than adding a third entry to a two-sided partition.)
+//
+// FIELD PROJECTION IS NOT DECORATION. X returns `id`, `text` and `edit_history_tweet_ids` and
+// NOTHING ELSE unless the caller asks: `author_id`, `created_at`, `conversation_id`,
+// `referenced_tweets` and the rest arrive only under `tweet.fields`, and related objects only
+// under `expansions`. A twin that returns everything always is not more generous, it is wrong —
+// an integrator whose client forgets `tweet.fields` passes here and breaks in production. So the
+// default projection is the vendor's three fields, and `projectPost` is the ONE place a stored
+// post becomes a response body.
+//
+// AUTH. OAuth 2.0 is xidentity's and stays there. This pack CONSUMES the user access token that
+// flow mints: a bearer, opaque, scope-carrying. `/_twin/tokens` registers one locally, which is
+// what a world does instead of running the authorize leg for every test.
+//
+// DETERMINISM. Every served response is a pure function of (request, stored state). Nothing on
+// the read path reads a clock: `created_at` is what the WRITE stored, and the `next_token` a page
+// hands back is derived from the id of the last row on that page, never from entropy or time.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import {
+  forbiddenProblem,
+  invalidRequestProblem,
+  lookupResult,
+  notFoundProblem,
+  rateLimitExceeded,
+  readOnlyRefusal,
+  resourceNotFoundError,
+  resourceNotFoundProblem,
+  unauthorizedProblem,
+  type XResponse,
+} from './x-problems.ts';
+import { missingScopes, parseScopeList, REQUIRED_SCOPES } from './x-scopes.ts';
+import {
+  clearSegments,
+  listMediaIds,
+  MAX_IMAGE_BYTES,
+  MAX_TWEET_VIDEO_MS,
+  MAX_VIDEO_BYTES,
+  MEDIA_EXPIRES_AFTER_SECS,
+  mediaExtension,
+  putSegment,
+  putXBlob,
+  readMediaRecord,
+  readSegments,
+  sniffImage,
+  sniffVideo,
+  writeMediaRecord,
+  type XMediaRecord,
+} from './x-media.ts';
+
+const SERVICE = 'x';
+
+/** X's post ids are snowflakes. A minted id must never collide with one PULLED from the real
+ *  vendor, and it must never be derived from a ROW COUNT (a count-mint silently clobbers a
+ *  pulled id sitting in a gap above the count — ADDING_A_TWIN.md §5). So: scan the id SET
+ *  already in state and step past its maximum, starting above today's real snowflake space. */
+const ID_FLOOR = 9_000_000_000_000_000_000n;
+
+/** X's default post length. An account on X Premium may exceed it, so the twin carries that
+ *  entitlement as a seeded per-account number rather than pretending every account is the same.
+ *  The COUNT here is code points; X's WEIGHTED count (CJK and emoji cost two) is a documented
+ *  refinement this build does not model and files as `x.errors.text_length_weighting`. */
+const DEFAULT_POST_CHARACTER_LIMIT = 280;
+const MAX_POST_CHARACTER_LIMIT = 25_000;
+
+export type XRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  readOnly?: boolean;
+  occurredAt?: string;
+  root?: string;
+  /** A multipart body, parsed by the server (x-server.ts): its text fields and the `media` part's
+   *  bytes. The JSON adapter reads bodies as text, which would corrupt binary; so a multipart
+   *  upload arrives here instead of in `body`. */
+  form?: { fields: Record<string, string>; media?: Uint8Array };
+  /** Where this twin is reached (`twinPublicBase`: origin plus any World mount path). A media `url`
+   *  is minted from it; a direct handler call with none mints X's own pbs.twimg.com form. */
+  publicBase?: string;
+};
+
+type Resource = Record<string, any>;
+
+function ok(body: unknown, headers: Record<string, string> = {}): XResponse {
+  return { status: 200, body, headers: { 'content-type': 'application/json', ...headers } };
+}
+
+function parseJsonBody(body?: string): { object: Record<string, any> } | { malformed: true } {
+  if (body === undefined || body.trim() === '') return { object: {} };
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return { malformed: true };
+    return { object: parsed as Record<string, any> };
+  } catch {
+    return { malformed: true };
+  }
+}
+
+function resources(root?: string): Resource[] {
+  return projectResources(SERVICE, root) as unknown as Resource[];
+}
+
+function ofType(all: Resource[], type: string): Resource[] {
+  return all.filter((r) => r.type === type);
+}
+
+// X draws every object id from ONE snowflake space: an account and a post never share an id,
+// and a client that resolves `author_id` against a post id would be reading the wrong object.
+// So the high-water mark is taken across every seeded resource, not just posts — scanning one
+// type while minting for two let a seeded account collide with an earlier account AND with a
+// post, and the mentions timeline for that id then answered about the wrong subject.
+function mintSnowflakeId(all: Resource[], alsoTaken: string[] = []): string {
+  let max = ID_FLOOR;
+  for (const id of [...all.map((r) => String(r.id)), ...alsoTaken]) {
+    const asBigInt = /^\d+$/.test(id) ? BigInt(id) : 0n;
+    if (asBigInt > max) max = asBigInt;
+  }
+  return String(max + 1n);
+}
+
+const livePosts = (all: Resource[]): Resource[] => ofType(all, 'post').filter((p) => p.deleted !== true);
+const findPost = (all: Resource[], id: string): Resource | undefined => livePosts(all).find((p) => String(p.id) === id);
+const findAccount = (all: Resource[], id: string): Resource | undefined => ofType(all, 'account').find((a) => String(a.id) === id);
+
+/** Newest first, by snowflake id — X orders every timeline by id, not by a parsed timestamp. */
+function newestFirst(posts: Resource[]): Resource[] {
+  return [...posts].sort((a, b) => (BigInt(String(b.id)) > BigInt(String(a.id)) ? 1 : -1));
+}
+
+// ── auth ────────────────────────────────────────────────────────────────────────────────────
+// A registered token resolves to the account it acts for and the scopes it carries. An
+// unregistered, malformed or absent bearer is the vendor's about:blank 401 — never a local
+// exception, and never a pass.
+
+type Authorized = { accountId: string; scopes: string[]; token: string };
+
+function bearerFrom(headers: Record<string, string> | undefined): string | undefined {
+  if (!headers) return undefined;
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== 'authorization') continue;
+    const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return match?.[1]?.trim();
+  }
+  return undefined;
+}
+
+function authorize(all: Resource[], headers: Record<string, string> | undefined): Authorized | XResponse {
+  const token = bearerFrom(headers);
+  if (!token) return unauthorizedProblem();
+  const row = ofType(all, 'token').find((t) => String(t.id) === token);
+  if (!row) return unauthorizedProblem();
+  return { accountId: String(row.account_id), scopes: Array.isArray(row.scopes) ? row.scopes.map(String) : [], token };
+}
+
+const isResponse = (value: Authorized | XResponse): value is XResponse => 'status' in value;
+
+function scopeRefusal(auth: Authorized, operation: keyof typeof REQUIRED_SCOPES): XResponse | undefined {
+  const missing = missingScopes(auth.scopes, REQUIRED_SCOPES[operation]);
+  if (missing.length === 0) return undefined;
+  return forbiddenProblem(`This request requires the ${missing.join(', ')} scope(s), which this token does not hold.`);
+}
+
+// ── tweet.fields / expansions: the projection X actually serves ──────────────────────────────
+//
+// Two closed sets, written as LITERALS. X documents exactly which values `tweet.fields` and
+// `expansions` accept, so an allowlist is a real oracle rather than the twin agreeing with
+// itself: a value outside the documented set is the vendor's own invalid-request refusal, and a
+// value INSIDE it that this twin holds no state for is refused BY NAME rather than silently
+// omitted. Silence would be the worse failure — a caller that asked for `public_metrics` and got
+// a post without it cannot tell "this twin does not model metrics" from "this post has none".
+// (ADDING_A_TWIN.md §6: only an option the endpoint actually DECLARES may be an unmodelled
+// option. Each unmodelled value below has its own manifest todo: x.fields.entities,
+// x.fields.public_metrics, x.fields.user_fields, x.tweets.reply_settings, x.tweets.geo_place, …)
+
+const TWEET_FIELDS_DOCUMENTED = new Set([
+  'attachments', 'author_id', 'card_uri', 'context_annotations', 'conversation_id', 'created_at',
+  'edit_controls', 'edit_history_tweet_ids', 'entities', 'geo', 'id', 'in_reply_to_user_id', 'lang',
+  'non_public_metrics', 'note_tweet', 'organic_metrics', 'possibly_sensitive', 'promoted_metrics',
+  'public_metrics', 'referenced_tweets', 'reply_settings', 'scopes', 'source', 'text', 'withheld',
+]);
+
+/** The subset the twin holds state for. `id`, `text` and `edit_history_tweet_ids` are in X's
+ *  DEFAULT projection and are served whether or not they are asked for, exactly as at the vendor. */
+const TWEET_FIELDS_MODELLED = new Set([
+  'attachments', 'author_id', 'conversation_id', 'created_at', 'edit_history_tweet_ids', 'id', 'in_reply_to_user_id',
+  'referenced_tweets', 'text',
+]);
+
+const EXPANSIONS_DOCUMENTED = new Set([
+  'attachments.media_keys', 'attachments.poll_ids', 'author_id', 'edit_history_tweet_ids',
+  'entities.mentions.username', 'geo.place_id', 'in_reply_to_user_id', 'referenced_tweets.id',
+  'referenced_tweets.id.author_id',
+]);
+
+const EXPANSIONS_MODELLED = new Set(['attachments.media_keys', 'author_id', 'in_reply_to_user_id', 'referenced_tweets.id', 'referenced_tweets.id.author_id']);
+
+/** An expansion RETURNS its source field on the post as well as the expanded object in
+ *  `includes` — asking to expand `author_id` and getting back a post with no `author_id` would
+ *  leave the sidecar unjoinable. */
+const EXPANSION_IMPLIES_FIELD: Record<string, string> = {
+  'attachments.media_keys': 'attachments',
+  author_id: 'author_id',
+  in_reply_to_user_id: 'in_reply_to_user_id',
+  'referenced_tweets.id': 'referenced_tweets',
+  'referenced_tweets.id.author_id': 'referenced_tweets',
+};
+
+type ReadShape = { fields: Set<string>; expansions: Set<string>; userFields: Set<string>; mediaFields: Set<string>; publicBase: string };
+
+// `media.fields`: the documented set is docs.x.com's Media object (fundamentals/data-dictionary);
+// `media_key` and `type` are its DEFAULT projection. The modelled subset is what an uploaded image
+// or video has state for — a photo's `url`, `width`, `height`; a video's `duration_ms`,
+// `preview_image_url` and `variants` (whose answer for a photo is X's own: absent). `alt_text`
+// (the metadata endpoint) and every metrics field have no state here and are refused by name.
+const MEDIA_FIELDS_DOCUMENTED = new Set([
+  'alt_text', 'duration_ms', 'height', 'media_key', 'non_public_metrics', 'organic_metrics', 'preview_image_url',
+  'promoted_metrics', 'public_metrics', 'type', 'url', 'variants', 'width',
+]);
+const MEDIA_FIELDS_MODELLED = new Set(['duration_ms', 'height', 'media_key', 'preview_image_url', 'type', 'url', 'variants', 'width']);
+
+/** The hosts X serves media from — what a direct handler call (no served base) mints: images and
+ *  video thumbnails on pbs.twimg.com, video files on video.twimg.com. Served over HTTP, every one
+ *  of them is this twin's own base instead (x-server.ts serves the same paths). */
+const PBS_BASE = 'https://pbs.twimg.com';
+const VIDEO_BASE = 'https://video.twimg.com';
+
+// `user.fields`: the documented set is the pinned client's own `TTweetv2UserField = keyof UserV2`
+// (twitter-api-v2@1.29.1 dist/cjs/types/v2/user.v2.types.d.ts), the same grounding as the routes.
+// `id`, `name` and `username` are X's DEFAULT user object and are served whether asked or not.
+const USER_FIELDS_DOCUMENTED = new Set([
+  'affiliation', 'confirmed_email', 'connection_status', 'created_at', 'description', 'entities', 'id',
+  'is_identity_verified', 'location', 'most_recent_tweet_id', 'name', 'parody', 'pinned_tweet_id',
+  'profile_banner_url', 'profile_image_url', 'protected', 'public_metrics', 'receives_your_dm',
+  'subscription', 'subscription_type', 'url', 'username', 'verified', 'verified_followers_count',
+  'verified_type', 'withheld',
+]);
+
+/** The subset the twin holds state for: what `/_twin/accounts` seeds, plus `most_recent_tweet_id`,
+ *  which is a pure function of the account's live posts. `public_metrics` is NOT here: two of its
+ *  counts (listed, like) have no state behind them, and a zero the twin cannot know is a fabrication. */
+const USER_FIELDS_MODELLED = new Set([
+  'created_at', 'description', 'id', 'location', 'most_recent_tweet_id', 'name', 'protected', 'url', 'username', 'verified',
+]);
+
+/** Read `user.fields` off the query string, refusing the way `tweet.fields` refuses. */
+function parseUserFields(url: URL): Set<string> | XResponse {
+  const userFields = new Set<string>();
+  for (const value of csv(url.searchParams.get('user.fields'))) {
+    if (!USER_FIELDS_DOCUMENTED.has(value)) {
+      return invalidRequestProblem({ 'user.fields': [value] }, `The \`user.fields\` query parameter value [${value}] is not one of the documented User fields`);
+    }
+    if (!USER_FIELDS_MODELLED.has(value)) return unmodelledOption('user.fields', value);
+    userFields.add(value);
+  }
+  return userFields;
+}
+
+const isFieldSet = (value: Set<string> | XResponse): value is Set<string> => value instanceof Set;
+
+function csv(raw: string | null): string[] {
+  if (raw === null) return [];
+  return raw.split(',').map((v) => v.trim()).filter((v) => v !== '');
+}
+
+function unmodelledOption(parameter: string, value: string): XResponse {
+  return invalidRequestProblem(
+    { [parameter]: [value] },
+    `The \`${parameter}\` value [${value}] is real X surface this twin does not model. It is refused rather than silently dropped, so a caller never mistakes an unmodelled field for an absent value.`,
+  );
+}
+
+/** Read `tweet.fields` + `expansions` off the query string, or refuse the way X refuses. */
+function parseReadShape(url: URL, publicBase: string): ReadShape | XResponse {
+  const fields = new Set<string>();
+  for (const value of csv(url.searchParams.get('tweet.fields'))) {
+    if (!TWEET_FIELDS_DOCUMENTED.has(value)) {
+      return invalidRequestProblem({ 'tweet.fields': [value] }, `The \`tweet.fields\` query parameter value [${value}] is not one of the documented Post fields`);
+    }
+    if (!TWEET_FIELDS_MODELLED.has(value)) return unmodelledOption('tweet.fields', value);
+    fields.add(value);
+  }
+  const expansions = new Set<string>();
+  for (const value of csv(url.searchParams.get('expansions'))) {
+    if (!EXPANSIONS_DOCUMENTED.has(value)) {
+      return invalidRequestProblem({ expansions: [value] }, `The \`expansions\` query parameter value [${value}] is not one of the documented Post expansions`);
+    }
+    if (!EXPANSIONS_MODELLED.has(value)) return unmodelledOption('expansions', value);
+    expansions.add(value);
+    const implied = EXPANSION_IMPLIES_FIELD[value];
+    if (implied !== undefined) fields.add(implied);
+  }
+  // `user.fields` shapes the users in `includes`, with the same closed-set refusal as the user
+  // lookup routes: one parser, so the two can never disagree about a field.
+  const userFields = parseUserFields(url);
+  if (!isFieldSet(userFields)) return userFields;
+  const mediaFields = new Set<string>();
+  for (const value of csv(url.searchParams.get('media.fields'))) {
+    if (!MEDIA_FIELDS_DOCUMENTED.has(value)) {
+      return invalidRequestProblem({ 'media.fields': [value] }, `The \`media.fields\` query parameter value [${value}] is not one of the documented Media fields`);
+    }
+    if (!MEDIA_FIELDS_MODELLED.has(value)) return unmodelledOption('media.fields', value);
+    mediaFields.add(value);
+  }
+  return { fields, expansions, userFields, mediaFields, publicBase };
+}
+
+const isShape = (value: ReadShape | XResponse): value is ReadShape => !('status' in value);
+
+/** THE ONE PLACE a stored post becomes a response body. Default projection = X's three fields. */
+function projectPost(post: Resource, fields: Set<string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    id: String(post.id),
+    text: String(post.text),
+    edit_history_tweet_ids: [String(post.id)],
+  };
+  if (fields.has('author_id') && post.author_id !== undefined) out.author_id = String(post.author_id);
+  if (fields.has('created_at') && post.created_at !== undefined) out.created_at = String(post.created_at);
+  if (fields.has('conversation_id') && post.conversation_id !== undefined) out.conversation_id = String(post.conversation_id);
+  if (fields.has('in_reply_to_user_id') && post.in_reply_to_user_id !== undefined) out.in_reply_to_user_id = String(post.in_reply_to_user_id);
+  if (fields.has('referenced_tweets') && Array.isArray(post.referenced_tweets) && post.referenced_tweets.length > 0) out.referenced_tweets = post.referenced_tweets;
+  // X serves `attachments` only on a post that has some — a text-only post carries no empty object.
+  const mediaKeys = attachedMedia(post).map((m) => m.media_key);
+  if (fields.has('attachments') && mediaKeys.length > 0) out.attachments = { media_keys: mediaKeys };
+  return out;
+}
+
+/** One image or video a post carries, as its entry recorded it at create time (see createPost). */
+type AttachedMedia = {
+  media_key: string; media_id: string; type: 'photo' | 'video'; media_type: string; media_category: string; sha256: string; size: number;
+  width?: number; height?: number; duration_ms?: number;
+};
+
+function attachedMedia(post: Resource): AttachedMedia[] {
+  return Array.isArray(post.media) ? (post.media as AttachedMedia[]).filter((m) => m && typeof m.media_key === 'string') : [];
+}
+
+/** THE ONE PLACE an attached image becomes an `includes.media` object. Default = X's two fields. */
+function projectMedia(media: AttachedMedia, mediaFields: Set<string>, publicBase: string): Record<string, unknown> {
+  const out: Record<string, unknown> = { media_key: media.media_key, type: media.type };
+  // `url` is a photo's; a video or GIF answers with `preview_image_url` instead. The path is
+  // pbs.twimg.com's `/media/<name>.<ext>`, served by this twin (x-server.ts) from the blob seam.
+  if (mediaFields.has('url') && media.type === 'photo') out.url = `${publicBase}/media/${media.sha256}.${mediaExtension(media.media_type)}`;
+  if (mediaFields.has('width') && typeof media.width === 'number') out.width = media.width;
+  if (mediaFields.has('height') && typeof media.height === 'number') out.height = media.height;
+  if (media.type === 'video') {
+    // video.twimg.com's `/ext_tw_video/<id>/pu/vid/avc1/<w>x<h>/<name>.mp4` and pbs's
+    // `/ext_tw_video_thumb/<id>/pu/img/<name>.<ext>` shapes, served by this twin.
+    const videoBase = publicBase === PBS_BASE ? VIDEO_BASE : publicBase;
+    const file = `${videoBase}/ext_tw_video/${media.media_id}/pu/vid/avc1/${media.width ?? 0}x${media.height ?? 0}/${media.sha256}.mp4`;
+    if (mediaFields.has('duration_ms') && typeof media.duration_ms === 'number') out.duration_ms = media.duration_ms;
+    if (mediaFields.has('preview_image_url')) out.preview_image_url = `${publicBase}/ext_tw_video_thumb/${media.media_id}/pu/img/${media.sha256}.svg`;
+    if (mediaFields.has('variants')) {
+      // ONE variant: the file as uploaded. X transcodes to an HLS playlist and several MP4 bit
+      // rates; the twin transcodes nothing, so it lists the one rendition it holds, with the bit
+      // rate that file actually has (bytes over duration), never an invented ladder.
+      const bitRate = typeof media.duration_ms === 'number' && media.duration_ms > 0 ? Math.round((media.size * 8 * 1000) / media.duration_ms) : undefined;
+      out.variants = [{ ...(bitRate !== undefined ? { bit_rate: bitRate } : {}), content_type: 'video/mp4', url: file }];
+    }
+  }
+  return out;
+}
+
+/** THE ONE PLACE a stored account becomes a user object. Default projection = X's three fields;
+ *  every other field only when asked for, and only when the twin holds state for it. */
+function projectUser(account: Resource, userFields: Set<string>, all: Resource[]): Record<string, unknown> {
+  const out: Record<string, unknown> = { id: String(account.id), name: String(account.name ?? account.username), username: String(account.username) };
+  if (userFields.has('created_at') && typeof account.created_at === 'string') out.created_at = account.created_at;
+  if (userFields.has('description')) out.description = typeof account.description === 'string' ? account.description : '';
+  if (userFields.has('location') && typeof account.location === 'string' && account.location !== '') out.location = account.location;
+  if (userFields.has('url')) out.url = typeof account.url === 'string' ? account.url : '';
+  if (userFields.has('protected')) out.protected = account.protected === true;
+  if (userFields.has('verified')) out.verified = account.verified === true;
+  if (userFields.has('most_recent_tweet_id')) {
+    const newest = newestFirst(livePosts(all).filter((p) => String(p.author_id) === String(account.id)))[0];
+    if (newest !== undefined) out.most_recent_tweet_id = String(newest.id);
+  }
+  return out;
+}
+
+/**
+ * The `includes` sidecar for a page of posts. Ordering is FIXED (users by id ascending, tweets
+ * by id descending — the same order the page itself uses) so two identical requests over
+ * identical state serve identical bytes.
+ */
+function buildIncludes(rows: Resource[], all: Resource[], shape: ReadShape): Record<string, unknown> {
+  const includes: Record<string, unknown> = {};
+  const userIds = new Set<string>();
+  const tweetIds = new Set<string>();
+  for (const post of rows) {
+    if (shape.expansions.has('author_id') && post.author_id !== undefined) userIds.add(String(post.author_id));
+    if (shape.expansions.has('in_reply_to_user_id') && post.in_reply_to_user_id !== undefined) userIds.add(String(post.in_reply_to_user_id));
+    if (!Array.isArray(post.referenced_tweets)) continue;
+    for (const reference of post.referenced_tweets) {
+      const referencedId = String((reference as Record<string, unknown>)?.id ?? '');
+      if (referencedId === '') continue;
+      if (shape.expansions.has('referenced_tweets.id')) tweetIds.add(referencedId);
+      if (shape.expansions.has('referenced_tweets.id.author_id')) {
+        const referenced = findPost(all, referencedId);
+        if (referenced?.author_id !== undefined) userIds.add(String(referenced.author_id));
+      }
+    }
+  }
+  const tweets = [...tweetIds]
+    .map((id) => findPost(all, id))
+    .filter((p): p is Resource => p !== undefined)
+    .sort((a, b) => (BigInt(String(b.id)) > BigInt(String(a.id)) ? 1 : -1))
+    .map((p) => projectPost(p, shape.fields));
+  const users = [...userIds]
+    .map((id) => findAccount(all, id))
+    .filter((a): a is Resource => a !== undefined)
+    .sort((a, b) => (BigInt(String(a.id)) > BigInt(String(b.id)) ? 1 : -1))
+    .map((a) => projectUser(a, shape.userFields, all));
+  if (tweets.length > 0) includes.tweets = tweets;
+  if (users.length > 0) includes.users = users;
+  // Media in the order the page first mentions it, each key once.
+  if (shape.expansions.has('attachments.media_keys')) {
+    const seen = new Set<string>();
+    const media: Array<Record<string, unknown>> = [];
+    for (const post of rows) {
+      for (const m of attachedMedia(post)) {
+        if (seen.has(m.media_key)) continue;
+        seen.add(m.media_key);
+        media.push(projectMedia(m, shape.mediaFields, shape.publicBase));
+      }
+    }
+    if (media.length > 0) includes.media = media;
+  }
+  return includes;
+}
+
+// ── timeline windowing and paging ────────────────────────────────────────────────────────────
+
+type Window = { sinceId?: string; untilId?: string; startTime?: string; endTime?: string };
+
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
+/**
+ * since_id / until_id / start_time / end_time, with X's own PRECEDENCE: an id bound and a time
+ * bound on the same side of the window cannot both apply, and the vendor says the id wins
+ * ("If included with the same request as a since_id parameter, only since_id will be used", and
+ * the mirror statement for until_id / end_time). Modelling that is the difference between a
+ * window and a guess — a twin that intersected all four would quietly return fewer rows than X.
+ */
+function parseWindow(url: URL): Window | XResponse {
+  const window: Window = {};
+  for (const name of ['since_id', 'until_id'] as const) {
+    const raw = url.searchParams.get(name);
+    if (raw === null) continue;
+    if (!/^\d+$/.test(raw)) return invalidRequestProblem({ [name]: [raw] }, `The \`${name}\` query parameter value [${raw}] is not a valid Post id`);
+    if (name === 'since_id') window.sinceId = raw;
+    else window.untilId = raw;
+  }
+  for (const name of ['start_time', 'end_time'] as const) {
+    const raw = url.searchParams.get(name);
+    if (raw === null) continue;
+    if (!ISO_8601.test(raw) || Number.isNaN(Date.parse(raw))) {
+      return invalidRequestProblem({ [name]: [raw] }, `The \`${name}\` query parameter value [${raw}] is not a valid ISO 8601 date (YYYY-MM-DDTHH:mm:ssZ)`);
+    }
+    if (name === 'start_time') window.startTime = raw;
+    else window.endTime = raw;
+  }
+  if (window.sinceId !== undefined) delete window.startTime;
+  if (window.untilId !== undefined) delete window.endTime;
+  return window;
+}
+
+const isWindow = (value: Window | XResponse): value is Window => !('status' in value);
+
+function applyWindow(posts: Resource[], window: Window): Resource[] {
+  return posts.filter((post) => {
+    const id = BigInt(String(post.id));
+    // X EXCLUDES the bound itself on both id bounds.
+    if (window.sinceId !== undefined && id <= BigInt(window.sinceId)) return false;
+    if (window.untilId !== undefined && id >= BigInt(window.untilId)) return false;
+    const createdAt = typeof post.created_at === 'string' ? Date.parse(post.created_at) : Number.NaN;
+    if (window.startTime !== undefined && !(createdAt >= Date.parse(window.startTime))) return false;
+    if (window.endTime !== undefined && !(createdAt < Date.parse(window.endTime))) return false;
+    return true;
+  });
+}
+
+/**
+ * A pagination token that is a PURE FUNCTION OF STORED STATE: the id of the last row served on
+ * the page it came from, opaque on the wire the way X's is, carrying no clock and no entropy.
+ * The same page over the same state always hands back the same token.
+ */
+function encodeCursor(lastId: string): string {
+  return Buffer.from(`x:${lastId}`, 'utf8').toString('base64url');
+}
+
+function parseCursor(url: URL): { before?: string } | XResponse {
+  const raw = url.searchParams.get('pagination_token');
+  if (raw === null || raw === '') return {};
+  let decoded = '';
+  try {
+    decoded = Buffer.from(raw, 'base64url').toString('utf8');
+  } catch {
+    decoded = '';
+  }
+  const match = /^x:(\d+)$/.exec(decoded);
+  if (!match) return invalidRequestProblem({ pagination_token: [raw] }, `The \`pagination_token\` query parameter value [${raw}] is not a valid pagination token`);
+  return { before: match[1]! };
+}
+
+const isCursor = (value: { before?: string } | XResponse): value is { before?: string } => !('status' in value);
+
+/**
+ * Page size. The timeline endpoints bound it 5..100; recent SEARCH bounds it 10..100. Both
+ * default to 10. Out of range is the invalid-request envelope, never a silent clamp.
+ */
+function parsePageSize(url: URL, min: number, max: number): number | XResponse {
+  const raw = url.searchParams.get('max_results');
+  if (raw === null) return 10;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    return invalidRequestProblem({ max_results: [raw] }, 'The `max_results` query parameter value [' + raw + '] is not between ' + min + ' and ' + max);
+  }
+  return parsed;
+}
+
+const isSize = (value: number | XResponse): value is number => typeof value === 'number';
+
+/**
+ * Turn a matched post set into the vendor's timeline envelope: the page, its `includes` sidecar,
+ * and the `meta` X actually serves. X OMITS `data` entirely on an empty page and answers with
+ * `meta` alone — a client that reads `response.data.length` breaks against the real vendor if the
+ * twin invents `[]`, so faithfulness here is the ABSENCE.
+ */
+function timelinePage(matched: Resource[], all: Resource[], shape: ReadShape, size: number, cursor: { before?: string }): XResponse {
+  const ordered = newestFirst(matched);
+  const afterCursor = cursor.before === undefined ? ordered : ordered.filter((p) => BigInt(String(p.id)) < BigInt(cursor.before!));
+  const page = afterCursor.slice(0, size);
+  if (page.length === 0) return ok({ meta: { result_count: 0 } });
+  const rows = page.map((p) => projectPost(p, shape.fields));
+  const includes = buildIncludes(page, all, shape);
+  const meta: Record<string, unknown> = {
+    result_count: rows.length,
+    newest_id: String(page[0]!.id),
+    oldest_id: String(page[page.length - 1]!.id),
+  };
+  // A next_token is served ONLY when a further row actually exists — an unconditional token
+  // walks a client into an empty page forever.
+  if (afterCursor.length > page.length) meta.next_token = encodeCursor(String(page[page.length - 1]!.id));
+  return ok({ data: rows, ...(Object.keys(includes).length > 0 ? { includes } : {}), meta });
+}
+
+/** Everything a timeline/search read needs off the query string, refused as one. */
+type ReadRequest = { shape: ReadShape; window: Window; size: number; cursor: { before?: string } };
+
+function parseReadRequest(url: URL, minSize: number, publicBase: string): ReadRequest | XResponse {
+  const shape = parseReadShape(url, publicBase);
+  if (!isShape(shape)) return shape;
+  const window = parseWindow(url);
+  if (!isWindow(window)) return window;
+  const size = parsePageSize(url, minSize, 100);
+  if (!isSize(size)) return size;
+  const cursor = parseCursor(url);
+  if (!isCursor(cursor)) return cursor;
+  return { shape, window, size, cursor };
+}
+
+const isReadRequest = (value: ReadRequest | XResponse): value is ReadRequest => !('status' in value);
+
+/** X's mentions timeline is "posts mentioning this account". The twin reads the mention out of
+ *  the post's own text, the way the vendor's entity extraction does, so a seeded post that says
+ *  `@handle` IS a mention and nothing has to declare it separately. */
+function mentionsHandle(text: string, username: string): boolean {
+  return new RegExp(`(^|[^A-Za-z0-9_])@${username.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^A-Za-z0-9_]|$)`, 'i').test(text);
+}
+
+// ── the search query grammar this twin models ────────────────────────────────────────────────
+//
+// X's search grammar is large (boolean operators, grouping, negation, dozens of field operators)
+// and this twin models a SUBSET: bare keywords and quoted phrases ANDed together, plus `from:`.
+// Everything else is REFUSED, loudly, on the `query` parameter — because the alternative is
+// worse than a refusal: silently ignoring `-spam` or `OR` would answer a query the twin did not
+// honour, which is a fake success wearing a 200. The unmodelled remainder is
+// `x.search.query_grammar` in the manifest, and stays a todo until it is really built.
+
+type SearchTerm = { kind: 'text'; value: string } | { kind: 'from'; username: string };
+
+function parseSearchQuery(query: string): { terms: SearchTerm[] } | { unsupported: string } {
+  const terms: SearchTerm[] = [];
+  const tokens = query.match(/"[^"]*"|\S+/g) ?? [];
+  for (const token of tokens) {
+    if (token.startsWith('"')) {
+      const phrase = token.slice(1, -1).trim();
+      if (phrase !== '') terms.push({ kind: 'text', value: phrase });
+      continue;
+    }
+    if (token === 'OR' || token.startsWith('-') || token.includes('(') || token.includes(')')) return { unsupported: token };
+    const from = /^from:([A-Za-z0-9_]{1,15})$/.exec(token);
+    if (from) {
+      terms.push({ kind: 'from', username: from[1]! });
+      continue;
+    }
+    if (token.includes(':')) return { unsupported: token };
+    terms.push({ kind: 'text', value: token });
+  }
+  return { terms };
+}
+
+/**
+ * X's keyword operator matches TOKENS, not substrings. A substring match answers `cat` with a post
+ * that says `catalog` — a confident row for a query the vendor returns nothing for, which is worse
+ * than refusing the query outright. So both the post and the term are tokenised the same way, and
+ * a phrase matches a CONTIGUOUS run of tokens. `@handle` and `#hashtag` survive tokenisation as
+ * single tokens, because at X they are single entities.
+ */
+function searchTokens(text: string): string[] {
+  return text.toLowerCase().split(/[^a-z0-9_@#]+/i).filter((t) => t !== '');
+}
+
+function containsRun(haystack: string[], needle: string[]): boolean {
+  if (needle.length === 0) return true;
+  for (let i = 0; i + needle.length <= haystack.length; i += 1) {
+    if (needle.every((tok, k) => haystack[i + k] === tok)) return true;
+  }
+  return false;
+}
+
+function matchesSearch(post: Resource, all: Resource[], terms: SearchTerm[]): boolean {
+  const tokens = searchTokens(String(post.text));
+  for (const term of terms) {
+    if (term.kind === 'text') {
+      if (!containsRun(tokens, searchTokens(term.value))) return false;
+      continue;
+    }
+    const author = findAccount(all, String(post.author_id));
+    if (!author || String(author.username).toLowerCase() !== term.username.toLowerCase()) return false;
+  }
+  return true;
+}
+
+// ── the modelled operations ─────────────────────────────────────────────────────────────────
+
+function postCharacterLimit(account: Resource | undefined): number {
+  const declared = account?.post_character_limit;
+  return typeof declared === 'number' && Number.isInteger(declared) && declared >= DEFAULT_POST_CHARACTER_LIMIT && declared <= MAX_POST_CHARACTER_LIMIT
+    ? declared
+    : DEFAULT_POST_CHARACTER_LIMIT;
+}
+
+/** POST /2/tweets' body is a CLOSED schema. The modelled fields are read below; every other field
+ *  X documents is refused by name (a silently ignored `poll` would be a post X would not have
+ *  made); anything else is not a parameter at all. */
+const POST_FIELDS_MODELLED = new Set(['text', 'reply', 'quote_tweet_id', 'media']);
+const POST_FIELDS_UNMODELLED = new Set([
+  'card_uri', 'community_id', 'direct_message_deep_link', 'edit_options', 'for_super_followers_only', 'geo', 'made_with_ai',
+  'nullcast', 'paid_partnership', 'poll', 'reply_settings', 'share_with_followers',
+]);
+const REPLY_FIELDS_UNMODELLED = new Set(['exclude_reply_user_ids', 'auto_populate_reply_metadata']);
+
+/** A post id in a request body: a STRING matching ^[0-9]{1,19}$, as the schema types it. */
+function postIdField(value: unknown, parameter: string): string | XResponse {
+  if (typeof value !== 'string' || !/^\d{1,19}$/.test(value)) {
+    return invalidRequestProblem({ [parameter]: [String(value)] }, `The \`${parameter}\` value [${String(value)}] is not a string matching ^[0-9]{1,19}$`);
+  }
+  return value;
+}
+
+async function createPost(request: XRequest, all: Resource[], auth: Authorized, payload: Record<string, any>): Promise<XResponse> {
+  for (const key of Object.keys(payload)) {
+    if (POST_FIELDS_MODELLED.has(key)) continue;
+    if (POST_FIELDS_UNMODELLED.has(key)) return unmodelledOption(key, JSON.stringify(payload[key]));
+    return invalidRequestProblem({ [key]: [JSON.stringify(payload[key])] }, `The \`${key}\` field is not a parameter of this request.`);
+  }
+  if (payload.reply !== undefined && payload.reply !== null) {
+    if (typeof payload.reply !== 'object' || Array.isArray(payload.reply)) return invalidRequestProblem({ reply: [JSON.stringify(payload.reply)] }, 'The `reply` field must be an object with `in_reply_to_tweet_id`.');
+    for (const key of Object.keys(payload.reply)) {
+      if (key === 'in_reply_to_tweet_id') continue;
+      if (REPLY_FIELDS_UNMODELLED.has(key)) return unmodelledOption(`reply.${key}`, JSON.stringify(payload.reply[key]));
+      return invalidRequestProblem({ [`reply.${key}`]: [JSON.stringify(payload.reply[key])] }, `The \`reply.${key}\` field is not a parameter of this request.`);
+    }
+  }
+  // MEDIA first: X's `text` is "required unless media is provided", so whether a post may be
+  // text-less depends on its media. Every id must name media THIS account may use, finished and
+  // unexpired; anything else is X's own refusal, "Your media IDs are invalid.", and nothing lands.
+  const attached = await resolveAttachedMedia(request, auth, payload.media);
+  if ('status' in attached) return attached;
+  const text = payload.text ?? (attached.media.length > 0 ? '' : undefined);
+  if (typeof text !== 'string' || (text.trim() === '' && attached.media.length === 0)) {
+    return invalidRequestProblem({ text: [String(text ?? '')] }, 'The `text` field is required when no other content is supplied.');
+  }
+  // THE DISCRIMINATOR. Its presence is what makes this request a reply rather than an original
+  // post, at the vendor and here. Everything downstream — which capability the census names,
+  // which conversation the post joins, whose mention was answered — follows from this one read.
+  const inReplyTo = payload.reply?.in_reply_to_tweet_id;
+  const isReply = inReplyTo !== undefined && inReplyTo !== null;
+  if (isReply) { const checked = postIdField(inReplyTo, 'reply.in_reply_to_tweet_id'); if (typeof checked !== 'string') return checked; }
+  // The QUOTE discriminator: a sibling top-level body field (client.v2.write.js:187). A quote is
+  // an ORIGINAL post that REFERENCES another, so it needs the same scope and starts its own
+  // conversation — the quoted post is cited, not answered.
+  const quoteOf = payload.quote_tweet_id;
+  const isQuote = quoteOf !== undefined && quoteOf !== null;
+  if (isQuote) { const checked = postIdField(quoteOf, 'quote_tweet_id'); if (typeof checked !== 'string') return checked; }
+  const refusal = scopeRefusal(auth, isReply ? 'tweets.reply' : 'tweets.create');
+  if (refusal) return refusal;
+
+  // LENGTH, before anything is written. A post the vendor would refuse must never land here.
+  const limit = postCharacterLimit(findAccount(all, auth.accountId));
+  const length = Array.from(text).length;
+  if (length > limit) {
+    return invalidRequestProblem(
+      { text: [String(length)] },
+      `The \`text\` field is ${length} characters, over this account's ${limit}-character limit for a Post.`,
+    );
+  }
+
+  let conversationId: string | undefined;
+  let inReplyToUserId: string | undefined;
+  const referenced: Array<{ type: string; id: string }> = [];
+  if (isReply) {
+    const parent = findPost(all, String(inReplyTo));
+    if (!parent) return resourceNotFoundProblem(String(inReplyTo), 'tweet', 'reply.in_reply_to_tweet_id');
+    conversationId = String(parent.conversation_id ?? parent.id);
+    inReplyToUserId = String(parent.author_id);
+    referenced.push({ type: 'replied_to', id: String(parent.id) });
+  }
+  if (isQuote) {
+    const quoted = findPost(all, String(quoteOf));
+    if (!quoted) return resourceNotFoundProblem(String(quoteOf), 'tweet', 'quote_tweet_id');
+    referenced.push({ type: 'quoted', id: String(quoted.id) });
+  }
+
+  // a post's id is the snowflake high-water mark + 1: timelines, since_id and pagination order by it
+  const id = mintSnowflakeId(all, await listMediaIds(request.root));
+  const createdAt = request.occurredAt ?? new Date().toISOString();
+  await applyTwinWrite(SERVICE, {
+    operation: isReply ? 'x.post.reply' : isQuote ? 'x.post.quote' : 'x.post.create',
+    subjectType: 'post',
+    subjectId: id,
+    fields: {
+      text,
+      author_id: auth.accountId,
+      created_at: createdAt,
+      conversation_id: conversationId ?? id,
+      ...(inReplyToUserId ? { in_reply_to_user_id: inReplyToUserId } : {}),
+      ...(referenced.length > 0 ? { referenced_tweets: referenced } : {}),
+      // The post's entry names each image by key, id and DIGEST: the digest is how the mirror's
+      // url and a deploy's upload find the bytes on the blob seam, with no staged record needed.
+      ...(attached.media.length > 0 ? { media: attached.media } : {}),
+      deleted: false,
+    },
+    occurredAt: createdAt,
+    actor: { kind: 'agent', id: auth.accountId },
+  }, request.root);
+
+  // X's create response is deliberately thin: id, text, edit_history_tweet_ids. Reading the post
+  // back is a separate call, exactly as at the vendor.
+  return { status: 201, body: { data: { id, text, edit_history_tweet_ids: [id] } }, headers: { 'content-type': 'application/json' } };
+}
+
+async function deletePost(request: XRequest, all: Resource[], auth: Authorized, id: string): Promise<XResponse> {
+  const refusal = scopeRefusal(auth, 'tweets.delete');
+  if (refusal) return refusal;
+  const post = findPost(all, id);
+  if (!post) return resourceNotFoundProblem(id, 'tweet', 'id');
+  // A public voice may only retract its OWN words. Deleting someone else's post is a refusal at
+  // the vendor and a refusal here.
+  if (String(post.author_id) !== auth.accountId) return forbiddenProblem('You are not permitted to delete this Post.');
+  await applyTwinWrite(SERVICE, {
+    operation: 'x.post.delete',
+    subjectType: 'post',
+    subjectId: id,
+    fields: { ...Object.fromEntries(Object.entries(post).filter(([k]) => k !== 'type' && k !== 'id' && k !== 'updatedAt')), deleted: true },
+    occurredAt: request.occurredAt ?? new Date().toISOString(),
+    actor: { kind: 'agent', id: auth.accountId },
+  }, request.root);
+  return ok({ data: { deleted: true } });
+}
+
+// ── media: upload (one-shot and chunked), processing, and attachment ─────────────────────────
+//
+// docs.x.com/x-api/media: `POST /2/media/upload` takes `media` ("base64-encoded in JSON bodies,
+// raw bytes in multipart bodies") and `media_category`; the chunked form is
+// `POST /2/media/upload/initialize` {media_type, total_bytes, media_category},
+// `POST /2/media/upload/{id}/append` {media, segment_index} and `POST /2/media/upload/{id}/finalize`,
+// with `GET /2/media/upload?command=STATUS&media_id=` for the processing state. Every one needs
+// `media.write`. The twin models STILL IMAGES (`tweet_image`, `dm_image`) and MP4 VIDEO
+// (`tweet_video`, `amplify_video`); GIF, DM video and subtitle categories are documented X surface
+// it refuses by name.
+//
+// PROCESSING. An image is usable the moment its bytes are whole. A video is not: FINALIZE answers
+// `processing_info` {state: "pending", check_after_secs}, and the client polls STATUS until the
+// state is `succeeded` (or `failed`). The twin walks the same states, one per STATUS read —
+// pending → in_progress → succeeded — so a client that polls as X asks reaches `succeeded`, and a
+// client that posts without polling is refused exactly as X refuses it. The step is kept on the
+// upload's pointer record (not kernel state: nothing about it is ever performed). Time moves it
+// too: one step per `check_after_secs` of World-clock time since FINALIZE, whichever is sooner —
+// so a client that sleeps as told and then posts, without polling, is not refused.
+
+const MEDIA_CATEGORIES_DOCUMENTED = new Set(['amplify_video', 'dm_gif', 'dm_image', 'dm_video', 'subtitles', 'tweet_gif', 'tweet_image', 'tweet_video']);
+/** The one-shot upload's own enum: every category but `amplify_video`, which only initialize takes. */
+const ONE_SHOT_CATEGORIES_DOCUMENTED = new Set([...MEDIA_CATEGORIES_DOCUMENTED].filter((c) => c !== 'amplify_video'));
+/** The body fields each upload endpoint declares; any other is refused (the schemas are closed). */
+const ONE_SHOT_FIELDS = new Set(['media', 'media_category', 'media_type', 'additional_owners', 'shared']);
+const INITIALIZE_FIELDS = new Set(['media_type', 'total_bytes', 'media_category', 'additional_owners', 'shared']);
+const APPEND_FIELDS = new Set(['media', 'segment_index']);
+/** A post's `media` object: `media_ids` is modelled; `tagged_user_ids` and the Amplify fields are
+ *  X's documented shape this twin does not model, refused by name; anything else is unknown. */
+const POST_MEDIA_FIELDS_UNMODELLED = new Set(['tagged_user_ids', 'title', 'description', 'preview_media_id', 'embeddable', 'call_to_actions']);
+const IMAGE_CATEGORIES = new Set(['tweet_image', 'dm_image']);
+const VIDEO_CATEGORIES = new Set(['tweet_video', 'amplify_video']);
+const IMAGE_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+const VIDEO_TYPES = new Set(['video/mp4']);
+const MEDIA_TYPES_DOCUMENTED = new Set([
+  'video/mp4', 'video/webm', 'video/mp2t', 'video/quicktime', 'text/srt', 'text/vtt', 'image/jpeg', 'image/gif', 'image/bmp',
+  'image/png', 'image/webp', 'image/pjpeg', 'image/tiff', 'model/gltf-binary', 'model/vnd.usdz+zip',
+]);
+
+const INVALID_MEDIA_IDS = 'Your media IDs are invalid.';
+/** How long X tells a client to wait between STATUS reads while a video processes. */
+const CHECK_AFTER_SECS = 1;
+
+const isVideoCategory = (category: string): boolean => VIDEO_CATEGORIES.has(category);
+
+function nowSeconds(request: XRequest): number {
+  return Math.floor(Date.parse(request.occurredAt ?? new Date().toISOString()) / 1000);
+}
+
+/** A field of the upload body, from the multipart form or the JSON object. */
+function uploadField(request: XRequest, payload: Record<string, any>, name: string): unknown {
+  if (request.form) return request.form.fields[name];
+  return payload[name];
+}
+
+/** The `media` bytes: the multipart part as sent, or the JSON body's base64 decoded. */
+function uploadBytes(request: XRequest, payload: Record<string, any>): Uint8Array | XResponse {
+  if (request.form) {
+    if (request.form.media && request.form.media.length > 0) return request.form.media;
+    return invalidRequestProblem({ media: [''] }, 'The `media` field is required.');
+  }
+  const raw = payload.media;
+  if (typeof raw !== 'string' || raw.trim() === '') return invalidRequestProblem({ media: [String(raw ?? '')] }, 'The `media` field is required.');
+  const clean = raw.replace(/\s+/g, '');
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(clean)) return invalidRequestProblem({ media: ['(not base64)'] }, 'The `media` field of a JSON body must be base64-encoded bytes.');
+  return new Uint8Array(Buffer.from(clean, 'base64'));
+}
+
+function parseCategory(value: unknown, documented: Set<string> = MEDIA_CATEGORIES_DOCUMENTED): string | XResponse {
+  if (typeof value !== 'string' || value === '') return invalidRequestProblem({ media_category: [String(value ?? '')] }, 'The `media_category` field is required.');
+  if (!documented.has(value)) {
+    return invalidRequestProblem({ media_category: [value] }, `The \`media_category\` value [${value}] is not one of [${[...documented].join(', ')}]`);
+  }
+  if (!IMAGE_CATEGORIES.has(value) && !VIDEO_CATEGORIES.has(value)) return unmodelledOption('media_category', value);
+  return value;
+}
+
+/** `additional_owners`: comma-separated on the one-shot, an array on initialize. */
+function parseOwners(value: unknown): string[] | XResponse {
+  if (value === undefined || value === null || value === '') return [];
+  const list = Array.isArray(value) ? value.map(String) : String(value).split(',').map((v) => v.trim()).filter((v) => v !== '');
+  for (const id of list) {
+    if (!/^\d{1,19}$/.test(id)) return invalidRequestProblem({ additional_owners: [id] }, `The \`additional_owners\` value [${id}] does not match ^[0-9]{1,19}$`);
+  }
+  return list;
+}
+
+const isOwners = (value: string[] | XResponse): value is string[] => Array.isArray(value);
+
+/** A field the endpoint's closed schema does not declare — the vendor's invalid-request refusal. */
+function unknownField(present: string[], allowed: Set<string>): XResponse | undefined {
+  const extra = present.find((name) => !allowed.has(name));
+  return extra === undefined ? undefined : invalidRequestProblem({ [extra]: [extra] }, `The \`${extra}\` field is not a parameter of this request.`);
+}
+
+function bodyFieldNames(request: XRequest, payload: Record<string, any>): string[] {
+  return request.form ? [...Object.keys(request.form.fields), ...(request.form.media ? ['media'] : [])] : Object.keys(payload);
+}
+
+/** The step a processing video has reached: counted STATUS reads, or elapsed World-clock time
+ *  since FINALIZE in `check_after_secs` steps, whichever is further along. */
+function processingStep(record: XMediaRecord, request: XRequest): number {
+  const byReads = record.processing_step ?? 0;
+  const byTime = record.finalized_at === undefined ? 0 : Math.floor((nowSeconds(request) - record.finalized_at) / CHECK_AFTER_SECS);
+  return Math.max(byReads, byTime);
+}
+
+/** A record as it stands NOW: a processing video two steps along has succeeded. */
+function settled(record: XMediaRecord, request: XRequest): XMediaRecord {
+  if (record.state !== 'processing') return record;
+  const step = processingStep(record, request);
+  return step >= 2 ? { ...record, state: 'succeeded', processing_step: step } : { ...record, processing_step: step };
+}
+
+/** X's `processing_info` — state, progress_percent and check_after_secs, nothing else (the v2
+ *  schema's three fields). A failure's reason rides the response's `errors`, not in here. */
+function processingInfo(record: XMediaRecord): Record<string, unknown> | undefined {
+  if (record.state === 'failed') return { state: 'failed', progress_percent: 0 };
+  if (!isVideoCategory(record.media_category)) return record.state === 'succeeded' ? undefined : { state: 'pending', progress_percent: 0, check_after_secs: CHECK_AFTER_SECS };
+  if (record.state === 'succeeded') return { state: 'succeeded', progress_percent: 100 };
+  if (record.state === 'processing' && (record.processing_step ?? 0) >= 1) return { state: 'in_progress', progress_percent: 50, check_after_secs: CHECK_AFTER_SECS };
+  return { state: 'pending', progress_percent: 0, check_after_secs: CHECK_AFTER_SECS };
+}
+
+/** What X answers about a media object: its id, key, remaining lifetime, and (once whole) its size,
+ *  its image or video facts and — while a video processes, and on STATUS — `processing_info`. An
+ *  image that is already usable carries no `processing_info` except on the STATUS read. */
+function mediaAnswer(record: XMediaRecord, request: XRequest, status = false): Record<string, unknown> {
+  const data: Record<string, unknown> = {
+    id: record.id,
+    media_key: record.media_key,
+    expires_after_secs: Math.max(0, record.expires_at - nowSeconds(request)),
+  };
+  if (record.size !== undefined) data.size = record.size;
+  if (record.sha256 && !isVideoCategory(record.media_category)) data.image = { image_type: record.media_type, w: record.width, h: record.height };
+  if (record.sha256 && isVideoCategory(record.media_category) && record.state !== 'failed') data.video = { video_type: record.media_type };
+  const info = processingInfo(record) ?? (status ? { state: 'succeeded', progress_percent: 100 } : undefined);
+  if (info && (status || isVideoCategory(record.media_category) || record.state === 'failed')) data.processing_info = info;
+  // A failed processing run is the response's `errors` — the one place the v2 schema puts a reason.
+  const errors = record.state === 'failed'
+    ? [{ title: 'Invalid Request', detail: record.error ?? 'Invalid or Unsupported media.', type: 'https://api.x.com/2/problems/invalid-request' }]
+    : undefined;
+  return { data, ...(errors ? { errors } : {}) };
+}
+
+/** Whole bytes against the category: what they are, or why X would not take them. An image that
+ *  is not one is refused on the request; a video X would take the upload of and then FAIL in
+ *  processing, so a bad video becomes a `failed` record rather than a refused request. */
+function finishUpload(record: XMediaRecord, bytes: Uint8Array, sha256: string): XMediaRecord | XResponse {
+  if (!isVideoCategory(record.media_category)) {
+    if (bytes.length > MAX_IMAGE_BYTES) {
+      return invalidRequestProblem({ media: [String(bytes.length)] }, `The image is ${bytes.length} bytes, over X's ${MAX_IMAGE_BYTES}-byte limit for an image.`);
+    }
+    const info = sniffImage(bytes);
+    if (!info) return invalidRequestProblem({ media: [`(${bytes.length} bytes)`] }, 'The `media` bytes are not a supported image (JPEG, PNG, GIF or WebP).');
+    return { ...record, state: 'succeeded', media_type: info.mediaType, sha256, size: bytes.length, width: info.width, height: info.height };
+  }
+  if (bytes.length > MAX_VIDEO_BYTES) {
+    return invalidRequestProblem({ media: [String(bytes.length)] }, `The video is ${bytes.length} bytes, over X's ${MAX_VIDEO_BYTES}-byte limit for a video.`);
+  }
+  const video = sniffVideo(bytes);
+  const failed = (message: string): XMediaRecord => ({ ...record, state: 'failed', sha256, size: bytes.length, error: message });
+  if (!video) return failed('Invalid or Unsupported media, Reason: the file is not an MP4 with a video track.');
+  if (record.media_category === 'tweet_video' && video.durationMs > MAX_TWEET_VIDEO_MS) {
+    return failed(`Invalid or Unsupported media, Reason: Duration too long, maximum:${MAX_TWEET_VIDEO_MS / 1000}, actual:${(video.durationMs / 1000).toFixed(3)}`);
+  }
+  return { ...record, state: 'processing', processing_step: 0, media_type: video.mediaType, sha256, size: bytes.length, width: video.width, height: video.height, duration_ms: video.durationMs };
+}
+
+async function mintMediaId(request: XRequest, all: Resource[]): Promise<string> {
+  // RANDOM, not the high-water mark + 1: two clones of one World each upload before either pushes, and
+  // a counter hands both the same id, so the origin would hold one clone's file under the other's post
+  // (a push carries the media record by its id). 19 digits, as X's own snowflakes are.
+  const taken = new Set([...all.map((r) => String(r.id)), ...(await listMediaIds(request.root))]);
+  for (;;) {
+    const bytes = crypto.getRandomValues(new Uint8Array(8));
+    const n = (BigInt('0x' + [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')) % 8_000_000_000_000_000_000n) + 1_000_000_000_000_000_000n;
+    const id = String(n);
+    if (!taken.has(id)) return id;
+  }
+}
+
+/** X's media-key prefix names the kind: 3_ a photo, 7_ a posted video, 13_ an Amplify video. */
+function mediaKeyFor(category: string, id: string): string {
+  return `${category === 'tweet_video' ? '7' : category === 'amplify_video' ? '13' : '3'}_${id}`;
+}
+
+/** The one-shot upload: the whole file in one request. */
+async function uploadMedia(request: XRequest, all: Resource[], auth: Authorized, payload: Record<string, any>): Promise<XResponse> {
+  const refusal = scopeRefusal(auth, 'media.upload');
+  if (refusal) return refusal;
+  const extra = unknownField(bodyFieldNames(request, payload), ONE_SHOT_FIELDS);
+  if (extra) return extra;
+  const category = parseCategory(uploadField(request, payload, 'media_category'), ONE_SHOT_CATEGORIES_DOCUMENTED);
+  if (typeof category !== 'string') return category;
+  const owners = parseOwners(uploadField(request, payload, 'additional_owners'));
+  if (!isOwners(owners)) return owners;
+  const bytes = uploadBytes(request, payload);
+  if (!(bytes instanceof Uint8Array)) return bytes;
+  const id = await mintMediaId(request, all);
+  const opened: XMediaRecord = {
+    id, media_key: mediaKeyFor(category, id), account_id: auth.accountId, media_category: category, media_type: 'application/octet-stream', state: 'initialized',
+    ...(owners.length > 0 ? { additional_owners: owners } : {}),
+    created_at: request.occurredAt ?? new Date().toISOString(), expires_at: nowSeconds(request) + MEDIA_EXPIRES_AFTER_SECS,
+  };
+  // Check before storing: a refused image leaves no bytes behind.
+  const checked = finishUpload(opened, bytes, '');
+  if ('status' in checked) return checked;
+  const stored = await putXBlob(bytes, checked.media_type, request.root);
+  const record: XMediaRecord = { ...checked, sha256: stored.sha256, ...(checked.state === 'processing' ? { finalized_at: nowSeconds(request) } : {}) };
+  await writeMediaRecord(record, request.root);
+  return ok(mediaAnswer(record, request));
+}
+
+async function initializeUpload(request: XRequest, all: Resource[], auth: Authorized, payload: Record<string, any>): Promise<XResponse> {
+  const refusal = scopeRefusal(auth, 'media.upload');
+  if (refusal) return refusal;
+  const extra = unknownField(Object.keys(payload), INITIALIZE_FIELDS);
+  if (extra) return extra;
+  const category = parseCategory(payload.media_category);
+  if (typeof category !== 'string') return category;
+  const mediaType = payload.media_type;
+  if (typeof mediaType !== 'string' || !MEDIA_TYPES_DOCUMENTED.has(mediaType)) {
+    return invalidRequestProblem({ media_type: [String(mediaType ?? '')] }, `The \`media_type\` value [${String(mediaType ?? '')}] is not one of the documented media types`);
+  }
+  const video = isVideoCategory(category);
+  if (!IMAGE_TYPES.has(mediaType) && !VIDEO_TYPES.has(mediaType)) return unmodelledOption('media_type', mediaType);
+  if (video !== VIDEO_TYPES.has(mediaType)) {
+    return invalidRequestProblem({ media_type: [mediaType] }, `The \`media_type\` [${mediaType}] does not match the \`media_category\` [${category}].`);
+  }
+  const total = payload.total_bytes;
+  if (typeof total !== 'number' || !Number.isInteger(total) || total < 0) {
+    return invalidRequestProblem({ total_bytes: [String(total ?? '')] }, 'The `total_bytes` field is required and must be a non-negative integer.');
+  }
+  const ceiling = video ? MAX_VIDEO_BYTES : MAX_IMAGE_BYTES;
+  if (total > ceiling) return invalidRequestProblem({ total_bytes: [String(total)] }, `A${video ? ' video' : 'n image'} may be at most ${ceiling} bytes.`);
+  const owners = parseOwners(payload.additional_owners);
+  if (!isOwners(owners)) return owners;
+  const id = await mintMediaId(request, all);
+  const record: XMediaRecord = {
+    id, media_key: mediaKeyFor(category, id), account_id: auth.accountId, media_category: category, media_type: mediaType, state: 'initialized', total_bytes: total,
+    ...(owners.length > 0 ? { additional_owners: owners } : {}),
+    created_at: request.occurredAt ?? new Date().toISOString(), expires_at: nowSeconds(request) + MEDIA_EXPIRES_AFTER_SECS,
+  };
+  await writeMediaRecord(record, request.root);
+  return ok({ data: { id, media_key: record.media_key, expires_after_secs: MEDIA_EXPIRES_AFTER_SECS } });
+}
+
+/** An upload session this account started and has not finished — or X's refusal of the id. */
+async function openSession(request: XRequest, auth: Authorized, id: string): Promise<XMediaRecord | XResponse> {
+  const record = await readMediaRecord(id, request.root);
+  if (!record || record.account_id !== auth.accountId || record.expires_at <= nowSeconds(request)) {
+    return invalidRequestProblem({ media_id: [id] }, INVALID_MEDIA_IDS);
+  }
+  if (record.state !== 'initialized') return invalidRequestProblem({ media_id: [id] }, `Media ${id} is already finalized.`);
+  return record;
+}
+
+async function appendUpload(request: XRequest, auth: Authorized, id: string, payload: Record<string, any>): Promise<XResponse> {
+  const refusal = scopeRefusal(auth, 'media.upload');
+  if (refusal) return refusal;
+  const extra = unknownField(bodyFieldNames(request, payload), APPEND_FIELDS);
+  if (extra) return extra;
+  const record = await openSession(request, auth, id);
+  if ('status' in record) return record;
+  const rawIndex = uploadField(request, payload, 'segment_index');
+  const index = typeof rawIndex === 'number' ? rawIndex : typeof rawIndex === 'string' && /^\d+$/.test(rawIndex) ? Number(rawIndex) : Number.NaN;
+  if (!Number.isInteger(index) || index < 0 || index > 999) {
+    return invalidRequestProblem({ segment_index: [String(rawIndex ?? '')] }, 'The `segment_index` field is required and must be an integer between 0 and 999.');
+  }
+  const bytes = uploadBytes(request, payload);
+  if (!(bytes instanceof Uint8Array)) return bytes;
+  await putSegment(id, index, bytes, request.root);
+  return ok({ data: { expires_at: record.expires_at } });
+}
+
+async function finalizeUpload(request: XRequest, auth: Authorized, id: string): Promise<XResponse> {
+  const refusal = scopeRefusal(auth, 'media.upload');
+  if (refusal) return refusal;
+  const record = await openSession(request, auth, id);
+  if ('status' in record) return record;
+  const segments = await readSegments(id, request.root);
+  const size = segments.reduce((n, s) => n + s.length, 0);
+  if (segments.length === 0 || size !== record.total_bytes) {
+    return invalidRequestProblem({ media_id: [id] }, `The uploaded segments total ${size} bytes; initialize declared ${record.total_bytes}.`);
+  }
+  const whole = new Uint8Array(size);
+  let at = 0;
+  for (const segment of segments) { whole.set(segment, at); at += segment.length; }
+  const checked = finishUpload(record, whole, '');
+  if ('status' in checked) return checked;
+  const stored = await putXBlob(whole, checked.media_type, request.root);
+  const finished: XMediaRecord = { ...checked, sha256: stored.sha256, ...(checked.state === 'processing' ? { finalized_at: nowSeconds(request) } : {}) };
+  await writeMediaRecord(finished, request.root);
+  await clearSegments(id, request.root);
+  return ok(mediaAnswer(finished, request));
+}
+
+async function uploadStatus(request: XRequest, auth: Authorized, url: URL): Promise<XResponse> {
+  const refusal = scopeRefusal(auth, 'media.upload');
+  if (refusal) return refusal;
+  const command = url.searchParams.get('command');
+  if (command !== null && command !== 'STATUS') return invalidRequestProblem({ command: [command] }, `The \`command\` query parameter value [${command}] is not one of [STATUS]`);
+  const id = url.searchParams.get('media_id') ?? '';
+  if (!/^\d{1,19}$/.test(id)) return invalidRequestProblem({ media_id: [id] }, `The \`media_id\` query parameter value [${id}] does not match ^[0-9]{1,19}$`);
+  const stored = await readMediaRecord(id, request.root);
+  if (!stored || !canUse(stored, auth) || stored.expires_at <= nowSeconds(request)) return invalidRequestProblem({ media_id: [id] }, INVALID_MEDIA_IDS);
+  // A read of a processing video advances it one state (pending → in_progress → succeeded), on top
+  // of whatever the clock has already moved it; read-only, the clock alone moves it.
+  let record = settled(stored, request);
+  if (record.state === 'processing' && !request.readOnly) {
+    record = settled({ ...record, processing_step: (stored.processing_step ?? 0) + 1 }, request);
+  }
+  if (!request.readOnly && (record.state !== stored.state || record.processing_step !== stored.processing_step)) await writeMediaRecord(record, request.root);
+  return ok(mediaAnswer(record, request, true));
+}
+
+function canUse(record: XMediaRecord, auth: Authorized): boolean {
+  return record.account_id === auth.accountId || (record.additional_owners ?? []).includes(auth.accountId);
+}
+
+/** `media.media_ids` on a create, resolved to what the post will carry — or X's refusal. A post
+ *  carries up to four images or one video; a video still processing (or failed) is not usable. */
+async function resolveAttachedMedia(request: XRequest, auth: Authorized, media: unknown): Promise<{ media: AttachedMedia[] } | XResponse> {
+  if (media === undefined || media === null) return { media: [] };
+  if (typeof media !== 'object' || Array.isArray(media)) return invalidRequestProblem({ media: [JSON.stringify(media)] }, 'The `media` field must be an object with `media_ids`.');
+  const body = media as Record<string, unknown>;
+  for (const key of Object.keys(body)) {
+    if (key === 'media_ids') continue;
+    if (POST_MEDIA_FIELDS_UNMODELLED.has(key)) return unmodelledOption(`media.${key}`, JSON.stringify(body[key]));
+    return invalidRequestProblem({ [`media.${key}`]: [JSON.stringify(body[key])] }, `The \`media.${key}\` field is not a parameter of this request.`);
+  }
+  const ids = body.media_ids;
+  if (!Array.isArray(ids) || ids.length < 1 || ids.length > 4) {
+    return invalidRequestProblem({ 'media.media_ids': [JSON.stringify(ids ?? null)] }, 'The `media.media_ids` field must list between 1 and 4 media ids.');
+  }
+  const out: AttachedMedia[] = [];
+  for (const raw of ids) {
+    // the schema's items are STRINGS matching ^[0-9]{1,19}$: a JSON number is refused, not coerced
+    if (typeof raw !== 'string' || !/^\d{1,19}$/.test(raw)) {
+      return invalidRequestProblem({ 'media.media_ids': [String(raw)] }, `The \`media.media_ids\` value [${String(raw)}] is not a string matching ^[0-9]{1,19}$`);
+    }
+    const id = raw;
+    const stored = await readMediaRecord(id, request.root);
+    const record = stored ? settled(stored, request) : undefined;
+    // a DM category is a Direct Message's, never a post's
+    if (!record || record.state !== 'succeeded' || !canUse(record, auth) || record.expires_at <= nowSeconds(request) || !record.sha256 || record.media_category.startsWith('dm_')) {
+      return invalidRequestProblem({ 'media.media_ids': [id] }, INVALID_MEDIA_IDS);
+    }
+    out.push({
+      media_key: record.media_key, media_id: record.id, type: isVideoCategory(record.media_category) ? 'video' : 'photo',
+      media_type: record.media_type, media_category: record.media_category, sha256: record.sha256, size: record.size ?? 0,
+      ...(typeof record.width === 'number' ? { width: record.width } : {}), ...(typeof record.height === 'number' ? { height: record.height } : {}),
+      ...(typeof record.duration_ms === 'number' ? { duration_ms: record.duration_ms } : {}),
+    });
+  }
+  if (out.some((m) => m.type === 'video') && out.length > 1) {
+    return invalidRequestProblem({ 'media.media_ids': ids.map(String) }, 'A Post may carry up to four images or one video, not both.');
+  }
+  return { media: out };
+}
+
+// ── the reads ────────────────────────────────────────────────────────────────────────────────
+
+/** Post lookup by id. A post nobody created comes back inside `errors`, NEVER as a fabricated
+ *  `data` object — the whole point of a twin over a mock. */
+function lookupById(all: Resource[], auth: Authorized, id: string, url: URL, publicBase: string): XResponse {
+  const refusal = scopeRefusal(auth, 'tweets.lookup');
+  if (refusal) return refusal;
+  if (!/^\d+$/.test(id)) return invalidRequestProblem({ id: [id] }, `The \`id\` query parameter value [${id}] is not a valid Post id`);
+  const shape = parseReadShape(url, publicBase);
+  if (!isShape(shape)) return shape;
+  const post = findPost(all, id);
+  if (!post) return lookupResult(undefined, [resourceNotFoundError(id, 'tweet', 'id')]);
+  const includes = buildIncludes([post], all, shape);
+  return lookupResult(projectPost(post, shape.fields), [], includes);
+}
+
+/** Bulk lookup. X answers PARTIALLY: the ids that exist ride in `data`, the ones that do not ride
+ *  in `errors`, in one 200. Order follows the caller's `ids` list. */
+function lookupByIds(all: Resource[], auth: Authorized, url: URL, publicBase: string): XResponse {
+  const refusal = scopeRefusal(auth, 'tweets.lookup');
+  if (refusal) return refusal;
+  const raw = url.searchParams.get('ids');
+  const ids = csv(raw);
+  if (raw === null || ids.length === 0) return invalidRequestProblem({ ids: [String(raw ?? '')] }, 'The `ids` query parameter is required and must name at least one Post id.');
+  if (ids.length > 100) return invalidRequestProblem({ ids: [String(ids.length)] }, 'The `ids` query parameter accepts at most 100 Post ids.');
+  for (const id of ids) {
+    if (!/^\d+$/.test(id)) return invalidRequestProblem({ ids: [id] }, `The \`ids\` query parameter value [${id}] is not a valid Post id`);
+  }
+  const shape = parseReadShape(url, publicBase);
+  if (!isShape(shape)) return shape;
+  const found: Resource[] = [];
+  const errors: Array<Record<string, unknown>> = [];
+  for (const id of ids) {
+    const post = findPost(all, id);
+    if (post) found.push(post);
+    else errors.push(resourceNotFoundError(id, 'tweet', 'ids'));
+  }
+  const includes = buildIncludes(found, all, shape);
+  return lookupResult(found.length > 0 ? found.map((p) => projectPost(p, shape.fields)) : undefined, errors, includes);
+}
+
+// ── user lookup ─────────────────────────────────────────────────────────────────────────────
+// GET /2/users/:id and GET /2/users/by/username/:username — the pinned client's `user()` and
+// `userByUsername()` (dist/cjs/v2/client.v2.read.js:243, :258). A missing user is X's partial-
+// error 200 (`errors` with resource_type "user"), the same envelope a missing post uses.
+// GET /2/users/me is NOT here: it is xidentity's route, and the host claim keeps the two disjoint.
+
+const USER_EXPANSIONS_DOCUMENTED = new Set(['affiliation.user_id', 'most_recent_tweet_id', 'pinned_tweet_id']);
+
+function parseUserLookup(url: URL): Set<string> | XResponse {
+  for (const value of csv(url.searchParams.get('expansions'))) {
+    if (!USER_EXPANSIONS_DOCUMENTED.has(value)) {
+      return invalidRequestProblem({ expansions: [value] }, `The \`expansions\` query parameter value [${value}] is not one of the documented User expansions`);
+    }
+    return unmodelledOption('expansions', value);
+  }
+  // `tweet.fields` shapes an expanded pinned/most-recent post; with no user expansion modelled
+  // there is nothing for it to shape, so a request for it is refused by name, never ignored.
+  const tweetFields = url.searchParams.get('tweet.fields');
+  if (tweetFields !== null && tweetFields.trim() !== '') return unmodelledOption('tweet.fields', tweetFields);
+  return parseUserFields(url);
+}
+
+function lookupUserById(all: Resource[], auth: Authorized, id: string, url: URL): XResponse {
+  const refusal = scopeRefusal(auth, 'users.lookup');
+  if (refusal) return refusal;
+  if (!/^\d{1,19}$/.test(id)) return invalidRequestProblem({ id: [id] }, `The \`id\` query parameter value [${id}] is not a valid User id`);
+  const userFields = parseUserLookup(url);
+  if (!isFieldSet(userFields)) return userFields;
+  const account = findAccount(all, id);
+  if (!account) return lookupResult(undefined, [resourceNotFoundError(id, 'user', 'id')]);
+  return lookupResult(projectUser(account, userFields, all), []);
+}
+
+function lookupUserByUsername(all: Resource[], auth: Authorized, username: string, url: URL): XResponse {
+  const refusal = scopeRefusal(auth, 'users.lookup');
+  if (refusal) return refusal;
+  if (!/^[A-Za-z0-9_]{1,15}$/.test(username)) {
+    return invalidRequestProblem({ username: [username] }, `The \`username\` query parameter value [${username}] does not match ^[A-Za-z0-9_]{1,15}$`);
+  }
+  const userFields = parseUserLookup(url);
+  if (!isFieldSet(userFields)) return userFields;
+  // X handles are case-insensitive: @Volter and @volter are one account.
+  const account = ofType(all, 'account').find((a) => String(a.username).toLowerCase() === username.toLowerCase());
+  if (!account) return lookupResult(undefined, [resourceNotFoundError(username, 'user', 'username')]);
+  return lookupResult(projectUser(account, userFields, all), []);
+}
+
+function listMentions(all: Resource[], auth: Authorized, userId: string, url: URL, publicBase: string): XResponse {
+  const refusal = scopeRefusal(auth, 'mentions.list');
+  if (refusal) return refusal;
+  const account = findAccount(all, userId);
+  if (!account) return resourceNotFoundProblem(userId, 'user', 'id');
+  const read = parseReadRequest(url, 5, publicBase);
+  if (!isReadRequest(read)) return read;
+  const username = String(account.username);
+  const matched = livePosts(all).filter((p) => String(p.author_id) !== userId && mentionsHandle(String(p.text), username));
+  return timelinePage(applyWindow(matched, read.window), all, read.shape, read.size, read.cursor);
+}
+
+/** The user's own posted timeline — what the org actually said, in its own voice. */
+function listUserTweets(all: Resource[], auth: Authorized, userId: string, url: URL, publicBase: string): XResponse {
+  const refusal = scopeRefusal(auth, 'timelines.read');
+  if (refusal) return refusal;
+  const account = findAccount(all, userId);
+  if (!account) return resourceNotFoundProblem(userId, 'user', 'id');
+  const read = parseReadRequest(url, 5, publicBase);
+  if (!isReadRequest(read)) return read;
+  const matched = livePosts(all).filter((p) => String(p.author_id) === userId);
+  return timelinePage(applyWindow(matched, read.window), all, read.shape, read.size, read.cursor);
+}
+
+/**
+ * The HOME timeline: posts by the authenticated account and by the accounts it FOLLOWS. The
+ * follow graph is real state a world seeds through `/_twin/follows` — without it this endpoint
+ * would have to invent an audience, and a home timeline nobody follows into is a fabrication.
+ * X serves this route only for the authenticated user's own id.
+ */
+function listHomeTimeline(all: Resource[], auth: Authorized, userId: string, url: URL, publicBase: string): XResponse {
+  const refusal = scopeRefusal(auth, 'timelines.read');
+  if (refusal) return refusal;
+  const account = findAccount(all, userId);
+  if (!account) return resourceNotFoundProblem(userId, 'user', 'id');
+  if (userId !== auth.accountId) return forbiddenProblem('You are not permitted to access the home timeline of another account.');
+  const read = parseReadRequest(url, 5, publicBase);
+  if (!isReadRequest(read)) return read;
+  const following = new Set(
+    ofType(all, 'follow')
+      .filter((f) => String(f.follower_id) === userId)
+      .map((f) => String(f.followed_id)),
+  );
+  const matched = livePosts(all).filter((p) => String(p.author_id) === userId || following.has(String(p.author_id)));
+  return timelinePage(applyWindow(matched, read.window), all, read.shape, read.size, read.cursor);
+}
+
+function searchRecent(all: Resource[], auth: Authorized, url: URL, publicBase: string): XResponse {
+  const refusal = scopeRefusal(auth, 'search.recent');
+  if (refusal) return refusal;
+  const query = url.searchParams.get('query');
+  if (query === null || query.trim() === '') return invalidRequestProblem({ query: [String(query ?? '')] }, 'The `query` query parameter is required.');
+  const parsed = parseSearchQuery(query);
+  if ('unsupported' in parsed) {
+    return invalidRequestProblem(
+      { query: [parsed.unsupported] },
+      `The \`query\` operator [${parsed.unsupported}] is real X search grammar this twin does not model. It is refused rather than ignored, so a caller never receives results for a query the twin did not honour.`,
+    );
+  }
+  // Recent search bounds max_results at 10, unlike the 5 the timelines allow.
+  const read = parseReadRequest(url, 10, publicBase);
+  if (!isReadRequest(read)) return read;
+  const matched = livePosts(all).filter((p) => matchesSearch(p, all, parsed.terms));
+  return timelinePage(applyWindow(matched, read.window), all, read.shape, read.size, read.cursor);
+}
+
+// ── the twin control plane ──────────────────────────────────────────────────────────────────
+// Not vendor surface. `/_twin/*` is how a WORLD seeds the state a rehearsal needs — the org's
+// account, the bearer xidentity's flow would have minted, the inbound mention the reply class
+// answers, and the follow graph a home timeline reads — without running an OAuth leg or waiting
+// for a member of the public to post.
+
+async function handleTwinControl(request: XRequest, all: Resource[], path: string, payload: Record<string, any>): Promise<XResponse> {
+  if (request.method === 'POST' && path === '/_twin/accounts') {
+    const username = payload.username;
+    if (typeof username !== 'string' || !/^[A-Za-z0-9_]{1,15}$/.test(username)) {
+      return invalidRequestProblem({ username: [String(username ?? '')] }, 'A twin account requires an X-shaped username (1-15 of A-Z a-z 0-9 _).');
+    }
+    // The X Premium long-post entitlement, seeded rather than assumed. Out of range is a refusal,
+    // so a world cannot quietly hand an account a limit X does not offer.
+    const declaredLimit = payload.post_character_limit;
+    if (declaredLimit !== undefined
+      && (typeof declaredLimit !== 'number' || !Number.isInteger(declaredLimit) || declaredLimit < DEFAULT_POST_CHARACTER_LIMIT || declaredLimit > MAX_POST_CHARACTER_LIMIT)) {
+      return invalidRequestProblem({ post_character_limit: [String(declaredLimit)] }, `A seeded post_character_limit must be an integer between ${DEFAULT_POST_CHARACTER_LIMIT} and ${MAX_POST_CHARACTER_LIMIT}.`);
+    }
+    // An explicit id must be an X-SHAPED numeric snowflake. Everything downstream orders and
+    // joins on `BigInt(id)`, so a seeded `"abc"` would take a timeline read down at read time
+    // rather than being refused at the write that caused it.
+    if (payload.id !== undefined && (typeof payload.id !== 'string' || !/^\d+$/.test(payload.id.trim()))) {
+      return invalidRequestProblem({ id: [String(payload.id)] }, 'A seeded account id must be an X-shaped numeric snowflake.');
+    }
+    const id = typeof payload.id === 'string' && payload.id.trim() !== '' ? payload.id.trim() : mintSnowflakeId(all);
+    const name = typeof payload.name === 'string' ? payload.name : username;
+    // The profile an X account carries and `user.fields` serves back: optional, typed, seeded.
+    const profile: Record<string, unknown> = {};
+    for (const key of ['description', 'location', 'url'] as const) {
+      if (payload[key] === undefined) continue;
+      if (typeof payload[key] !== 'string') return invalidRequestProblem({ [key]: [String(payload[key])] }, `A seeded account's \`${key}\` must be a string.`);
+      profile[key] = payload[key];
+    }
+    for (const key of ['protected', 'verified'] as const) {
+      if (payload[key] === undefined) continue;
+      if (typeof payload[key] !== 'boolean') return invalidRequestProblem({ [key]: [String(payload[key])] }, `A seeded account's \`${key}\` must be a boolean.`);
+      profile[key] = payload[key];
+    }
+    const createdAt = request.occurredAt ?? new Date().toISOString();
+    await applyTwinWrite(SERVICE, {
+      operation: 'x.twin.seed_account',
+      subjectType: 'account',
+      subjectId: id,
+      fields: { username, name, created_at: createdAt, ...profile, ...(declaredLimit !== undefined ? { post_character_limit: declaredLimit } : {}) },
+      occurredAt: createdAt,
+    }, request.root);
+    return ok({ data: { id, username, name, ...profile, ...(declaredLimit !== undefined ? { post_character_limit: declaredLimit } : {}) } });
+  }
+
+  if (request.method === 'POST' && path === '/_twin/tokens') {
+    const token = payload.token;
+    const accountId = payload.account_id;
+    if (typeof token !== 'string' || token.trim() === '') return invalidRequestProblem({ token: [String(token ?? '')] }, 'A twin token requires a non-empty `token`.');
+    if (typeof accountId !== 'string' || findAccount(all, accountId) === undefined) {
+      return invalidRequestProblem({ account_id: [String(accountId ?? '')] }, 'A twin token must name an account seeded through /_twin/accounts.');
+    }
+    const scopes = Array.isArray(payload.scopes) ? payload.scopes.map(String) : parseScopeList(typeof payload.scopes === 'string' ? payload.scopes : '');
+    await applyTwinWrite(SERVICE, {
+      operation: 'x.twin.seed_token',
+      subjectType: 'token',
+      subjectId: token,
+      fields: { account_id: accountId, scopes },
+      occurredAt: request.occurredAt ?? new Date().toISOString(),
+    }, request.root);
+    return ok({ data: { token, account_id: accountId, scopes } });
+  }
+
+  if (request.method === 'POST' && path === '/_twin/posts') {
+    const text = payload.text;
+    const authorId = payload.author_id;
+    if (typeof text !== 'string' || text.trim() === '') return invalidRequestProblem({ text: [String(text ?? '')] }, 'A seeded post requires `text`.');
+    if (typeof authorId !== 'string' || findAccount(all, authorId) === undefined) {
+      return invalidRequestProblem({ author_id: [String(authorId ?? '')] }, 'A seeded post must name an account seeded through /_twin/accounts.');
+    }
+    const id = mintSnowflakeId(all);
+    const createdAt = request.occurredAt ?? new Date().toISOString();
+    await applyTwinWrite(SERVICE, {
+      operation: 'x.twin.seed_post',
+      subjectType: 'post',
+      subjectId: id,
+      fields: { text, author_id: authorId, created_at: createdAt, conversation_id: id, deleted: false },
+      occurredAt: createdAt,
+    }, request.root);
+    return ok({ data: { id, text, author_id: authorId } });
+  }
+
+  // The follow graph the HOME timeline reads. Seeded, never inferred: X's home timeline is
+  // "you and the accounts you follow", and a twin with no graph would have to invent an audience.
+  if (request.method === 'POST' && path === '/_twin/follows') {
+    const followerId = payload.follower_id;
+    const followedId = payload.followed_id;
+    for (const [name, value] of [['follower_id', followerId], ['followed_id', followedId]] as const) {
+      if (typeof value !== 'string' || findAccount(all, value) === undefined) {
+        return invalidRequestProblem({ [name]: [String(value ?? '')] }, `A twin follow must name an account seeded through /_twin/accounts (${name}).`);
+      }
+    }
+    if (followerId === followedId) return invalidRequestProblem({ followed_id: [String(followedId)] }, 'An account cannot follow itself.');
+    await applyTwinWrite(SERVICE, {
+      operation: 'x.twin.seed_follow',
+      subjectType: 'follow',
+      subjectId: `${followerId}:${followedId}`,
+      fields: { follower_id: followerId, followed_id: followedId },
+      occurredAt: request.occurredAt ?? new Date().toISOString(),
+    }, request.root);
+    return ok({ data: { follower_id: followerId, followed_id: followedId } });
+  }
+
+  // Arms the vendor's 15-minute-window refusal for the NEXT /2 request, so an integration can
+  // rehearse the 429 + legacy code 88 pair without waiting out a real window.
+  if (request.method === 'POST' && path === '/_twin/rate_limit') {
+    const resetAt = typeof payload.reset === 'number' ? payload.reset : 900;
+    await applyTwinWrite(SERVICE, {
+      operation: 'x.twin.arm_rate_limit',
+      subjectType: 'rate_limit',
+      subjectId: 'armed',
+      fields: { armed: payload.armed !== false, reset: resetAt, limit: typeof payload.limit === 'number' ? payload.limit : 200 },
+      occurredAt: request.occurredAt ?? new Date().toISOString(),
+    }, request.root);
+    return ok({ data: { armed: payload.armed !== false, reset: resetAt } });
+  }
+
+  return notFoundProblem();
+}
+
+function armedRateRefusal(all: Resource[]): XResponse | undefined {
+  const armed = ofType(all, 'rate_limit').find((r) => String(r.id) === 'armed');
+  if (!armed || armed.armed !== true) return undefined;
+  const limit = typeof armed.limit === 'number' ? armed.limit : 200;
+  const reset = typeof armed.reset === 'number' ? armed.reset : 900;
+  return rateLimitExceeded({
+    'x-rate-limit-limit': String(limit),
+    'x-rate-limit-remaining': '0',
+    'x-rate-limit-reset': String(Math.floor(Date.parse('1970-01-01T00:00:00.000Z') / 1000) + reset),
+  });
+}
+
+// ── the router ──────────────────────────────────────────────────────────────────────────────
+
+const TWEETS_PATH = '/2/tweets';
+const MEDIA_UPLOAD_PATH = '/2/media/upload';
+const MEDIA_INITIALIZE_PATH = '/2/media/upload/initialize';
+const MEDIA_SESSION_PATH = /^\/2\/media\/upload\/(\d{1,19})\/(append|finalize)$/;
+const SEARCH_RECENT_PATH = '/2/tweets/search/recent';
+const TWEET_ID_PATH = /^\/2\/tweets\/([^/]+)$/;
+const MENTIONS_PATH = /^\/2\/users\/([^/]+)\/mentions$/;
+const USER_TWEETS_PATH = /^\/2\/users\/([^/]+)\/tweets$/;
+const HOME_TIMELINE_PATH = /^\/2\/users\/([^/]+)\/timelines\/reverse_chronological$/;
+// `me` is excluded: GET /2/users/me is xidentity's route, never a user id here.
+const USER_ID_PATH = /^\/2\/users\/(?!me$)([^/]+)$/;
+const USER_BY_USERNAME_PATH = /^\/2\/users\/by\/username\/([^/]+)$/;
+
+export async function handleXTwinRequest(request: XRequest): Promise<XResponse> {
+  const url = new URL(request.path, 'http://twin.local');
+  const path = url.pathname;
+  const parsed = parseJsonBody(request.body);
+  if ('malformed' in parsed) return invalidRequestProblem({ body: ['(unparseable)'] }, 'The request body could not be parsed as a JSON object.');
+  const payload = parsed.object;
+  const all = resources(request.root);
+
+  if (path.startsWith('/_twin/')) {
+    if (request.readOnly) return readOnlyRefusal();
+    return handleTwinControl(request, all, path, payload);
+  }
+
+  // Everything below is vendor surface. An UNMODELLED /2 route fails like the vendor (404
+  // problem) rather than reporting a fake success — the rule the whole estate is held to.
+  if (!path.startsWith('/2/')) return notFoundProblem();
+
+  const refusal = armedRateRefusal(all);
+  if (refusal) return refusal;
+
+  const auth = authorize(all, request.headers);
+  if (isResponse(auth)) return auth;
+  const publicBase = (request.publicBase ?? PBS_BASE).replace(/\/+$/, '');
+
+  // MEDIA UPLOAD — staged bytes, not kernel state (x-media.ts).
+  if (path === MEDIA_UPLOAD_PATH) {
+    if (request.method === 'POST') {
+      if (request.readOnly) return readOnlyRefusal();
+      return uploadMedia(request, all, auth, payload);
+    }
+    if (request.method === 'GET') return uploadStatus(request, auth, url);
+  }
+  if (path === MEDIA_INITIALIZE_PATH && request.method === 'POST') {
+    if (request.readOnly) return readOnlyRefusal();
+    return initializeUpload(request, all, auth, payload);
+  }
+  const mediaSession = MEDIA_SESSION_PATH.exec(path);
+  if (mediaSession && request.method === 'POST') {
+    if (request.readOnly) return readOnlyRefusal();
+    return mediaSession[2] === 'append'
+      ? appendUpload(request, auth, mediaSession[1]!, payload)
+      : finalizeUpload(request, auth, mediaSession[1]!);
+  }
+
+  if (path === TWEETS_PATH) {
+    if (request.method === 'POST') {
+      if (request.readOnly) return readOnlyRefusal();
+      return createPost(request, all, auth, payload);
+    }
+    if (request.method === 'GET') return lookupByIds(all, auth, url, publicBase);
+  }
+
+  if (path === SEARCH_RECENT_PATH && request.method === 'GET') return searchRecent(all, auth, url, publicBase);
+
+  const byId = TWEET_ID_PATH.exec(path);
+  if (byId && request.method === 'DELETE') {
+    if (request.readOnly) return readOnlyRefusal();
+    return deletePost(request, all, auth, byId[1]!);
+  }
+  if (byId && request.method === 'GET') return lookupById(all, auth, byId[1]!, url, publicBase);
+
+  const mentions = MENTIONS_PATH.exec(path);
+  if (mentions && request.method === 'GET') return listMentions(all, auth, mentions[1]!, url, publicBase);
+
+  const userTweets = USER_TWEETS_PATH.exec(path);
+  if (userTweets && request.method === 'GET') return listUserTweets(all, auth, userTweets[1]!, url, publicBase);
+
+  const home = HOME_TIMELINE_PATH.exec(path);
+  if (home && request.method === 'GET') return listHomeTimeline(all, auth, home[1]!, url, publicBase);
+
+  const userById = USER_ID_PATH.exec(path);
+  if (userById && request.method === 'GET') return lookupUserById(all, auth, decodeURIComponent(userById[1]!), url);
+
+  const userByUsername = USER_BY_USERNAME_PATH.exec(path);
+  if (userByUsername && request.method === 'GET') return lookupUserByUsername(all, auth, decodeURIComponent(userByUsername[1]!), url);
+
+  return notFoundProblem();
+}