@volter/twin-tiktok 0.1.0

package/dist/src/index.js

@@ -0,0 +1,167 @@
+// @volter/twin-tiktok — the TikTok twin (one vendor, one package), built on the shared
+// @volter/world-core kernel.
+//
+// A BROWSER-FACING protocol pack (the googleoauth class): it serves TikTok's own authorization
+// page as HTML at www.tiktok.com's real path, completes the full Login Kit authorization-code
+// round trip (consent -> 302 with code+scopes+state -> redemption at the token endpoint -> refresh
+// -> revoke), and answers the Display API's `/v2/user/info/`, `/v2/video/list/` and
+// `/v2/video/query/` reads with TikTok's real field-selection, scope-gating and error envelopes, and
+// posts a creator's video through the Content Posting API (creator_info, the Direct Post and inbox
+// inits, the chunked upload to a signed upload URL, status/fetch) with the bytes on the blob seam, a
+// tiktok.com-style mirror over that state, and a perform that sends a World's post to TikTok.
+// Deliberately NON-OIDC, exactly as the vendor is: opaque `act.`/`rft.` tokens, no id_token, no
+// JWKS — identity comes from the Display API, and `open_id` is per-app while `union_id` is
+// per-human. Conformance tooling lives in @volter/world-tooling (a dev dependency), not here.
+import { registerPack } from '@volter/world-core';
+export { ACCESS_TOKEN_TTL_SECONDS, API_ORIGIN, AUTH_CODE_TTL_SECONDS, AUTHORIZE_ORIGIN, CLIENT_TOKEN_TTL_SECONDS, handleTikTokTwinRequest, METERED_ENDPOINTS, RATE_LIMIT_PER_WINDOW, RATE_LIMITS, RATE_WINDOW_SECONDS, REFRESH_TOKEN_TTL_SECONDS, RESOURCE_TYPES, tiktokTwinSnapshot, USER_FIELDS, VIDEO_FIELDS, VIDEO_LIST_DEFAULT_COUNT, VIDEO_LIST_MAX_COUNT, VIDEO_QUERY_MAX_IDS, } from "./tiktok-twin.js";
+export { createTikTokConsentServer, createTikTokTwinFetch, createTikTokTwinServer } from "./tiktok-server.js";
+export { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_KEY, DEFAULT_CLIENT_SECRET, DEFAULT_VIDEOS, defaultRedirectUris, openIdFor, redirectUriAllowed, sessionAccount, } from "./tiktok-store.js";
+export { CHALLENGE_METHOD, isSupportedChallengeMethod, isWellFormedVerifier, pkceVerifies, rfc7636Challenge, tiktokCodeChallenge } from "./tiktok-pkce.js";
+export { describeScope, describeScopes, formatScopeParam, KNOWN_SCOPES, parseScopeParam, SCOPE_CATALOG, sortScopesForConsent, } from "./tiktok-scopes.js";
+export { API_ERRORS, OAUTH_ERRORS } from "./tiktok-errors.js";
+export { logId } from "./tiktok-ids.js";
+export { renderUser, renderVideo, USER_FIELD_SCOPES, USER_INFO_SCOPES, VIDEO_SCOPE } from "./tiktok-user.js";
+export { liveTikTokExecute, mapUserInfoAccount, mapVideo, performTikTokAction, PULL_USER_FIELDS, PULL_VIDEO_FIELDS, pullTikTok, pushPendingTikTokActions, syncTikTokFromReal, syncTikTokFromRemote, tiktokExecuteOver, } from "./tiktok-connector.js";
+export { budgetedTikTokExecute, MAX_PUBLISH_WAIT_MS, TikTokRetryableError, PERFORM_CHUNK_BYTES, performChunkPlan, STATUS_POLL_MS, TikTokStillProcessingError, } from "./tiktok-connector.js";
+export { checkChunkPlan, chunkLength, creatorOptions, DEFAULT_MAX_VIDEO_POST_DURATION_SEC, MAX_CHUNK_BYTES, MAX_CHUNK_COUNT, MAX_FINAL_CHUNK_BYTES, MAX_SERVED_RANGE, MAX_VIDEO_BYTES, MEDIA_PREFIX, MIN_CHUNK_BYTES, PRIVACY_LEVELS, processingMs, UPLOAD_ORIGIN, UPLOAD_PATH, UPLOAD_URL_TTL_MS, } from "./tiktok-posting.js";
+export { POSTING_ERRORS } from "./tiktok-errors.js";
+// The client-side rate budget — the fail-closed backstop `liveTikTokExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is this vendor's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `TikTokBudgetError` by type; there is deliberately no export that disables the guard.
+export { TIKTOK_BUDGET_BURST_CEILING, TIKTOK_BUDGET_CEILING, TIKTOK_BUDGET_MAX_RETRY_AFTER_S, TIKTOK_BUDGET_WINDOW_MS, TIKTOK_CALL_WEIGHTS, TIKTOK_RATE_BUDGET, TikTokBudget, TikTokBudgetError, tiktokBudgetPath, tiktokCallWeight, } from "./tiktok-budget.js";
+export { CONSENT_CSS, consentPageHtml, errorPageHtml, tiktokConsentState } from "./tiktok-consent-ui.js";
+// The tiktok.com mirror (profile, grid, vertical player): its pure helpers and its server. The hosted
+// mirror mount reads tiktok-mirror-ui.ts directly (`tiktokMirrorHtml`, `buildTiktokMirrorClient`,
+// `tiktokMirrorStyles`).
+export { captionOf, captionSegments, compactCount, createTiktokMirrorServer, mediaSource, profileStats } from "./tiktok-mirror-ui.js";
+import { TIKTOK_RATE_BUDGET as RATE_BUDGET } from "./tiktok-budget.js";
+import { performTikTokAction, syncTikTokFromRemote } from "./tiktok-connector.js";
+/**
+ * The www.tiktok.com paths THIS pack serves — the Login Kit authorization leg — as a RegExp SOURCE
+ * for the descriptor's `hosts` path rule. www.tiktok.com is NOT an API host: it is the whole
+ * TikTok web property (the For You feed, profiles, settings, everything). Claiming the host
+ * outright would be the Cal.com mis-route incident with the largest possible blast radius, so this
+ * claims EXACTLY the authorize path plus the twin-only prefix. ANCHORED, the googleoauth lesson:
+ * an unanchored claim swallows `/v2/auth/authorize2` and friends. The optional trailing slash is
+ * load-bearing — TikTok's own documentation writes `/v2/auth/authorize/` while Dub's URL builder
+ * omits it, and both must route here.
+ */
+const TIKTOK_AUTHORIZE_PATHS = '^/v2/auth/authorize/?$|^/_twin/';
+/**
+ * The open.tiktokapis.com paths THIS pack serves: the OAuth token/revoke endpoints, the Display
+ * API's user and video reads and the Content Posting API's four calls. open.tiktokapis.com is the
+ * ENTIRE TikTok open platform host — Research, Data Portability, Commercial Content, Business and
+ * the photo post besides — and nothing this pack does not model is claimed: an unmodelled TikTok
+ * call must refuse loudly rather than land in a twin that cannot serve it.
+ */
+const TIKTOK_API_PATHS = '^/v2/(?:oauth/(?:token|revoke)|user/info|video/(?:list|query)|post/publish/(?:creator_info/query|video/init|inbox/video/init|status/fetch))/?$|^/_twin/';
+/**
+ * The upload host's path: the Content Posting API's upload_url is `https://open-upload.tiktokapis.com/
+ * video/?upload_id=…&upload_token=…` (the Direct Post and inbox references' own examples). An app in a
+ * World PUTs its chunks there, so the injector must route that host to the twin too. Nothing else on
+ * the upload host is modelled, so nothing else is claimed.
+ */
+const TIKTOK_UPLOAD_PATHS = '^/video/?$';
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+    // the real state system, registered on load. A World's POST crosses at `perform`, through the
+    // Content Posting API (creator_info, init, the presigned chunk PUTs, status/fetch); nothing else
+    // does: TikTok publishes no API that creates a developer app, seeds a user or grants a scope —
+    // those are developer-portal and in-app settings actions a person takes in a browser — so
+    // `perform` settles every other entry with that reason.
+    protocol: '2',
+    // The vendor's access token lives 24 hours and its Display API limit is 600/minute, so a served
+    // world can afford a half-hourly pull; `onDemand` throttles a hand-run refresh to one a minute,
+    // well inside that budget.
+    refresh: { every: '30m', onDemand: { atMost: '60s' } },
+    stateSystem: { perform: performTikTokAction, refresh: syncTikTokFromRemote },
+    // The round trip registers a developer app through the twin's OWN door, because the vendor has no
+    // API for it at all — which is the same reason `perform` never crosses. (The Login Kit legs
+    // cannot serve as the round trip: the consent post answers a 302 and the harness fails any step
+    // answering >=300.)
+    roundTrip: {
+        method: 'POST',
+        path: '/_twin/clients',
+        body: { client_key: 'awroundtripapp0001', client_secret: 'round-trip-secret', name: 'Round Trip', redirect_uris: ['https://round.trip.test/callback'] },
+    },
+    parityOrigin: 'http://twin',
+    // shapeParity is NOT held, and the reason is STRUCTURAL rather than a divergence to close: the
+    // refresh reads the ACCOUNT the credential names (`GET /v2/user/info/`), while the only write a
+    // blind round trip can make on this vendor is registering a developer app — which TikTok
+    // publishes no API to read back. Written and observed are different subjects by design, so there
+    // is no pair of shapes to compare. Reaching parity would need the refresh to observe an
+    // oauth_client, and no TikTok endpoint returns one.
+    vendor: 'tiktok',
+    // The SAME object tiktok-budget.ts declares at module load — one source of truth, so registering
+    // the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-tiktok',
+    resources: [
+        'oauth_client',
+        'account',
+        'session',
+        'auth_request',
+        'grant',
+        'video',
+        'publish',
+    ],
+    specSource: 'developers.tiktok.com, fetched 2026-09-13 — no first-party machine-readable spec exists for '
+        + 'the TikTok open API, so the denominator was authored top-down from the published references: '
+        + 'Login Kit for Web (the authorize URL, its parameters and the callback parameters), User '
+        + 'Access Token Management (token / refresh / revoke request + response tables and examples), '
+        + 'Client Access Token Management (the client_credentials grant), Login Kit for Desktop (PKCE: '
+        + 'hex-encoded SHA-256, S256 only), the Scopes Overview, Get User Info (the field x scope '
+        + 'table), the Video Object / Video List / Video Query references, the OAuth error-handling '
+        + 'reference (the ten flat `error` values) and the API v2 error-handling reference (the seven '
+        + 'nested `error.code` values with their HTTP statuses) and rate-limit reference (600/minute, '
+        + 'one-minute sliding window, 429 + rate_limit_exceeded); and, fetched 2026-09-27, the Content '
+        + 'Posting references (Query Creator Info, Direct Post, Upload to inbox, Get Post Status and the '
+        + 'Media Transfer Guide: chunk rules, the upload_url PUT with Content-Range, per-token minute limits).',
+    description: "TikTok twin — the real tiktok.com authorization page, the full Login Kit OAuth round trip "
+        + '(token, refresh, revoke, client_credentials) and the Display API user/video reads with '
+        + "TikTok's own comma-separated scopes, per-app open_id, field-level scope gating and both of "
+        + 'its error envelopes; and the Content Posting API — creator_info, Direct Post and inbox uploads '
+        + 'through a signed upload URL in chunks, status/fetch by World time — with a tiktok.com-style '
+        + "profile and vertical player over the posted videos, and a perform that posts a World's video "
+        + 'to TikTok.',
+    adoption: {
+        // TikTok publishes NO first-party npm client for Login Kit or the Display API: its own
+        // reference material is curl and raw fetch, which is exactly how the motivating application
+        // (Dub) calls it. The community `tiktok` package on npm is deliberately NOT claimed — it is
+        // not a TikTok-published client, and `adoption.sdks` is for official clients only (the bitly
+        // precedent). Interception is therefore host-based, which is why `hosts` below is the whole
+        // adoption story for this vendor.
+        sdks: [],
+        // No official Python distribution either. `tiktok-business-api-sdk` (PyPI and npm) is
+        // first-party but speaks the BUSINESS/Ads API on business-api.tiktok.com — a different half of
+        // the vendor that this pack does not serve, so claiming it would over-claim coverage.
+        pypi: [],
+        // TIKTOK_CLIENT_ID / TIKTOK_CLIENT_SECRET are exactly the pair Dub reads, and TIKTOK_CLIENT_KEY
+        // is the vendor's own name for the same value. The `TIKTOKBUSINESS` stem is deliberately left
+        // to the packless registry: it names the Business API this pack does not model.
+        envStems: ['TIKTOK'],
+    },
+    hosts: [
+        { host: 'www.tiktok.com', pathPattern: TIKTOK_AUTHORIZE_PATHS },
+        { host: 'open.tiktokapis.com', pathPattern: TIKTOK_API_PATHS },
+        { host: 'open-upload.tiktokapis.com', pathPattern: TIKTOK_UPLOAD_PATHS },
+    ],
+    // Dub HARDCODES both hosts — `https://open.tiktokapis.com/v2` in its TikTokClient and the
+    // authorize/token URLs in its provider table — and TikTok publishes no official SDK with a
+    // base-URL option, so there is no env var an app reads that a world could point at the twin.
+    // Inventing a TIKTOK_BASE_URL would make `covers` report the world covered while the app still
+    // talked to the real vendor; interception through the two `hosts` entries above is the whole
+    // mechanism.
+    endpointEnvNone: 'no app-read base-URL env exists: TikTok publishes no official SDK with a base-URL option and '
+        + 'integrations (Dub included) hardcode www.tiktok.com and open.tiktokapis.com, so interception '
+        + 'is the path-scoped hosts entries above.',
+    // A browser is REDIRECTED to www.tiktok.com/v2/auth/authorize — the loader host is the consent
+    // host and the prefix is the Login Kit path root.
+    browserRouting: { apiPathPrefix: '/v2/auth/', loaderHost: 'https://www.tiktok.com' },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/dist/src/tiktok-blobs.d.ts

