@volter/twin-x 0.1.0

package/dist/src/x-connector.js

@@ -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 { XBudget, XBudgetError, xBudgetPath, xCallWeight } from "./x-budget.js";
+import { readXBlob } from "./x-media.js";
+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 = [
+    /^\/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'];
+/**
+ * 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, opts = {}) {
+    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 = {};
+        res.headers.forEach((v, k) => {
+            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;
+        try {
+            parsed = raw === '' ? {} : JSON.parse(raw);
+        }
+        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) {
+    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() {
+    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, label, basePath) {
+    const collected = [];
+    const seenTokens = new Set();
+    let token;
+    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.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, userId) {
+    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, userId) {
+    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, userId, root, occurredAt) {
+    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, userId, root, occurredAt) {
+    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, opts) {
+    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();
+    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) {
+    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) => String(m?.media_id ?? '')).filter((m) => 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) => 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) => 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, action, opts = {}) {
+    // 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, opts = {}) {
+    let pushed = 0;
+    let unpushable = 0;
+    for (const action of pendingActions(SERVICE, opts.root)) {
+        const result = await pushXAction(execute, action, 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, budget = new XBudget()) {
+    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, action, ctx) {
+    // 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 ?? {}) };
+    if (Array.isArray(fields.referenced_tweets)) {
+        fields.referenced_tweets = fields.referenced_tweets.map((r) => (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 = [];
+    if (action.operation !== 'x.post.delete' && Array.isArray(fields.media) && fields.media.length > 0) {
+        const uploaded = [];
+        for (const media of fields.media) {
+            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 = {};
+    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 {
+    mediaId;
+    retryable = true;
+    constructor(mediaId, waitedMs, polls) {
+        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.mediaId = mediaId;
+        this.name = 'XVideoStillProcessingError';
+    }
+}
+/** A multipart/form-data body as bytes, with the boundary its content-type names. */
+async function multipart(parts) {
+    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, label, request) {
+    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;
+    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, media, bytes) {
+    const minted = (answer) => ({ 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) => 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;
+    }
+}

package/dist/src/x-media.d.ts

@@ -0,0 +1,87 @@
+/** The stored upload session / finished media object, keyed by the media id X hands back. */
+export type XMediaRecord = {
+    id: string;
+    media_key: string;
+    account_id: string;
+    media_category: string;
+    /** The declared (initialize) or sniffed MIME type. */
+    media_type: string;
+    /** `initialized` while segments arrive; an image is `succeeded` once its bytes are whole; a video
+     *  is `processing` (X's pending → in_progress) until STATUS reads walk it to `succeeded`, or
+     *  `failed` when the bytes are not a video X would take. */
+    state: 'initialized' | 'processing' | 'succeeded' | 'failed';
+    /** A video's processing step counted in STATUS reads (0 = pending, 1 = in_progress, 2 = done). */
+    processing_step?: number;
+    /** World-clock epoch seconds of FINALIZE: processing also advances one step per
+     *  `check_after_secs` elapsed since, so a client that sleeps and then posts is not held back. */
+    finalized_at?: number;
+    /** Why processing failed, in X's words (served as a problem in the response's `errors`). */
+    error?: string;
+    duration_ms?: number;
+    total_bytes?: number;
+    sha256?: string;
+    size?: number;
+    width?: number;
+    height?: number;
+    additional_owners?: string[];
+    created_at: string;
+    /** Epoch seconds after which X no longer accepts the id on a post. */
+    expires_at: number;
+};
+/** X keeps an uploaded media id usable for a day (`expires_after_secs: 86400` on its answers). */
+export declare const MEDIA_EXPIRES_AFTER_SECS = 86400;
+/** X's image ceiling: 5 MB. */
+export declare const MAX_IMAGE_BYTES: number;
+/** X's video ceiling: 512 MB. */
+export declare const MAX_VIDEO_BYTES: number;
+/** A `tweet_video` may run at most 140 seconds (longer videos are an `amplify_video` or a Premium entitlement). */
+export declare const MAX_TWEET_VIDEO_MS = 140000;
+/** Store bytes content-addressed; a re-upload of identical content is a no-op write. The MIME
+ *  type the upload was read as rides beside them, so the bytes routes answer with the type the
+ *  twin decided, never one a URL's extension claims. */
+export declare function putXBlob(bytes: Uint8Array, contentType: string, root?: string): Promise<{
+    sha256: string;
+    size: number;
+}>;
+/** The MIME type stored bytes were uploaded as (this branch, then its ancestors). */
+export declare function readXBlobType(sha256: string, root?: string): Promise<string | undefined>;
+/** Stored bytes by digest (this branch, then its ancestors); null when absent or malformed. */
+export declare function readXBlob(sha256: string, root?: string): Promise<Uint8Array | null>;
+export declare function writeMediaRecord(record: XMediaRecord, root?: string): Promise<void>;
+export declare function readMediaRecord(id: string, root?: string): Promise<XMediaRecord | undefined>;
+/** Every media id this branch or an ancestor has minted — so a new media id (and a new post id)
+ *  steps past them all. */
+export declare function listMediaIds(root?: string): Promise<string[]>;
+/** One APPEND segment, stored under its index (a retried index overwrites, as at X). */
+export declare function putSegment(id: string, index: number, bytes: Uint8Array, root?: string): Promise<void>;
+/** Every segment of an upload, in index order, across the branch chain (the nearest copy of an
+ *  index wins, as a retried APPEND overwrites at X). */
+export declare function readSegments(id: string, root?: string): Promise<Uint8Array[]>;
+export declare function clearSegments(id: string, root?: string): Promise<void>;
+export type ImageInfo = {
+    mediaType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    width: number;
+    height: number;
+};
+export declare function sniffImage(bytes: Uint8Array): ImageInfo | undefined;
+export type VideoInfo = {
+    mediaType: 'video/mp4';
+    width: number;
+    height: number;
+    durationMs: number;
+};
+/**
+ * An MP4 (ISO BMFF) read from its boxes: `ftyp` first, then `moov` (anywhere — ffmpeg writes it
+ * after `mdat` unless told to fast-start) holding `mvhd` (timescale + duration) and one `trak` per
+ * stream whose `tkhd` carries the presented width/height (16.16 fixed point); the video track is
+ * the one with a non-zero size. Nothing is decoded — the codec is the browser's business.
+ */
+export declare function sniffVideo(bytes: Uint8Array): VideoInfo | undefined;
+/**
+ * The video's preview image. X's is a frame its transcoder cut; the twin decodes nothing (the codec
+ * is the browser's), so it serves a STAND-IN at the video's own size and aspect — a dark frame with
+ * X's play glyph — and says so here. `x.media.video_poster_frame` is the todo for a real frame.
+ */
+export declare function videoPosterSvg(width: number, height: number): string;
+/** The file extension pbs.twimg.com serves an image under. */
+export declare function mediaExtension(mediaType: string): string;