@volter/twin-x 0.1.0

package/src/x-connector.ts

@@ -0,0 +1,546 @@
+// X CONNECTOR — the live-vendor path for the posting surface.
+//
+// PULL (real → twin): TWO timelines, because an org's public voice has two halves. The MENTIONS
+// TIMELINE (`GET /2/users/:id/mentions`) is what was said TO the org — the input the demo's
+// reply class consumes. The OWN TIMELINE (`GET /2/users/:id/tweets`) is what the org itself
+// said, INCLUDING what it said somewhere else: by a human on x.com, or by an earlier run.
+// Without the second half, a twin that has been away comes back believing it never spoke.
+// Both are PAGED: a busy account's timeline arrives in pages joined by `meta.next_token`, and a
+// pull that read only the first page would put the older half of the account permanently outside
+// the twin while reporting a complete fold.
+//
+// PUSH (twin → real): unlike xidentity, this vendor HAS a write API, so push is real. A pending
+// `x.post.create` / `x.post.reply` / `x.post.quote` becomes `POST /2/tweets` (each carrying the
+// same body field the twin dispatched on — `reply.in_reply_to_tweet_id` for a reply,
+// `quote_tweet_id` for a quote, neither for an original post); a pending `x.post.delete`
+// becomes `DELETE /2/tweets/:id`. Each is confirmed with the id the REAL vendor minted, so the
+// twin's projection stops claiming a local id for a post that now exists in public.
+//
+// MEDIA. A post that carries images or a video names each one on its entry by key, local media id
+// and DIGEST (x-twin.ts createPost). The local media id means nothing at X, and an upload is not an
+// entry of its own (x-media.ts), so there is no adopted subject to resolve: the perform adapter
+// reads each file's bytes off the blob seam by digest, uploads them to the vendor through the same
+// v2 media endpoints the twin serves (one-shot for an image; initialize/append/finalize for a video,
+// then STATUS until X's processing says `succeeded`), and creates the post with the media ids X
+// minted. X media ids expire a day after upload, so uploading at perform time is also what the
+// vendor asks for.
+//
+// THE PERFORM PATH IS BUDGETED. The kernel hands `performXAction` its own executor
+// (buildRemoteExecute: the World's sealed credential), which knows nothing of X's limits, so the
+// adapter wraps it (`budgetedXExecute`) in this pack's XBudget ledger — the same mechanism
+// `liveXExecute` uses: every call is charged BEFORE it goes out, a refusal THROWS without calling
+// X, and a 429 / Retry-After arms the persisted cooldown. The ledger is the box's X ledger
+// (VOLTER_HOME), shared by every World and branch that performs to X from here, so no number of
+// branches multiplies the allowance.
+//
+// THE BOUND ON A VIDEO. X's processing can take longer than anyone should hold a request for. The
+// wait on STATUS honours each `check_after_secs` (at least 1 s) and stops at 120 s in total or 30
+// polls, whichever comes first; past that the perform fails with a RETRYABLE reason ("video still
+// processing at the vendor"). The kernel records that as a `failed` receipt, which leaves the entry
+// deployable, so the next deploy performs it again (and uploads afresh — an unfinished media id is
+// not reused). So a deploy, and a write at an `auto` head (which performs inside the request),
+// spends at most ~120 s waiting on X's processing per video, plus the upload itself. At an `auto`
+// head the kernel reverts a write whose perform failed (head.ts performAtHead): the app is told no,
+// with that reason, and retries the write itself.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO X
+// credential and import NO network client. Offline/tests pass a fake executor; live runs pass
+// `liveXExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, confirmAction, pendingActions, syncPull } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { XBudget, XBudgetError, xBudgetPath, xCallWeight, type XBudgetOptions } from './x-budget.ts';
+import { readXBlob } from './x-media.ts';
+
+const SERVICE = 'x';
+
+/** X's real host — the live executor's routing table. ONLY mapped paths may be called live, so a
+ *  typo or a widened caller cannot reach an X endpoint this pack has never modelled. */
+const HOST = 'https://api.x.com';
+const ALLOWED_PATHS: ReadonlyArray<RegExp> = [
+  /^\/2\/tweets$/,
+  /^\/2\/tweets\/[^/]+$/,
+  /^\/2\/users\/[^/]+\/mentions$/,
+  /^\/2\/users\/[^/]+\/tweets$/,
+];
+
+/** The modelled tweet.fields a pull requests — every field the twin's post rows can hold. */
+export const PULL_TWEET_FIELDS = ['author_id', 'created_at', 'conversation_id', 'in_reply_to_user_id', 'referenced_tweets'] as const;
+
+export type XExecute = (
+  method: 'GET' | 'POST' | 'DELETE',
+  path: string,
+  init?: { headers?: Record<string, string>; body?: string },
+) => Promise<Record<string, any>>;
+
+export type LiveXOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: XBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: XBudgetOptions;
+};
+
+/**
+ * A live executor against the real X API, holding the operator's OWN user access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live X request, and therefore the one place the rate
+ * budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request goes
+ * out (`checkBudget`, which THROWS instead of returning when the ceiling or a cooldown says stop)
+ * and the response is fed back (`recordCall`) so a 429 / `Retry-After` becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching X. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client
+ * (`assertBudgetGuardIntact`). This matters more here than on a read-only vendor: an unguarded
+ * loop at this vendor does not waste quota, it POSTS IN PUBLIC.
+ */
+export function liveXExecute(accessToken: string, opts: LiveXOptions = {}): XExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, XBudget, 'liveXExecute')
+    : new XBudget({ ...(opts.budgetOptions ?? {}), token: accessToken });
+  const explicitLedger = opts.budgetOptions?.path !== undefined || opts.budgetOptions?.root !== undefined;
+  if (opts.budget && !explicitLedger && budget.path !== xBudgetPath({ token: accessToken })) {
+    throw new Error('liveXExecute: injected budget is not keyed to the credential this client will send');
+  }
+  return async (method, path, init) => {
+    const bare = path.split('?')[0] ?? path;
+    if (!ALLOWED_PATHS.some((allowed) => allowed.test(bare))) throw new Error(`liveXExecute: refusing to call an unmapped X path: ${bare}`);
+    const weight = xCallWeight(method, path);
+    if (Object.keys(init?.headers ?? {}).some((name) => name.toLowerCase() === 'authorization')) {
+      throw new Error('liveXExecute: refusing an injected Authorization header; the guarded credential is fixed at construction');
+    }
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${HOST}${path}`, {
+      method,
+      headers: { 'content-type': 'application/json', ...(init?.headers ?? {}), Authorization: `Bearer ${accessToken}` },
+      ...(init?.body !== undefined ? { body: init.body } : {}),
+    });
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => {
+      resHeaders[k.toLowerCase()] = v;
+    });
+    // Settles the reservation and, on a back-off signal, arms the cooldown. The cooldown is
+    // persisted before body parsing or any throw, so even an HTML/plain-text 429 survives it.
+    // recordCall may THROW after arming it (a back-off beyond the cap). On a refused call that
+    // louder refusal wins; on a call X ACCEPTED the answer is kept — a post that landed in public
+    // must be confirmed under its id, never recorded as failed and posted again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof XBudgetError) || !res.ok) throw error;
+    }
+    const raw = await res.text();
+    let parsed: Record<string, any>;
+    try {
+      parsed = raw === '' ? {} : JSON.parse(raw) as Record<string, any>;
+    } catch {
+      throw new Error(`x returned non-JSON for ${method} ${bare}: HTTP ${res.status}`);
+    }
+    // A REFUSED call is NOT an empty result. X answers failures with a problem envelope
+    // (`title`/`type`), a legacy `errors` array, OR a 200 whose body carries partial `errors` —
+    // a status check alone cannot tell refusal from emptiness, so every refusal shape throws.
+    if (res.status >= 400) throw new Error(`x refused ${method} ${bare}: HTTP ${res.status} ${JSON.stringify(parsed)}`);
+    if (parsed && typeof parsed === 'object' && !('data' in parsed) && !('meta' in parsed) && ('errors' in parsed || 'title' in parsed)) {
+      throw new Error(`x refused ${method} ${bare}: ${JSON.stringify(parsed)}`);
+    }
+    return parsed;
+  };
+}
+
+/** Map one real timeline post → the twin's `post` SyncResource. Nothing invented: a field the
+ *  response omits records NOTHING rather than a placeholder, so a partial reply can never fold a
+ *  null over a previously observed value. */
+export function mapTimelinePost(row: Record<string, any>): SyncResource {
+  return {
+    type: 'post',
+    id: String(row.id ?? ''),
+    fields: {
+      ...(typeof row.text === 'string' ? { text: row.text } : {}),
+      ...(typeof row.author_id === 'string' ? { author_id: row.author_id } : {}),
+      ...(typeof row.created_at === 'string' ? { created_at: row.created_at } : {}),
+      ...(typeof row.conversation_id === 'string' ? { conversation_id: row.conversation_id } : {}),
+      ...(typeof row.in_reply_to_user_id === 'string' ? { in_reply_to_user_id: row.in_reply_to_user_id } : {}),
+      ...(Array.isArray(row.referenced_tweets) ? { referenced_tweets: row.referenced_tweets } : {}),
+      deleted: false,
+      pulled: true,
+    },
+  };
+}
+
+/**
+ * A MOVING pull timestamp, forced strictly increasing within the process — never a pinned
+ * constant (ADDING_A_TWIN.md §6: under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the delta silently vanishes).
+ */
+let lastPollMs = 0;
+function pollTimestamp(): string {
+  const now = Date.now();
+  lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+  return new Date(lastPollMs).toISOString();
+}
+
+/** How many pages one pull will follow before it refuses. A vendor that keeps handing back a
+ *  token is a loop or a bug, not a deep timeline; the pull stops and SAYS SO rather than paging
+ *  forever or quietly truncating. 32 pages at X's 100-per-page ceiling is its own 3200-post
+ *  timeline depth. */
+const MAX_PULL_PAGES = 32;
+
+/**
+ * Read ONE timeline to its end, following `meta.next_token`.
+ *
+ * The refusal checks live HERE, not only in the live executor: an injected executor (or a vendor
+ * 200 carrying a problem envelope) must never fold an empty timeline over observed state. X OMITS
+ * `data` on an empty timeline and answers with `meta` alone, so an empty page is
+ * `meta.result_count === 0` — a body with NEITHER `data` nor `meta` is a refusal and throws.
+ */
+async function collectXTimeline(execute: XExecute, label: string, basePath: string): Promise<SyncResource[]> {
+  const collected: SyncResource[] = [];
+  const seenTokens = new Set<string>();
+  let token: string | undefined;
+  for (let page = 0; page < MAX_PULL_PAGES; page += 1) {
+    const paging = token === undefined ? '' : `&pagination_token=${encodeURIComponent(token)}`;
+    const body = await execute('GET', `${basePath}?tweet.fields=${PULL_TWEET_FIELDS.join(',')}${paging}`);
+    if (!body || typeof body !== 'object') throw new Error(`x ${label} pull refused or malformed: no body`);
+    const rows = body.data;
+    if (rows === undefined) {
+      if (body.meta && typeof body.meta === 'object') return collected;
+      throw new Error(`x ${label} pull refused or malformed: ${JSON.stringify(body).slice(0, 200)}`);
+    }
+    if (!Array.isArray(rows)) throw new Error(`x ${label} pull refused or malformed: ${JSON.stringify(body).slice(0, 200)}`);
+    // An X post id is a NUMERIC snowflake string. A row without one is not a post this twin can
+    // key, and folding it would put a foreign id into the projection's id space.
+    for (const row of rows) {
+      if (!row || typeof row !== 'object' || typeof row.id !== 'string' || !/^\d+$/.test(row.id)) {
+        throw new Error(`x ${label} pull returned a row with no X-shaped id: ${JSON.stringify(row).slice(0, 200)}`);
+      }
+    }
+    collected.push(...(rows as Array<Record<string, any>>).map(mapTimelinePost));
+    const next = body.meta?.next_token;
+    if (next === undefined || next === null) return collected;
+    if (typeof next !== 'string' || next === '') throw new Error(`x ${label} pull returned an unusable next_token: ${JSON.stringify(next)}`);
+    // A token this pull has already followed means the vendor is not advancing. Following it
+    // again loops; stopping SILENTLY would report a complete pull that is missing rows.
+    if (seenTokens.has(next)) throw new Error(`x ${label} pull was handed a repeated next_token (${next}); refusing to page in a loop`);
+    seenTokens.add(next);
+    token = next;
+  }
+  throw new Error(`x ${label} pull exceeded ${MAX_PULL_PAGES} pages; refusing to page further`);
+}
+
+async function collectXMentions(execute: XExecute, userId: string): Promise<SyncResource[]> {
+  return collectXTimeline(execute, 'mentions', `/2/users/${encodeURIComponent(userId)}/mentions`);
+}
+
+/** The org's OWN posted timeline — what it said, including what it said somewhere else. */
+async function collectXOwnTimeline(execute: XExecute, userId: string): Promise<SyncResource[]> {
+  return collectXTimeline(execute, 'own timeline', `/2/users/${encodeURIComponent(userId)}/tweets`);
+}
+
+/** PULL the org's mentions timeline into the twin's observed log (idempotent). */
+export async function pullXMentions(execute: XExecute, userId: string, root?: string, occurredAt?: string): Promise<number> {
+  const resources = await collectXMentions(execute, userId);
+  syncPull({ service: SERVICE, resources, occurredAt: occurredAt ?? pollTimestamp(), ...(root !== undefined ? { root } : {}) });
+  return resources.length;
+}
+
+/** PULL the org's OWN posted timeline into the twin's observed log (idempotent). */
+export async function pullXOwnTimeline(execute: XExecute, userId: string, root?: string, occurredAt?: string): Promise<number> {
+  const resources = await collectXOwnTimeline(execute, userId);
+  syncPull({ service: SERVICE, resources, occurredAt: occurredAt ?? pollTimestamp(), ...(root !== undefined ? { root } : {}) });
+  return resources.length;
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real X posting surface
+ * and fold it into the twin in ONE shadow-diffed `syncPull`, returning the standard
+ * `{ observed, deltasAppended }`. Idempotent — a re-pull of identical state appends nothing.
+ */
+export async function syncXFromReal(
+  execute: XExecute,
+  opts: { userId: string; root?: string; occurredAt?: string; includeOwnTimeline?: boolean },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const occurredAt = opts.occurredAt ?? pollTimestamp();
+  const mentions = await collectXMentions(execute, opts.userId);
+  // BOTH halves by DEFAULT. `includeOwnTimeline: false` exists for a caller that genuinely only
+  // wants the inbox — never as the default, which is exactly the hole the pull audit filed as
+  // `x.connector.pull_own_timeline`.
+  const own = opts.includeOwnTimeline === false ? [] : await collectXOwnTimeline(execute, opts.userId);
+  // At the vendor a post can only be on one of the two timelines (the mentions timeline excludes
+  // the account's own posts), but keying the fold by id keeps it single-valued rather than
+  // trusting that.
+  const byId = new Map<string, SyncResource>();
+  for (const resource of [...mentions, ...own]) byId.set(resource.id, resource);
+  const resources = [...byId.values()];
+  const result = syncPull({ service: SERVICE, resources, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}
+
+/**
+ * The request ONE pending twin action becomes at the real vendor. A pure shape builder — it
+ * issues nothing, so it can be asserted directly. The reply's discriminator travels here exactly
+ * as the twin read it: `reply.in_reply_to_tweet_id`, the same field, in the same place.
+ */
+export function xRequestForAction(action: { operation?: string; subject?: { type: string; id: string }; fields?: Record<string, any> }):
+  | { method: 'POST' | 'DELETE'; path: string; body?: string }
+  | undefined {
+  const fields = action.fields ?? {};
+  const id = action.subject?.id ?? '';
+  // `media.media_ids`, when the post carries media: the ids as the fields name them — the vendor's
+  // once performXAction has uploaded and swapped them in.
+  const mediaIds = Array.isArray(fields.media) ? fields.media.map((m: any) => String(m?.media_id ?? '')).filter((m: string) => m !== '') : [];
+  const media = mediaIds.length > 0 ? { media: { media_ids: mediaIds } } : {};
+  if (action.operation === 'x.post.create') {
+    return { method: 'POST', path: '/2/tweets', body: JSON.stringify({ text: String(fields.text ?? ''), ...media }) };
+  }
+  if (action.operation === 'x.post.reply') {
+    const referenced = Array.isArray(fields.referenced_tweets) ? fields.referenced_tweets : [];
+    const parent = referenced.find((r: any) => r?.type === 'replied_to');
+    if (!parent?.id) return undefined;
+    return { method: 'POST', path: '/2/tweets', body: JSON.stringify({ text: String(fields.text ?? ''), reply: { in_reply_to_tweet_id: String(parent.id) }, ...media }) };
+  }
+  if (action.operation === 'x.post.quote') {
+    const referenced = Array.isArray(fields.referenced_tweets) ? fields.referenced_tweets : [];
+    const quoted = referenced.find((r: any) => r?.type === 'quoted');
+    if (!quoted?.id) return undefined;
+    return { method: 'POST', path: '/2/tweets', body: JSON.stringify({ text: String(fields.text ?? ''), quote_tweet_id: String(quoted.id), ...media }) };
+  }
+  if (action.operation === 'x.post.delete') {
+    return { method: 'DELETE', path: `/2/tweets/${encodeURIComponent(id)}` };
+  }
+  return undefined;
+}
+
+/**
+ * PUSH one pending action to the real vendor and confirm it with what the vendor answered.
+ *
+ * A create/reply is confirmed under the REAL id X minted, not the twin's locally minted one:
+ * after a push the public post has a public id, and a projection still claiming the local id
+ * would make every later delete address a post that does not exist. The local subject is
+ * confirmed as superseded in the same call.
+ */
+export async function pushXAction(
+  execute: XExecute,
+  action: { id: string; operation?: string; subject?: { type: string; id: string }; fields?: Record<string, any> },
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ pushed: boolean; realId?: string; reason?: string }> {
+  // A post's media ids are local; only the perform adapter uploads the files and swaps in X's ids.
+  // So a create/reply/quote CARRYING media is not pushable here — reported, not thrown, so a push
+  // of many entries carries on past it. A delete never uploads anything and is pushed as ever.
+  const writesPost = action.operation === 'x.post.create' || action.operation === 'x.post.reply' || action.operation === 'x.post.quote';
+  if (writesPost && Array.isArray(action.fields?.media) && action.fields.media.length > 0) {
+    return { pushed: false, reason: `${action.operation} carries media, which crosses through performXAction (it uploads the files first)` };
+  }
+  const request = xRequestForAction(action);
+  if (!request) return { pushed: false };
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const localId = action.subject?.id ?? '';
+  const reply = await execute(request.method, request.path, request.body === undefined ? undefined : { body: request.body });
+
+  if (request.method === 'DELETE') {
+    if (reply?.data?.deleted !== true) throw new Error(`x refused the delete of ${localId}: ${JSON.stringify(reply).slice(0, 200)}`);
+    confirmAction({ service: SERVICE, actionId: action.id, subject: { type: 'post', id: localId }, fields: { ...(action.fields ?? {}), deleted: true, pushed: true }, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+    return { pushed: true, realId: localId };
+  }
+
+  const realId = reply?.data?.id;
+  if (typeof realId !== 'string' || !/^\d+$/.test(realId)) throw new Error(`x returned no post id for ${action.operation}: ${JSON.stringify(reply).slice(0, 200)}`);
+  confirmAction({
+    service: SERVICE,
+    actionId: action.id,
+    subject: { type: 'post', id: realId },
+    fields: { ...(action.fields ?? {}), pushed: true, local_id: localId },
+    // The locally minted subject is retired in the SAME compound confirmation, so no window
+    // exists in which both ids look live.
+    ...(localId !== realId ? { additionalObservations: [{ subject: { type: 'post', id: localId }, fields: { ...(action.fields ?? {}), superseded_by: realId, deleted: true } }] } : {}),
+    occurredAt,
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+  });
+  return { pushed: true, realId };
+}
+
+/** Push every pending action this connector knows how to push. */
+export async function pushPendingXActions(
+  execute: XExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ pushed: number; unpushable: number }> {
+  let pushed = 0;
+  let unpushable = 0;
+  for (const action of pendingActions(SERVICE, opts.root)) {
+    const result = await pushXAction(execute, action as never, opts);
+    if (result.pushed) pushed += 1;
+    else unpushable += 1;
+  }
+  return { pushed, unpushable };
+}
+
+/**
+ * The perform adapter (runtime contract R18): what a World's deploy calls for each landed X entry
+ * on a twin whose root is the platform. A post, reply, quote or delete crosses through the host's
+ * executor, which adds the sealed credential; the kernel records the landing from the returned id.
+ * Anything else (a seeded account or token) is the twin's own record and crosses nothing. A
+ * reply's or quote's parent authored against a local id crosses against the id X minted for it.
+ */
+/**
+ * The kernel executor, charged to this pack's XBudget: the check RESERVES before the call and
+ * throws (XBudgetError) instead of calling when the ceiling, the burst bound or a cooldown says
+ * stop; the response settles the reservation and arms a cooldown on 429 / Retry-After.
+ */
+export function budgetedXExecute(execute: RemoteExecute, budget: XBudget = new XBudget()): RemoteExecute {
+  const guard = assertBudgetGuardIntact(budget, XBudget, 'budgetedXExecute');
+  return async (request) => {
+    const weight = xCallWeight(request.method, request.path);
+    const reservation = guard.checkBudget(weight);
+    const res = await execute(request);
+    // The vendor has ANSWERED: whatever the ledger says next, the answer goes back. recordCall
+    // persists any cooldown BEFORE it throws (a back-off beyond the cap), so the throw is caught
+    // here and the cooldown stands — the next call is refused by it. Dropping the answer would
+    // record a write X accepted as failed: at an auto head the entry is reverted, and a retry
+    // posts it twice. A refused answer carries its own status to the caller.
+    try {
+      guard.recordCall(weight, Object.fromEntries(Object.entries(res.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v])), { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof XBudgetError)) throw error;
+    }
+    return res;
+  };
+}
+
+export async function performXAction(kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  // ONE LEDGER PER CREDENTIAL: X's limits belong to the token, so every World and branch performing
+  // with one sealed credential shares that credential's ledger (keyed by its fingerprint); with none
+  // sealed (a twin-only perform) the ledger is the control root's, never one machine-wide file
+  const execute = budgetedXExecute(kernelExecute, new XBudget(ctx.credential !== undefined ? { token: ctx.credential } : ctx.root !== undefined ? { root: ctx.root } : {}));
+  const fields = { ...(action.fields ?? {}) } as Record<string, any>;
+  if (Array.isArray(fields.referenced_tweets)) {
+    fields.referenced_tweets = fields.referenced_tweets.map((r: any) => (r?.id ? { ...r, id: ctx.resolve('post', String(r.id)) } : r));
+  }
+  const subjectId = action.subject?.id ?? '';
+  const target = action.operation === 'x.post.delete' ? ctx.resolve('post', subjectId) : subjectId;
+  // Media first: each file goes to the vendor, and the post names the ids X minted for them.
+  const vendorMediaIds: string[] = [];
+  if (action.operation !== 'x.post.delete' && Array.isArray(fields.media) && fields.media.length > 0) {
+    const uploaded: Array<Record<string, any>> = [];
+    for (const media of fields.media as Array<Record<string, any>>) {
+      const bytes = typeof media.sha256 === 'string' ? await readXBlob(media.sha256, ctx.root) : null;
+      if (!bytes) throw new Error(`x cannot perform ${action.operation} on ${subjectId}: the bytes of ${String(media.media_key)} are not on this twin's blob seam`);
+      const vendor = await uploadMediaToVendor(execute, media, bytes);
+      vendorMediaIds.push(vendor.id);
+      uploaded.push({ ...media, media_id: vendor.id, ...(vendor.media_key ? { media_key: vendor.media_key } : {}) });
+    }
+    fields.media = uploaded;
+  }
+  const request = xRequestForAction({ operation: action.operation, subject: { type: 'post', id: target }, fields });
+  if (!request) {
+    // seeded state (x.twin.*) is the twin's own record; a post it cannot express fails loudly, never a silent receipt
+    if ((action.operation ?? '').startsWith('x.twin.')) return { externalId: ctx.resolve(action.subject?.type ?? 'post', subjectId), data: { performed: false, reason: `${action.operation} is the twin's own record — nothing at X to write` } };
+    throw new Error(`x cannot perform ${action.operation ?? 'this entry'} on ${subjectId}: no X request expresses it`);
+  }
+  const res = await execute({
+    method: request.method,
+    path: request.path,
+    headers: { accept: 'application/json', ...(request.body === undefined ? {} : { 'content-type': 'application/json' }) },
+    ...(request.body === undefined ? {} : { body: request.body }),
+  });
+  if (res.status < 200 || res.status >= 300) throw new Error(`x refused ${action.operation}: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+  let reply: Record<string, any> = {};
+  try { reply = res.body ? JSON.parse(res.body) : {}; } catch { throw new Error(`x answered ${action.operation} with a body that is not JSON: ${res.body.slice(0, 200)}`); }
+  if (request.method === 'DELETE') {
+    if (reply?.data?.deleted !== true) throw new Error(`x refused the delete of ${target}: ${res.body.slice(0, 200)}`);
+    return { externalId: target, data: { deleted: true } };
+  }
+  const realId = reply?.data?.id;
+  if (typeof realId !== 'string' || !/^\d+$/.test(realId)) throw new Error(`x returned no post id for ${action.operation}: ${res.body.slice(0, 200)}`);
+  return { externalId: realId, url: `https://x.com/i/web/status/${realId}`, data: { text: reply.data.text, ...(vendorMediaIds.length > 0 ? { media: fields.media } : {}) } };
+}
+
+// ── media to the vendor ──────────────────────────────────────────────────────────────────────
+
+/** How much of a video one APPEND carries. X accepts segments up to 5 MB. */
+const APPEND_CHUNK_BYTES = 4 * 1024 * 1024;
+/** How long, in total, a perform waits on X's video processing before it fails the entry
+ *  retryably — the bound on a request at an `auto` head (see the header). */
+export const MAX_PROCESSING_WAIT_MS = 120_000;
+/** At most this many STATUS reads per video, whatever `check_after_secs` says. */
+export const MAX_PROCESSING_POLLS = 30;
+
+/** The vendor has the video but has not finished processing it inside the bound: retry later. */
+export class XVideoStillProcessingError extends Error {
+  readonly retryable = true;
+  constructor(readonly mediaId: string, waitedMs: number, polls: number) {
+    super(`video still processing at the vendor (media ${mediaId}) after ${Math.round(waitedMs / 1000)}s and ${polls} STATUS reads — the entry stays pending; the next deploy performs it again`);
+    this.name = 'XVideoStillProcessingError';
+  }
+}
+
+/** A multipart/form-data body as bytes, with the boundary its content-type names. */
+async function multipart(parts: Record<string, string | Uint8Array>): Promise<{ body: Uint8Array; contentType: string }> {
+  const form = new FormData();
+  for (const [name, value] of Object.entries(parts)) {
+    if (typeof value === 'string') form.append(name, value);
+    else { const copy = new Uint8Array(value.length); copy.set(value); form.append(name, new Blob([copy]), 'blob'); }
+  }
+  const encoded = new Response(form);
+  // read the boundary BEFORE the body: Bun drops the content-type once the body has been consumed
+  const contentType = encoded.headers.get('content-type');
+  if (!contentType) throw new Error('x: the runtime did not name a multipart boundary');
+  return { body: new Uint8Array(await encoded.arrayBuffer()), contentType };
+}
+
+async function vendorCall(execute: RemoteExecute, label: string, request: Parameters<RemoteExecute>[0]): Promise<Record<string, any>> {
+  const res = await execute({ ...request, headers: { accept: 'application/json', ...(request.headers ?? {}) } });
+  if (res.status < 200 || res.status >= 300) throw new Error(`x refused ${label}: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+  let parsed: Record<string, any>;
+  try { parsed = res.body ? JSON.parse(res.body) : {}; } catch { throw new Error(`x answered ${label} with a body that is not JSON: ${res.body.slice(0, 200)}`); }
+  if (parsed?.errors && !parsed?.data) throw new Error(`x refused ${label}: ${res.body.slice(0, 200)}`);
+  return parsed;
+}
+
+/** One file to the vendor: an image in one request; a video initialized, appended in segments,
+ *  finalized, then polled on STATUS as X's `processing_info` asks until it has succeeded. */
+async function uploadMediaToVendor(execute: RemoteExecute, media: Record<string, any>, bytes: Uint8Array): Promise<{ id: string; media_key?: string }> {
+  const minted = (answer: Record<string, any>) => ({ id: String(answer.data.id), ...(typeof answer.data.media_key === 'string' ? { media_key: answer.data.media_key } : {}) });
+  const category = typeof media.media_category === 'string' ? media.media_category : media.type === 'video' ? 'tweet_video' : 'tweet_image';
+  if (media.type !== 'video') {
+    const form = await multipart({ media_category: category, media: bytes });
+    const answer = await vendorCall(execute, 'the image upload', { method: 'POST', path: '/2/media/upload', headers: { 'content-type': form.contentType }, body: form.body });
+    const id = answer?.data?.id;
+    if (typeof id !== 'string' || !/^\d+$/.test(id)) throw new Error(`x returned no media id for the image upload: ${JSON.stringify(answer).slice(0, 200)}`);
+    return minted(answer);
+  }
+  const init = await vendorCall(execute, 'the video upload (initialize)', {
+    method: 'POST', path: '/2/media/upload/initialize', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ media_type: String(media.media_type ?? 'video/mp4'), total_bytes: bytes.length, media_category: category }),
+  });
+  const id = init?.data?.id;
+  if (typeof id !== 'string' || !/^\d+$/.test(id)) throw new Error(`x returned no media id for the video upload: ${JSON.stringify(init).slice(0, 200)}`);
+  for (let at = 0, index = 0; at < bytes.length; at += APPEND_CHUNK_BYTES, index += 1) {
+    const form = await multipart({ segment_index: String(index), media: bytes.subarray(at, at + APPEND_CHUNK_BYTES) });
+    await vendorCall(execute, `the video upload (append ${index})`, { method: 'POST', path: `/2/media/upload/${id}/append`, headers: { 'content-type': form.contentType }, body: form.body });
+  }
+  let state = await vendorCall(execute, 'the video upload (finalize)', { method: 'POST', path: `/2/media/upload/${id}/finalize` });
+  const started = Date.now();
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+  let polls = 0;
+  for (;;) {
+    const info = state?.data?.processing_info;
+    if (!info || info.state === 'succeeded') return minted({ data: { ...init.data, ...(state?.data ?? {}) } });
+    if (info.state === 'failed') throw new Error(`x failed to process video ${id}: ${JSON.stringify(state.errors ?? info).slice(0, 200)}`);
+    const remaining = MAX_PROCESSING_WAIT_MS - (Date.now() - started);
+    const waitMs = Math.max(1, Number(info.check_after_secs ?? 1)) * 1000;
+    if (polls >= MAX_PROCESSING_POLLS || waitMs > remaining) throw new XVideoStillProcessingError(id, Date.now() - started, polls);
+    await sleep(waitMs);
+    try {
+      state = await vendorCall(execute, 'the video upload (status)', { method: 'GET', path: `/2/media/upload?command=STATUS&media_id=${id}` });
+    } catch (error) {
+      // the budget's BURST bound refusing a poll is a wait, not a failure, while the bound has room
+      // (the poll is not sent until the budget admits it); past the bound it is the same verdict as
+      // any other wait that outlasts it — the video is still processing, retry on the next deploy
+      if (!(error instanceof XBudgetError) || error.kind !== 'burst') throw error;
+      if (error.retryAfterMs > MAX_PROCESSING_WAIT_MS - (Date.now() - started)) throw new XVideoStillProcessingError(id, Date.now() - started, polls);
+      await sleep(error.retryAfterMs);
+      continue;
+    }
+    polls += 1;
+  }
+}