@volter/twin-tiktok 0.1.0

package/src/tiktok-connector.ts

@@ -0,0 +1,637 @@
+// TikTok CONNECTOR — the live-vendor pull path.
+//
+// PULL (real -> twin): the twin's persona registry is only as useful as the identities in it, and
+// Login Kit exposes exactly two authenticated reads a user token can perform: `GET /v2/user/info/`
+// and the Display API's video reads. A pull observes the real account behind the operator's own
+// user access token and, on request, that account's public videos, and folds them into the
+// observed log.
+//
+// SCOPES DECIDE WHAT A PULL CAN SEE, and that is a fact about this vendor rather than a bug to
+// paper over:
+//   • `/v2/user/info/` fields are gated per scope (basic / profile / stats), so a token that holds
+//     only `user.info.basic` cannot observe `username` or `follower_count`. The default pull asks
+//     for EVERY modelled field — a default-field pull would silently observe a bald persona — and
+//     a token with fewer scopes must NARROW `userFields` explicitly. A `scope_not_authorized`
+//     refusal THROWS; it is never read as "the account has no username".
+//   • the video reads need `video.list`, which the common Login Kit integration (Dub's included)
+//     does not request. So `videos` is OPT-IN: a refused read must never fold an empty video list
+//     over observed state, and silently skipping it would make "no videos" ambiguous.
+//
+// WHAT A PULL CANNOT OBSERVE, recorded as reasoned gaps rather than faked:
+//   • the DEVELOPER APP registry — TikTok apps are created in the developer portal; no API reads
+//     them (`tiktok.connector.pull_clients`, todo);
+//   • the GRANT (which scopes this token holds) — TikTok publishes no token-introspection
+//     endpoint, so the granted set cannot be enumerated; a successful user/info read evidences the
+//     scopes of the fields it returned and nothing more (`tiktok.connector.pull_grants`, todo).
+//
+// PUSH of the identity surface is an honest gap, not an omission: TikTok exposes NO write API for apps,
+// users or grants — apps live in the developer portal, and a user's app permissions are managed in
+// TikTok's own settings. `pushPendingTikTokActions` reports that; filed as `tiktok.connector.push`
+// (todo). A World's POSTS are the exception, and they cross through the kernel's perform: the
+// Content Posting API is TikTok's own write door for a new video (PERFORM, below).
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO
+// TikTok credential and import NO network client. Offline/tests pass a fake executor; live runs
+// pass `liveTikTokExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, deployableEntries, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { TikTokBudget, TikTokBudgetError, tiktokBudgetPath, tiktokCallWeight, type TikTokBudgetOptions } from './tiktok-budget.ts';
+import { clearPerformPublish, readPerformPublish, readTikTokBlobRange, tikTokBlobSize, writePerformPublish } from './tiktok-blobs.ts';
+import { USER_FIELDS, VIDEO_FIELDS } from './tiktok-user.ts';
+
+const SERVICE = 'tiktok';
+
+/** TikTok's real API host — the live executor's routing table. ONLY mapped paths may be called
+ *  live. The token/revoke paths are mapped so a live rehearsal can refresh or revoke the
+ *  operator's OWN token through the guarded path; nothing else on open.tiktokapis.com is
+ *  reachable, which is what keeps an unmodelled surface from being poked by accident (D8). */
+const HOSTS: Record<string, string> = {
+  '/v2/user/info': 'https://open.tiktokapis.com',
+  '/v2/video/list': 'https://open.tiktokapis.com',
+  '/v2/video/query': 'https://open.tiktokapis.com',
+  '/v2/oauth/token': 'https://open.tiktokapis.com',
+  '/v2/oauth/revoke': 'https://open.tiktokapis.com',
+};
+
+/** Every modelled user field a pull requests by default — narrow it for a narrower token. */
+export const PULL_USER_FIELDS: readonly string[] = USER_FIELDS;
+/** Every modelled video field a pull requests when `videos` is enabled. */
+export const PULL_VIDEO_FIELDS: readonly string[] = VIDEO_FIELDS;
+
+/**
+ * The injected real-TikTok boundary. `execute` issues ONE request and returns the parsed JSON
+ * body. A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type TikTokExecute = (
+  method: 'GET' | 'POST',
+  path: string,
+  init?: { headers?: Record<string, string>; body?: string },
+) => Promise<Record<string, any>>;
+
+export type LiveTikTokOptions = {
+  /** 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?: TikTokBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: TikTokBudgetOptions;
+};
+
+/**
+ * A live executor against the real TikTok open API, holding the operator's OWN user access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live TikTok 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 TikTok. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client
+ * (`assertBudgetGuardIntact`).
+ */
+export function liveTikTokExecute(accessToken: string, opts: LiveTikTokOptions = {}): TikTokExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, TikTokBudget, 'liveTikTokExecute')
+    : new TikTokBudget({ ...(opts.budgetOptions ?? {}), token: accessToken });
+  const explicitLedger = opts.budgetOptions?.path !== undefined || opts.budgetOptions?.root !== undefined;
+  if (opts.budget && !explicitLedger && budget.path !== tiktokBudgetPath({ token: accessToken })) {
+    throw new Error('liveTikTokExecute: injected budget is not keyed to the credential this client will send');
+  }
+  return async (method, path, init) => {
+    // TikTok writes every documented path WITH a trailing slash; the routing table and the price
+    // rules are keyed on the bare form, so both spellings resolve to one entry.
+    const bare = (path.split('?')[0] ?? path).replace(/\/+$/, '');
+    const host = HOSTS[bare];
+    if (!host) throw new Error(`liveTikTokExecute: refusing to call an unmapped TikTok path: ${bare}`);
+    const weight = tiktokCallWeight(method, path);
+    if (Object.keys(init?.headers ?? {}).some((name) => name.toLowerCase() === 'authorization')) {
+      throw new Error('liveTikTokExecute: 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: { ...(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 the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer TikTok ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof TikTokBudgetError) || !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(`tiktok returned non-JSON for ${method} ${bare}: HTTP ${res.status}`);
+    }
+    // A REFUSED pull is NOT an empty account. TikTok answers a Display API failure with a NESTED
+    // error object whose `code` is something other than `ok` — and it carries that object on
+    // SUCCESS too, so a status check alone cannot tell refusal from genuine emptiness. Both
+    // shapes throw.
+    if (res.status >= 400) throw new Error(`tiktok refused ${method} ${bare}: HTTP ${res.status} ${JSON.stringify(parsed)}`);
+    const code = (parsed?.['error'] as Record<string, unknown> | undefined)?.['code'];
+    if (typeof code === 'string' && code !== 'ok') {
+      throw new Error(`tiktok refused ${method} ${bare}: ${JSON.stringify(parsed['error'])}`);
+    }
+    // The OAuth endpoints use the FLAT envelope instead — a string `error` field is a refusal.
+    if (typeof parsed?.['error'] === 'string') {
+      throw new Error(`tiktok refused ${method} ${bare}: ${JSON.stringify(parsed)}`);
+    }
+    return parsed;
+  };
+}
+
+/**
+ * Map a real `GET /v2/user/info/` response -> the account (persona) SyncResource.
+ *
+ * NOTHING IS INVENTED: a field the response omits records NOTHING rather than a placeholder —
+ * including username and display_name, because a scope-narrowed token legitimately omits them and
+ * a `?? null` there would fold null over a previously pulled persona's real values.
+ *
+ * The subject id is `union_id`, the vendor's own cross-app user key — NOT `open_id`, which is
+ * per-app and would give one human as many twin accounts as they have authorized apps.
+ */
+export function mapUserInfoAccount(body: Record<string, any>): SyncResource {
+  const user = (body?.data?.user ?? {}) as Record<string, any>;
+  const str = (key: string, field: string) => (typeof user[key] === 'string' ? { [field]: user[key] } : {});
+  const num = (key: string, field: string) => (typeof user[key] === 'number' ? { [field]: user[key] } : {});
+  return {
+    type: 'account',
+    id: String(user['union_id'] ?? ''),
+    fields: {
+      ...str('username', 'username'),
+      ...str('display_name', 'displayName'),
+      ...str('avatar_url', 'avatarUrl'),
+      ...str('avatar_url_100', 'avatarUrl100'),
+      ...str('avatar_large_url', 'avatarLargeUrl'),
+      ...str('bio_description', 'bioDescription'),
+      ...str('profile_deep_link', 'profileDeepLink'),
+      ...(typeof user['is_verified'] === 'boolean' ? { isVerified: user['is_verified'] } : {}),
+      ...num('follower_count', 'followerCount'),
+      ...num('following_count', 'followingCount'),
+      ...num('likes_count', 'likesCount'),
+      ...num('video_count', 'videoCount'),
+      pulled: true,
+    },
+  };
+}
+
+/** Map one real Video object -> the video SyncResource, owned by the pulled account. */
+export function mapVideo(video: Record<string, any>, ownerUnionId: string): SyncResource {
+  const num = (key: string, field: string) => (typeof video[key] === 'number' ? { [field]: video[key] } : {});
+  return {
+    type: 'video',
+    id: String(video['id'] ?? ''),
+    fields: {
+      ownerUnionId,
+      ...(typeof video['title'] === 'string' ? { title: video['title'] } : {}),
+      ...(typeof video['video_description'] === 'string' ? { videoDescription: video['video_description'] } : {}),
+      ...num('create_time', 'createTime'),
+      ...num('duration', 'duration'),
+      ...num('height', 'height'),
+      ...num('width', 'width'),
+      ...num('like_count', 'likeCount'),
+      ...num('comment_count', 'commentCount'),
+      ...num('share_count', 'shareCount'),
+      ...num('view_count', 'viewCount'),
+      ...(typeof video['is_aigc'] === 'boolean' ? { isAigc: video['is_aigc'] } : {}),
+      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();
+}
+
+export type PullOptions = {
+  root?: string;
+  occurredAt?: string;
+  /** Narrow the `user.fields` a pull asks for — required when the token holds fewer scopes than
+   *  the three `user.info.*` ones (an unauthorized field is a refusal, not an empty value). */
+  userFields?: readonly string[];
+  /** Also pull the account's videos. OFF by default: the Display API video reads need the separate
+   *  `video.list` scope, and a refused read must never fold an empty list over observed state. */
+  videos?: boolean;
+  /** How many videos to ask for in one page (TikTok's own maximum is 20). */
+  videoCount?: number;
+};
+
+async function collectTikTok(execute: TikTokExecute, opts: PullOptions): Promise<SyncResource[]> {
+  const fields = (opts.userFields ?? PULL_USER_FIELDS).join(',');
+  const body = await execute('GET', `/v2/user/info/?fields=${fields}`);
+  // The refusal check lives HERE, not only in the live executor: an injected executor (or a vendor
+  // 200 carrying a non-ok error object) must never fold an empty account over observed state. A
+  // reply with no `data.user.union_id` is a refusal or a malformed body, and either one THROWS.
+  const unionId = (body as Record<string, any> | null)?.['data']?.['user']?.['union_id'];
+  if (!body || typeof body !== 'object' || typeof unionId !== 'string' || unionId === '') {
+    throw new Error(`tiktok pull refused or malformed: ${JSON.stringify(body).slice(0, 200)}`);
+  }
+  const out: SyncResource[] = [mapUserInfoAccount(body)];
+  if (opts.videos === true) {
+    const count = opts.videoCount ?? 20;
+    const listed = await execute(
+      'POST',
+      `/v2/video/list/?fields=${PULL_VIDEO_FIELDS.join(',')}`,
+      { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ max_count: count }) },
+    );
+    const videos = (listed as Record<string, any> | null)?.['data']?.['videos'];
+    if (!Array.isArray(videos)) {
+      throw new Error(`tiktok video pull refused or malformed: ${JSON.stringify(listed).slice(0, 200)}`);
+    }
+    for (const video of videos as Array<Record<string, any>>) {
+      if (typeof video?.['id'] === 'string' && video['id'] !== '') out.push(mapVideo(video, unionId));
+    }
+  }
+  return out;
+}
+
+/** PULL the operator's own identity (and optionally their videos) into the observed log. */
+export async function pullTikTok(execute: TikTokExecute, opts: PullOptions = {}): Promise<number> {
+  const resources = await collectTikTok(execute, opts);
+  const at = opts.occurredAt ?? pollTimestamp();
+  observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:${SERVICE}:${at}` });
+  return resources.length;
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real TikTok surface and
+ * fold it into the twin in ONE observation, returning the standard `{ observed, deltasAppended }`.
+ * Idempotent — a re-pull of identical state appends nothing.
+ */
+export async function syncTikTokFromReal(
+  execute: TikTokExecute,
+  opts: PullOptions = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const at = opts.occurredAt ?? pollTimestamp();
+  const resources = await collectTikTok(execute, opts);
+  const result = observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:${SERVICE}:${at}` });
+  return { observed: resources.length, deltasAppended: result.appended };
+}
+
+/**
+ * PUSH without a kernel executor — reported, never faked. TikTok has no API that creates a
+ * developer app, seeds a user, grants a scope, or edits a published video: those are developer-portal
+ * and in-app actions. A World's new posts DO have a door (the Content Posting API), and they cross
+ * through the kernel's deploy (`performTikTokAction`), which holds the sealed credential this
+ * function never does. This never confirms an action and never pretends to have pushed one; it
+ * returns the pending count so a caller can see exactly how much local state is waiting.
+ */
+export function pushPendingTikTokActions(root?: string): { pushed: 0; unpushable: number } {
+  return { pushed: 0, unpushable: deployableEntries(SERVICE, root).length };
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+
+/** A `TikTokExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function tiktokExecuteOver(execute: RemoteExecute): TikTokExecute {
+  return async (method, path, init) => {
+    const res = await execute({
+      method,
+      path,
+      headers: { accept: 'application/json', authorization: 'Bearer twin', ...(init?.headers ?? {}) },
+      ...(init?.body === undefined ? {} : { body: init.body }),
+    });
+    try { return JSON.parse(res.body || '{}'); } catch { return {}; }
+  };
+}
+
+/**
+ * The refresh adapter (protocol 2): `GET /v2/user/info/` is a real read of the real account, so the
+ * operator's own identity comes back from TikTok itself. It is also nearly the only thing this
+ * vendor lets a client read about its own identity surface — apps, grants and scopes are portal
+ * state.
+ *
+ * ── WHY THIS ONE DOES NOT THROW, AND THE PULL ABOVE STILL DOES ──────────────────────────────────
+ * Two entry points, two callers, two correct behaviours — and the difference is deliberate rather
+ * than a softened refusal:
+ *
+ *   • `pullTikTok` / `syncTikTokFromReal` are the OPERATOR's pull over an executor they built. The
+ *     credential is theirs and it is meant to work, so any refusal is a fault they must see: those
+ *     THROW on every refusal shape, and `tiktok.connector.refused_pull_throws` holds that.
+ *   • THIS adapter is driven by the kernel against whatever credential the root holds — including
+ *     none. A reply that discloses no account is then not "the vendor failed", it is "this wire
+ *     has nothing to tell us", and the honest answer is ZERO OBSERVATIONS. It is the googleoauth
+ *     remote adapter's own shape (`collectGoogleOAuthIdentity` pushes a resource only when the
+ *     reply carries one), transcribed.
+ *
+ * WHAT IS NOT WEAKENED, because this is the line the doctrine actually draws: nothing empty is ever
+ * FOLDED. `observeResources` is not called at all on this path, so no prior observation is
+ * overwritten, no subject is tombstoned, and a previously pulled persona survives byte for byte —
+ * which is the whole content of "a refused pull is not an empty account". The count comes back 0,
+ * and a caller that reads the count sees exactly that nothing was observed.
+ * `tiktok.connector.remote_refresh_folds_nothing_when_unreadable` pins both halves at once.
+ */
+export async function syncTikTokFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const at = opts.occurredAt ?? new Date().toISOString();
+  const body = await tiktokExecuteOver(execute)('GET', `/v2/user/info/?fields=${PULL_USER_FIELDS.join(',')}`);
+  const unionId = (body as Record<string, any> | null)?.['data']?.['user']?.['union_id'];
+  if (typeof unionId !== 'string' || unionId === '') return { observed: 0, deltasAppended: 0 };
+  const resources = [mapUserInfoAccount(body)];
+  const result = observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:${SERVICE}:${at}` });
+  return { observed: resources.length, deltasAppended: result.appended };
+}
+
+// ── PERFORM: a World's post crosses to TikTok through the Content Posting API ──────────────────
+//
+// A `video.publish` entry (a Direct Post the World made) crosses as the vendor's own flow, the one
+// its Direct Post guide walks: (1) creator_info — the creator the credential names, and whether the
+// entry's privacy_level is one of their options (a mismatch is refused here, before anything is
+// sent); (2) video/init with FILE_UPLOAD and the chunk plan TikTok's rules require for the stored
+// size; (3) each chunk PUT to the upload_url the vendor returned, PRESIGNED — the URL's upload_token
+// is its authorization, so the sealed credential never goes with it, and the host is the vendor's
+// upload host, not the API's; (4) status/fetch until PUBLISH_COMPLETE. A `video.inbox_upload` entry
+// crosses the same way through inbox/video/init and ends at SEND_TO_USER_INBOX. The bytes are read
+// off the blob seam by the entry's digest, a chunk at a time, across the branch's ancestors.
+//
+// THE BUDGET wraps the executor the perform receives (`budgetedTikTokExecute`, the X pack's shape),
+// with ONE LEDGER PER CREDENTIAL — keyed by `ctx.credential`, the sealed credential's keyed
+// fingerprint, so every World and branch performing with one TikTok account spends one allowance (the
+// vendor meters the token, not the World), and by `ctx.root` only when no credential is sealed (the
+// X / YouTube / LinkedIn keying): creator_info, the init and every status read
+// are charged before they go and refused without calling TikTok when the ledger says stop; an answer
+// that has arrived is never dropped. The chunk PUTs are NOT charged: once a publish has started, the
+// budget cannot stop it — a half-sent video would be worse than a spent minute.
+//
+// THE BOUND. TikTok publishes no processing time and no polling interval, only status/fetch's 30 reads
+// a minute per token; the wait reads every STATUS_POLL_MS (3 s: twenty a minute, which leaves the
+// ledger room for the creator_info and init beside them) and stops at MAX_PUBLISH_WAIT_MS (120 s).
+// Past that the perform fails RETRYABLY, and the publish it opened is KEPT (tiktok-blobs.ts
+// perform-publishes): a Direct Post publishes itself once its bytes are in, so the next deploy asks
+// that publish where it stands rather than initializing a second post, and resumes its missing chunks
+// on the upload_url it kept. Only a publish TikTok says is gone — `invalid_publish_id`, or FAILED —
+// is cleared, so the next perform opens a fresh one. A chunk TikTok does not take fails the perform
+// retryably with the publish still kept. A 429 or a 5xx
+// from status/fetch is TikTok saying "later", so the wait keeps reading inside its bound and ends
+// RETRYABLY, never as a permanent failure.
+
+/** How often the perform reads status/fetch while TikTok processes (see THE BOUND above). */
+export const STATUS_POLL_MS = 3_000;
+/** How long, in total, a perform waits on TikTok's processing before it fails the entry retryably. */
+export const MAX_PUBLISH_WAIT_MS = 120_000;
+/** The chunk the perform sends: TikTok's 5 MB minimum (read as MiB), so a 4 GB video is 800 chunks. */
+export const PERFORM_CHUNK_BYTES = 5 * 1024 * 1024;
+
+/** TikTok answered "later" (429, a 5xx) — the entry stays deployable and the next deploy tries again. */
+export class TikTokRetryableError extends Error {
+  readonly retryable = true;
+  constructor(message: string) {
+    super(message);
+    this.name = 'TikTokRetryableError';
+  }
+}
+
+/** TikTok has the video but has not finished processing it inside the bound: retry later. */
+export class TikTokStillProcessingError extends TikTokRetryableError {
+  constructor(readonly publishId: string, waitedMs: number, reads: number) {
+    super(`video still processing at TikTok (publish ${publishId}) after ${Math.round(waitedMs / 1000)}s and ${reads} status reads — the entry stays pending; the next deploy asks this publish where it stands`);
+    this.name = 'TikTokStillProcessingError';
+  }
+}
+
+/**
+ * The kernel executor, charged to this pack's TikTokBudget: the check RESERVES before the call and
+ * throws (TikTokBudgetError) instead of calling when the ceiling or a cooldown says stop; the answer
+ * settles the reservation and arms a cooldown on 429 / Retry-After. The vendor has ANSWERED by then:
+ * if recording throws (a back-off past the cap, persisted first), the answer still goes back and the
+ * next call meets the cooldown — dropping it would record a post TikTok accepted as failed.
+ */
+export function budgetedTikTokExecute(execute: RemoteExecute, budget: TikTokBudget = new TikTokBudget()): RemoteExecute {
+  const guard = assertBudgetGuardIntact(budget, TikTokBudget, 'budgetedTikTokExecute');
+  return async (request) => {
+    const weight = tiktokCallWeight(request.method, request.path);
+    const reservation = guard.checkBudget(weight);
+    const res = await execute(request);
+    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 TikTokBudgetError)) throw error;
+    }
+    return res;
+  };
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** One Content Posting call: its `data`, or a throw carrying the vendor's refusal. */
+async function postingCall(execute: RemoteExecute, label: string, path: string, body: unknown): Promise<{ data: Record<string, any>; raw: string }> {
+  const res = await execute({ method: 'POST', path, headers: { accept: 'application/json', 'content-type': 'application/json; charset=UTF-8' }, body: JSON.stringify(body) });
+  let parsed: Record<string, any> = {};
+  try { parsed = res.body ? JSON.parse(res.body) : {}; } catch { throw new Error(`tiktok answered ${label} with a body that is not JSON: HTTP ${res.status} ${res.body.slice(0, 200)}`); }
+  const code = parsed?.error?.code;
+  // TikTok saying "later" is not a refusal of the post
+  if (res.status === 429 || res.status >= 500) throw new TikTokRetryableError(`tiktok answered ${label} with HTTP ${res.status} (${String(code ?? 'no code')}) — retry later`);
+  if (res.status < 200 || res.status >= 300 || (typeof code === 'string' && code !== 'ok')) {
+    throw new TikTokRefusal(label, res.status, typeof code === 'string' ? code : '', JSON.stringify(parsed?.error ?? parsed).slice(0, 300));
+  }
+  return { data: (parsed.data ?? {}) as Record<string, any>, raw: res.body };
+}
+
+/** TikTok refused a call, with its own `error.code`. */
+class TikTokRefusal extends Error {
+  constructor(label: string, readonly status: number, readonly code: string, detail: string) {
+    super(`tiktok refused ${label}: HTTP ${status} ${detail}`);
+    this.name = 'TikTokRefusal';
+  }
+}
+
+/** A budget refusal is a wait while the bound has room; past it, the caller's verdict. */
+async function withinBudget<T>(deadline: number, call: () => Promise<T>): Promise<T> {
+  for (;;) {
+    try {
+      return await call();
+    } catch (error) {
+      // only a window that will open again is a wait: ceiling, burst, a cooldown the vendor asked for
+      if (!(error instanceof TikTokBudgetError) || !['ceiling', 'burst', 'cooldown'].includes(error.kind)) throw error;
+      if (Date.now() + error.retryAfterMs > deadline) throw error;
+      await sleep(error.retryAfterMs);
+    }
+  }
+}
+
+/** The chunk plan TikTok's rules require for `size` bytes at the perform's chunk size. */
+export function performChunkPlan(size: number): { chunkSize: number; totalChunkCount: number } {
+  if (size < PERFORM_CHUNK_BYTES) return { chunkSize: size, totalChunkCount: 1 };
+  return { chunkSize: PERFORM_CHUNK_BYTES, totalChunkCount: Math.floor(size / PERFORM_CHUNK_BYTES) };
+}
+
+type StatusRead = { status: string; failReason?: string; postId?: string; uploadedBytes: number };
+
+/** status/fetch, with `publicaly_available_post_id` read off the RAW body: it is a list of int64 JSON
+ *  numbers, and JSON.parse would round a 19-digit id to the nearest double. */
+async function readStatus(execute: RemoteExecute, publishId: string): Promise<StatusRead> {
+  const { data, raw } = await postingCall(execute, 'status/fetch', '/v2/post/publish/status/fetch/', { publish_id: publishId });
+  const ids = /"publicaly_available_post_id"\s*:\s*\[\s*"?(\d+)/.exec(raw);
+  return {
+    status: String(data.status ?? ''),
+    ...(typeof data.fail_reason === 'string' && data.fail_reason ? { failReason: data.fail_reason } : {}),
+    ...(ids ? { postId: ids[1] } : {}),
+    uploadedBytes: Number(data.uploaded_bytes ?? 0),
+  };
+}
+
+async function publishOver(budgeted: RemoteExecute, raw: RemoteExecute, action: TwinAction, mode: 'direct' | 'inbox', root?: string): Promise<PushOutcome> {
+  const f = (action.fields ?? {}) as Record<string, any>;
+  const sha = f._content_sha256;
+  const size = await tikTokBlobSize(sha, root);
+  if (size === null) throw new Error(`tiktok: ${action.operation} ${action.subject.id} has no stored media to post (_content_sha256 ${String(sha ?? 'absent')})`);
+  const contentType = typeof f._content_type === 'string' ? f._content_type : 'video/mp4';
+  const started = Date.now();
+  const deadline = started + MAX_PUBLISH_WAIT_MS;
+  const done = mode === 'direct' ? 'PUBLISH_COMPLETE' : 'SEND_TO_USER_INBOX';
+
+  // (0) a publish an earlier perform of this entry opened: where does it stand? It is re-opened ONLY
+  // when TikTok says it is gone — `invalid_publish_id`, or status FAILED ("an error has occurred and
+  // the entire process has failed"). Anything else is the same publish, still alive: PROCESSING_UPLOAD
+  // is "the upload is in process", and `uploaded_bytes` is "the number of bytes uploaded (1-indexed)
+  // for FILE_UPLOAD" (Get Post Status reference) — a count of what arrived, which says nothing about
+  // whether TikTok will still post it. So a partial count is where this perform resumes the SAME
+  // publish's chunks, on the upload_url it kept; a second init could put the video up twice.
+  let kept = await readPerformPublish(action.id, root);
+  if (kept && (kept.sha256 !== sha || kept.size !== size)) kept = null;
+  let offset = 0;
+  if (kept) {
+    let state: StatusRead | null = null;
+    try {
+      state = await withinBudget(deadline, () => readStatus(budgeted, kept!.publishId));
+    } catch (error) {
+      if (!(error instanceof TikTokRefusal) || error.code !== 'invalid_publish_id') throw error;
+    }
+    if (state === null || state.status === 'FAILED') { await clearPerformPublish(action.id, root); kept = null; }
+    else offset = state.status === 'PROCESSING_UPLOAD' ? state.uploadedBytes : size;
+  }
+
+  // (1) + (2) the creator and the init — the only calls charged before a publish exists
+  if (!kept) {
+    if (mode === 'direct') {
+      const creator = await withinBudget(deadline, () => postingCall(budgeted, 'creator_info', '/v2/post/publish/creator_info/query/', {}));
+      const options: unknown[] = Array.isArray(creator.data.privacy_level_options) ? creator.data.privacy_level_options : [];
+      if (!options.includes(f.privacyLevel)) {
+        throw new Error(`tiktok: the creator @${String(creator.data.creator_username ?? '?')} cannot post as ${String(f.privacyLevel)} (their options: ${options.join(', ')})`);
+      }
+    }
+    const plan = performChunkPlan(size);
+    const postInfo = {
+      title: String(f.videoDescription ?? f.title ?? ''),
+      privacy_level: f.privacyLevel,
+      disable_duet: f.disableDuet === true,
+      disable_comment: f.disableComment === true,
+      disable_stitch: f.disableStitch === true,
+      ...(typeof f.videoCoverTimestampMs === 'number' ? { video_cover_timestamp_ms: f.videoCoverTimestampMs } : {}),
+      ...(f.brandContentToggle === true ? { brand_content_toggle: true } : {}),
+      ...(f.brandOrganicToggle === true ? { brand_organic_toggle: true } : {}),
+      ...(f.isAigc === true ? { is_aigc: true } : {}),
+    };
+    const init = await withinBudget(deadline, () => postingCall(
+      budgeted,
+      mode === 'direct' ? 'video/init' : 'inbox/video/init',
+      mode === 'direct' ? '/v2/post/publish/video/init/' : '/v2/post/publish/inbox/video/init/',
+      {
+        ...(mode === 'direct' ? { post_info: postInfo } : {}),
+        source_info: { source: 'FILE_UPLOAD', video_size: size, chunk_size: plan.chunkSize, total_chunk_count: plan.totalChunkCount },
+      },
+    ));
+    const publishId = init.data.publish_id;
+    if (typeof publishId !== 'string' || typeof init.data.upload_url !== 'string') throw new Error(`tiktok init answered no publish_id/upload_url: ${init.raw.slice(0, 200)}`);
+    kept = { publishId, uploadUrl: init.data.upload_url, sha256: String(sha), size, ...plan };
+    await writePerformPublish(action.id, kept, root);
+    offset = 0;
+  }
+  const publish = kept;
+
+  // (3) the chunks still missing, in order, presigned, unbudgeted. A PUT TikTok does not take leaves
+  // the publish kept and fails RETRYABLY: the next perform asks status/fetch where it stands.
+  for (let index = Math.floor(offset / publish.chunkSize); offset < size && index < publish.totalChunkCount; index += 1) {
+    const first = index * publish.chunkSize;
+    const last = index === publish.totalChunkCount - 1 ? size - 1 : first + publish.chunkSize - 1;
+    const chunk = (await readTikTokBlobRange(sha, first, last, root)) ?? new Uint8Array(0);
+    const answer = await raw({
+      method: 'PUT',
+      path: publish.uploadUrl,
+      presigned: true,
+      headers: { 'content-type': contentType, 'content-length': String(chunk.length), 'content-range': `bytes ${first}-${last}/${size}` },
+      body: chunk,
+    });
+    if (answer.status === 206 || answer.status === 201) continue;
+    throw new TikTokRetryableError(`tiktok: chunk ${index + 1}/${publish.totalChunkCount} of publish ${publish.publishId} answered HTTP ${answer.status} — the publish is kept; the next deploy asks it where it stands: ${answer.body.slice(0, 200)}`);
+  }
+
+  // (4) the wait, bounded; "later" answers keep it waiting
+  let reads = 0;
+  for (;;) {
+    let state: StatusRead | null = null;
+    try {
+      state = await withinBudget(deadline, () => readStatus(budgeted, publish.publishId));
+      reads += 1;
+    } catch (error) {
+      if (error instanceof TikTokBudgetError) throw new TikTokStillProcessingError(publish.publishId, Date.now() - started, reads);
+      if (!(error instanceof TikTokRetryableError)) throw error;
+    }
+    if (state?.status === done) {
+      await clearPerformPublish(action.id, root);
+      const postId = state.postId;
+      return {
+        externalId: postId ?? publish.publishId,
+        ...(postId ? { url: `https://www.tiktok.com/video/${postId}` } : {}),
+        data: { publish_id: publish.publishId, status: state.status, ...(postId ? { post_id: postId } : {}) },
+      };
+    }
+    if (state?.status === 'FAILED') {
+      await clearPerformPublish(action.id, root);
+      throw new Error(`tiktok failed publish ${publish.publishId}: ${state.failReason ?? 'no fail_reason'}`);
+    }
+    if (Date.now() + STATUS_POLL_MS > deadline) throw new TikTokStillProcessingError(publish.publishId, Date.now() - started, reads);
+    await sleep(STATUS_POLL_MS);
+  }
+}
+
+/**
+ * The perform adapter (protocol 2).
+ *
+ * A World's post crosses (`video.publish`, `video.inbox_upload`: see PERFORM above). Everything else a
+ * World writes here has no upstream home, and saying so is the point: TikTok publishes NO API that
+ * creates a developer app, seeds a user, grants a scope or issues a token — those are developer-portal
+ * and in-app settings actions a person takes in a browser — and an upload whose file failed TikTok's
+ * checks here (`publish.fail`) has nothing to send.
+ */
+export async function performTikTokAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext, budget?: TikTokBudget): Promise<PushOutcome> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  if (op === 'video.publish' || op === 'video.inbox_upload') {
+    // ONE LEDGER PER CREDENTIAL (its keyed fingerprint), else per World root when none is sealed;
+    // `budget` is injectable so a verify charges a temporary ledger of its own
+    const budgeted = budgetedTikTokExecute(execute, budget ?? new TikTokBudget(ctx.credential !== undefined ? { token: ctx.credential } : ctx.root !== undefined ? { root: ctx.root } : {}));
+    return publishOver(budgeted, execute, action, op === 'video.publish' ? 'direct' : 'inbox', ctx.root);
+  }
+  return {
+    externalId: action.subject.id,
+    data: {
+      performed: false,
+      reason: op === 'publish.fail'
+        ? `${op}: the upload failed TikTok's checks on this twin (${String((action.fields ?? {}).failReason ?? 'unknown')}), so there is no post to send`
+        : `${op} has nowhere to go: TikTok creates developer apps, users, tokens and scope grants in the developer portal and in TikTok's own account settings, and publishes no API for any of them`,
+    },
+  };
+}