@@ -0,0 +1,66 @@
+export interface TikTokBlobRef {
+    sha256: string;
+    size: number;
+}
+/** Store bytes content-addressed in this branch's annex; identical content is a no-op write. */
+export declare function putTikTokBlob(bytes: Uint8Array, root?: string): Promise<TikTokBlobRef>;
+/** A stored blob's size, here or at an ancestor; null when absent or the digest is malformed. */
+export declare function tikTokBlobSize(sha256: unknown, root?: string): Promise<number | null>;
+/** Bytes start..endInclusive of a stored blob, here or at an ancestor, read as a range. */
+export declare function readTikTokBlobRange(sha256: unknown, start: number, endInclusive: number, root?: string): Promise<Uint8Array | null>;
+/** What an upload remembers between its init and its final chunk. */
+export type TikTokUpload = {
+    /** The upload_id in the upload_url's query. */
+    uploadId: string;
+    /** The publish_id the init answered; status/fetch reads the upload by it until it finalizes. */
+    publishId: string;
+    /** `direct` (video.publish: Direct Post) or `inbox` (video.upload: the creator's drafts). */
+    mode: 'direct' | 'inbox';
+    /** The account and app the posting token belongs to (status/fetch answers
+     *  token_not_authorized_for_specified_publish_id to any other), and the token's SHA-256 — never the
+     *  token. */
+    accountId: string;
+    clientKey: string;
+    tokenSha256: string;
+    /** This upload's own signing secret (hex), drawn from entropy at init: the upload_token is an HMAC
+     *  under it, so no other upload's URL, and no credential, is ever the key (LinkedIn's per-asset
+     *  secret). */
+    uploadSecret: string;
+    /** The Direct Post `post_info` as the init validated it (empty for an inbox upload). */
+    postInfo: Record<string, unknown>;
+    videoSize: number;
+    chunkSize: number;
+    totalChunkCount: number;
+    /** World time (ms) the upload_url was issued and stops being valid. */
+    issuedAt: number;
+    expiresAt: number;
+    /** Set once the final chunk has landed: the digest the bytes were stored under. */
+    sha256?: string;
+};
+export declare function writeUpload(upload: TikTokUpload, root?: string): Promise<void>;
+export declare function readUpload(id: string, root?: string): Promise<TikTokUpload | null>;
+/** The upload a publish_id names, while it is staging (before its final chunk lands). */
+export declare function readUploadByPublishId(publishId: string, root?: string): Promise<TikTokUpload | null>;
+/** Bytes an upload holds so far: the contiguous run from 0. */
+export declare function stagedSize(id: string, root?: string): Promise<number>;
+/** Stage one chunk at its first byte — its own key; nothing already staged is read or rewritten. */
+export declare function stageChunk(id: string, offset: number, bytes: Uint8Array, root?: string): Promise<void>;
+/** Join an upload's chunks, once, into the video's bytes. */
+export declare function joinStaged(id: string, root?: string): Promise<Uint8Array>;
+/** Drop a finalized upload's chunks (the bytes now live content-addressed); the record stays, so a
+ *  final PUT whose answer was lost can be asked again and status/fetch still finds the publish. */
+export declare function clearStaged(id: string, root?: string): Promise<void>;
+/** The publish an entry's perform opened, and the upload_url TikTok gave it: kept only in this World's
+ *  byte annex (never an entry, never a changeset), so the next perform can resume the SAME publish's
+ *  chunks rather than open a second one. */
+export type PerformPublish = {
+    publishId: string;
+    uploadUrl: string;
+    sha256: string;
+    size: number;
+    chunkSize: number;
+    totalChunkCount: number;
+};
+export declare function readPerformPublish(actionId: string, root?: string): Promise<PerformPublish | null>;
+export declare function writePerformPublish(actionId: string, record: PerformPublish, root?: string): Promise<void>;
+export declare function clearPerformPublish(actionId: string, root?: string): Promise<void>;

package/dist/src/tiktok-blobs.js

@@ -0,0 +1,161 @@
+// Content-addressed BYTE storage for the TikTok twin — a posted video's real media.
+//
+// Transcribed from the YouTube pack's byte annex (youtube-blobs.ts), which took it from Slack's: bytes
+// ride the KERNEL'S BLOB SEAM (`getActiveBlobStore()`, runtime contract R11) — the filesystem locally,
+// object storage inside a served namespace — under this service's own `resources` dir, which
+// `scrubService('tiktok')` already owns. Keys (relative to that dir): blobs/sha256/<ab>/<hex>. The
+// kernel projection references a blob by digest only (`_content_sha256` on a video or a draft), so the
+// event log stays small however large the media is.
+//
+// READS GO THROUGH THE KERNEL'S RESOURCE-BLOB HELPERS (`readResourceBlobRange`, `resourceBlobSize`): a
+// branch inherits its ancestors' videos in the projection, so it must inherit their bytes too, and
+// those helpers look at the branch and then its retained ancestors. They read a RANGE natively, so
+// serving a seek, or sending one upload chunk, never loads the whole video.
+//
+// AN UPLOAD IS STAGING, and staging is NOT a kernel action: the upload_url the init hands back is a
+// place to put bytes, not an event in the creator's history. An upload is a pointer record plus its
+// chunks, each chunk its own key, joined ONCE when the final chunk lands; only that finalize is a
+// kernel write. An upload that is abandoned leaves no pending action to wedge a later deploy, and its
+// upload_url stops answering after TikTok's own hour.
+import { join } from 'node:path';
+import { blobDigest, getActiveBlobStore, readResourceBlobRange, resourceBlobSize, worldPaths } from '@volter/world-core';
+const SERVICE = 'tiktok';
+const DIGEST = /^[0-9a-f]{64}$/;
+const UPLOAD_ID = /^[0-9]{1,24}$/;
+function resources(root) {
+    return worldPaths(SERVICE, root).resources;
+}
+function blobKey(sha256) {
+    return join('blobs', 'sha256', sha256.slice(0, 2), sha256);
+}
+/** Store bytes content-addressed in this branch's annex; identical content is a no-op write. */
+export async function putTikTokBlob(bytes, root) {
+    const sha256 = blobDigest(bytes);
+    const key = join(resources(root), blobKey(sha256));
+    if (!(await getActiveBlobStore().exists(key)))
+        await getActiveBlobStore().put(key, bytes);
+    return { sha256, size: bytes.length };
+}
+/** A stored blob's size, here or at an ancestor; null when absent or the digest is malformed. */
+export async function tikTokBlobSize(sha256, root) {
+    if (typeof sha256 !== 'string' || !DIGEST.test(sha256))
+        return null;
+    return resourceBlobSize(SERVICE, blobKey(sha256), root);
+}
+/** Bytes start..endInclusive of a stored blob, here or at an ancestor, read as a range. */
+export async function readTikTokBlobRange(sha256, start, endInclusive, root) {
+    if (typeof sha256 !== 'string' || !DIGEST.test(sha256))
+        return null;
+    return readResourceBlobRange(SERVICE, blobKey(sha256), start, endInclusive, root);
+}
+function uploadDir(root) {
+    return join(resources(root), 'uploads');
+}
+function assertUploadId(id) {
+    if (!UPLOAD_ID.test(id))
+        throw new Error(`invalid TikTok upload id: ${JSON.stringify(id)}`);
+    return id;
+}
+function uploadKey(id, root) {
+    return join(uploadDir(root), `${assertUploadId(id)}.json`);
+}
+function publishKey(publishId, root) {
+    return join(uploadDir(root), 'by-publish', `${blobDigest(new TextEncoder().encode(publishId))}.json`);
+}
+function chunkDir(id, root) {
+    return join(uploadDir(root), assertUploadId(id));
+}
+/** A chunk's key carries its first byte, zero-padded so the seam's sorted listing is byte order. */
+function chunkKey(id, offset, root) {
+    return join(chunkDir(id, root), `${String(offset).padStart(16, '0')}.part`);
+}
+async function readJson(key) {
+    try {
+        const stored = await getActiveBlobStore().get(key);
+        return stored === null ? null : JSON.parse(new TextDecoder().decode(stored));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUpload(upload, root) {
+    const bytes = new TextEncoder().encode(JSON.stringify(upload));
+    await getActiveBlobStore().put(uploadKey(upload.uploadId, root), bytes);
+    await getActiveBlobStore().put(publishKey(upload.publishId, root), new TextEncoder().encode(JSON.stringify({ uploadId: upload.uploadId })));
+}
+export async function readUpload(id, root) {
+    if (!UPLOAD_ID.test(id))
+        return null;
+    const upload = await readJson(uploadKey(id, root));
+    return upload && typeof upload.uploadId === 'string' ? upload : null;
+}
+/** The upload a publish_id names, while it is staging (before its final chunk lands). */
+export async function readUploadByPublishId(publishId, root) {
+    const pointer = await readJson(publishKey(publishId, root));
+    return pointer ? readUpload(pointer.uploadId, root) : null;
+}
+/** The upload's chunks in byte order, with their offsets and sizes. */
+async function chunks(id, root) {
+    const prefix = `${chunkDir(id, root)}/`;
+    const out = [];
+    for (const key of await getActiveBlobStore().list(prefix)) {
+        const m = /(\d{16})\.part$/.exec(key);
+        if (!m)
+            continue;
+        out.push({ key, offset: Number(m[1]), size: (await getActiveBlobStore().size(key)) ?? 0 });
+    }
+    return out.sort((a, b) => a.offset - b.offset);
+}
+/** Bytes an upload holds so far: the contiguous run from 0. */
+export async function stagedSize(id, root) {
+    let held = 0;
+    for (const c of await chunks(id, root)) {
+        if (c.offset !== held)
+            break;
+        held += c.size;
+    }
+    return held;
+}
+/** Stage one chunk at its first byte — its own key; nothing already staged is read or rewritten. */
+export async function stageChunk(id, offset, bytes, root) {
+    if (bytes.length > 0)
+        await getActiveBlobStore().put(chunkKey(id, offset, root), bytes);
+}
+/** Join an upload's chunks, once, into the video's bytes. */
+export async function joinStaged(id, root) {
+    const parts = await chunks(id, root);
+    const total = parts.reduce((n, c) => n + c.size, 0);
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of parts) {
+        const bytes = await getActiveBlobStore().get(c.key);
+        if (bytes === null)
+            continue;
+        out.set(bytes, at);
+        at += bytes.length;
+    }
+    return out.subarray(0, at);
+}
+/** Drop a finalized upload's chunks (the bytes now live content-addressed); the record stays, so a
+ *  final PUT whose answer was lost can be asked again and status/fetch still finds the publish. */
+export async function clearStaged(id, root) {
+    try {
+        await getActiveBlobStore().remove(`${chunkDir(id, root)}/`);
+    }
+    catch { /* never staged */ }
+}
+function performKey(actionId, root) {
+    return join(resources(root), 'perform-publishes', `${blobDigest(new TextEncoder().encode(actionId))}.json`);
+}
+export async function readPerformPublish(actionId, root) {
+    return readJson(performKey(actionId, root));
+}
+export async function writePerformPublish(actionId, record, root) {
+    await getActiveBlobStore().put(performKey(actionId, root), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function clearPerformPublish(actionId, root) {
+    try {
+        await getActiveBlobStore().remove(performKey(actionId, root));
+    }
+    catch { /* none */ }
+}

package/dist/src/tiktok-budget.d.ts

@@ -0,0 +1,56 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms — TikTok's own one-minute sliding window. */
+export declare const TIKTOK_BUDGET_WINDOW_MS = 60000;
+/** Weighted units allowed inside one window — TikTok's own published per-endpoint figure, applied
+ *  across ALL endpoints at once (strictly tighter than the vendor's own per-endpoint allowance). */
+export declare const TIKTOK_BUDGET_CEILING = 600;
+/** The window IS the kernel's burst sub-window, so this is also the per-minute burst bound. */
+export declare const TIKTOK_BUDGET_BURST_CEILING = 600;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export declare const TIKTOK_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs judged. */
+export declare const TIKTOK_CALL_WEIGHTS: {
+    /** The three Display API reads — 600/min is the PUBLISHED limit; weight 1 transcribes it. */
+    readonly displayRead: 1;
+    /** `POST /v2/oauth/revoke/` — disconnects an app from a REAL human's TikTok account. Priced as a
+     *  human blast radius, not a throttle (a judgement call, stated as one). */
+    readonly revoke: 60;
+    /** Everything else (the token endpoint): no published scalar limit -> priced conservatively. */
+    readonly other: 5;
+    /** `POST /v2/post/publish/creator_info/query/` — "limited to 20 requests per minute". */
+    readonly creatorInfo: 30;
+    /** `POST /v2/post/publish/video/init/` and `/inbox/video/init/` — "limited to 6 requests per minute". */
+    readonly postInit: 100;
+    /** `POST /v2/post/publish/status/fetch/` — "limited to 30 requests per minute". */
+    readonly postStatus: 20;
+};
+/** THE PACK'S DECLARATION — pure data, the only TikTok-specific thing in the whole budget. */
+export declare const TIKTOK_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation — and on THIS vendor the trailing slash is not hypothetical: every
+ * documented TikTok path carries one (`/v2/oauth/revoke/`), so a rule anchored on the bare form
+ * would price the vendor's OWN spelling of the destructive call at the default weight.
+ */
+export declare function tiktokCallWeight(method: string, path: string): number;
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export declare function tiktokBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type TikTokBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof TikTokBudget` means "a budget that accounts against TIKTOK's
+ * ledger under TIKTOK's ceiling".
+ */
+export declare class TikTokBudget extends RateBudget {
+    constructor(opts?: TikTokBudgetOptions);
+}
+export { RateBudgetError as TikTokBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as TikTokBudgetErrorKind } from '@volter/world-core';
+export type TikTokBudgetReservation = RateBudgetReservation;
+export type TikTokBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/tiktok-budget.js

@@ -0,0 +1,136 @@
+// TikTok's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveTikTokExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` -> `rateBudget.ts`).
+//
+// ── HOW THE CEILING WAS CHOSEN (live-fetched first-party figures) ───────────────────────────────
+// TikTok PUBLISHES per-endpoint rate limits. From https://developers.tiktok.com/doc/tiktok-api-v2-rate-limit
+// (fetched 2026-09-13): "Request rate calculation is based on a one minute sliding window", the
+// table gives `/v2/user/info/`, `/v2/video/list/` and `/v2/video/query/` a limit of **600** each,
+// and "If the number of requests exceeds the threshold, new requests will be throttled and a
+// response will be returned with HTTP status 429 and error code rate_limit_exceeded."
+//
+// So the window is the vendor's own ONE MINUTE and the ceiling is the vendor's own 600, with each
+// Display API read at weight 1 — the declaration REPRODUCES the published scheme for the endpoints
+// the connector reads (the github-budget precedent: when the vendor's scheme is already a windowed
+// budget, transcribe it). Two deliberate tightenings on top, both stated rather than hidden:
+//
+//   • The vendor's 600 is PER ENDPOINT; this ledger is ONE budget across all of them, so 600
+//     shared is strictly tighter than the vendor's 1800 across the three.
+//   • The OAuth endpoints (`/v2/oauth/token/`, `/v2/oauth/revoke/`) publish NO scalar limit on
+//     that page. That absence is stated here rather than dressed up, and those calls are priced
+//     ABOVE the documented read so the undocumented surface is the conservative one.
+//
+// The window is already the kernel's 60s burst sub-window, so the ceiling IS the burst and the
+// kernel refuses a `burstCeiling` here. 600 units/minute out-bursts the kernel fallback's 30
+// calls/minute, which is licensed by the hand-written `burstAnchor` in this pack's gate.ts —
+// the vendor's own documented per-minute allowance, with its source.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'tiktok';
+/** Rolling window, in ms — TikTok's own one-minute sliding window. */
+export const TIKTOK_BUDGET_WINDOW_MS = 60_000;
+/** Weighted units allowed inside one window — TikTok's own published per-endpoint figure, applied
+ *  across ALL endpoints at once (strictly tighter than the vendor's own per-endpoint allowance). */
+export const TIKTOK_BUDGET_CEILING = 600;
+/** The window IS the kernel's burst sub-window, so this is also the per-minute burst bound. */
+export const TIKTOK_BUDGET_BURST_CEILING = TIKTOK_BUDGET_CEILING;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const TIKTOK_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs judged. */
+export const TIKTOK_CALL_WEIGHTS = {
+    /** The three Display API reads — 600/min is the PUBLISHED limit; weight 1 transcribes it. */
+    displayRead: 1,
+    /** `POST /v2/oauth/revoke/` — disconnects an app from a REAL human's TikTok account. Priced as a
+     *  human blast radius, not a throttle (a judgement call, stated as one). */
+    revoke: 60,
+    /** Everything else (the token endpoint): no published scalar limit -> priced conservatively. */
+    other: 5,
+    // The Content Posting calls publish their OWN per-token minute allowance on each reference page
+    // (fetched 2026-09-27), and each is priced so that the endpoint alone can never exceed it inside
+    // this 600-unit minute: weight = 600 / the published per-minute figure.
+    /** `POST /v2/post/publish/creator_info/query/` — "limited to 20 requests per minute". */
+    creatorInfo: 30,
+    /** `POST /v2/post/publish/video/init/` and `/inbox/video/init/` — "limited to 6 requests per minute". */
+    postInit: 100,
+    /** `POST /v2/post/publish/status/fetch/` — "limited to 30 requests per minute". */
+    postStatus: 20,
+};
+/** THE PACK'S DECLARATION — pure data, the only TikTok-specific thing in the whole budget. */
+export const TIKTOK_RATE_BUDGET = {
+    windowMs: TIKTOK_BUDGET_WINDOW_MS,
+    ceiling: TIKTOK_BUDGET_CEILING,
+    defaultWeight: TIKTOK_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: TIKTOK_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '^GET /v2/user/info$', weight: TIKTOK_CALL_WEIGHTS.displayRead },
+        { match: '^POST /v2/video/list$', weight: TIKTOK_CALL_WEIGHTS.displayRead },
+        { match: '^POST /v2/video/query$', weight: TIKTOK_CALL_WEIGHTS.displayRead },
+        { match: '^POST /v2/oauth/revoke$', weight: TIKTOK_CALL_WEIGHTS.revoke },
+        { match: '^POST /v2/post/publish/creator_info/query$', weight: TIKTOK_CALL_WEIGHTS.creatorInfo },
+        { match: '^POST /v2/post/publish/video/init$', weight: TIKTOK_CALL_WEIGHTS.postInit },
+        { match: '^POST /v2/post/publish/inbox/video/init$', weight: TIKTOK_CALL_WEIGHTS.postInit },
+        { match: '^POST /v2/post/publish/status/fetch$', weight: TIKTOK_CALL_WEIGHTS.postStatus },
+    ],
+    reason: 'TikTok publishes per-endpoint rate limits (https://developers.tiktok.com/doc/tiktok-api-v2-rate-limit, '
+        + 'fetched 2026-09-13): "Request rate calculation is based on a one minute sliding window", the '
+        + 'table lists /v2/user/info/, /v2/video/list/ and /v2/video/query/ at 600 each, and exceeding a '
+        + 'limit answers "HTTP status 429 and error code rate_limit_exceeded". This declaration '
+        + "transcribes that scheme: the window is the vendor's own one minute, the ceiling is the "
+        + "vendor's own 600, and each Display API read costs 1. It is tighter than the vendor in one "
+        + 'respect, deliberately: the published 600 is PER ENDPOINT while this is ONE ledger shared '
+        + 'across all three, so the twin spends at a third of the vendor allowance in the worst case. '
+        + 'The OAuth token and revoke endpoints publish NO scalar limit on that page; they are priced '
+        + 'ABOVE the documented read (defaultWeight 5) so the undocumented surface is the conservative '
+        + 'one. POST /v2/oauth/revoke/ costs 60 because it is the one destructive call here — it '
+        + "disconnects an app from a real human's TikTok account — which is a human blast radius, not a "
+        + 'throttle; that price is a judgement call, stated as one. The Content Posting references each '
+        + 'publish a per-token minute allowance (fetched 2026-09-27): creator_info 20, the Direct Post and '
+        + 'inbox inits 6, status/fetch 30; each is priced 600 divided by its figure (30, 100, 20), so no '
+        + 'one of them can exceed its own allowance inside this minute. The chunk PUTs to the upload URL '
+        + 'are not charged: they go to the upload host on a presigned URL, and once a publish has started '
+        + 'the budget cannot stop it. The vendor publishes no rate-limit response headers, so the 429 / '
+        + 'Retry-After cooldown is the only backstop and is armed from whatever the vendor does send.',
+};
+// Declared at module load, so merely importing this module (which `tiktok-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, TIKTOK_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation — and on THIS vendor the trailing slash is not hypothetical: every
+ * documented TikTok path carries one (`/v2/oauth/revoke/`), so a rule anchored on the bare form
+ * would price the vendor's OWN spelling of the destructive call at the default weight.
+ */
+export function tiktokCallWeight(method, path) {
+    const { bare, query } = splitQuery(path);
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+function splitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    const raw = at === -1 ? path : path.slice(0, at);
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export function tiktokBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through must not
+    // redirect this pack's ledger.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof TikTokBudget` means "a budget that accounts against TIKTOK's
+ * ledger under TIKTOK's ceiling".
+ */
+export class TikTokBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as TikTokBudgetError } from '@volter/world-core';

package/dist/src/tiktok-capabilities.d.ts

@@ -0,0 +1,7 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const TIKTOK_CAPABILITIES: CapabilitySpec[];
+/** Committed area census (TWIN-87/F1) — enumerated TOP-DOWN from the vendor's own product nav
+ *  (Login Kit, Display API, Content Posting, Research, Data Portability, Local Services, Business)
+ *  plus this pack's structural areas, not derived from the manifest (which would be a tautology). */
+export declare const TIKTOK_AREAS: readonly ["authorize", "business", "client_credentials", "conformance", "connector", "consent", "content_posting", "errors", "local_services", "login_kit", "mini_apps", "oembed", "portability", "rate", "readonly", "refresh", "research", "revoke", "scopes", "share_kit", "token", "ui", "user_info", "video", "webhooks"];
+export declare function tiktokCapabilities(): Promise<CapabilityReport>;