@volter/twin-tiktok 0.1.0

package/dist/src/tiktok-capabilities.js

@@ -0,0 +1,1855 @@
+// TikTok capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from the vendor's own published references, all fetched 2026-09-13 from developers.tiktok.com:
+//   • Login Kit for Web (the authorize URL, its six query parameters, the five callback
+//     parameters) and Login Kit for Desktop (PKCE: hex-encoded SHA-256, S256 only, the 43-128
+//     character verifier alphabet);
+//   • User Access Token Management (the authorization_code and refresh_token grants and revoke —
+//     request tables, response field tables, curl examples and JSON examples) and Client Access
+//     Token Management (the client_credentials grant);
+//   • the Scopes Overview (the scope catalog);
+//   • Get User Info (the field x scope table) and the Video Object / Video List / Video Query
+//     references (the video field table, max_count, the 20-id query limit, cursor semantics);
+//   • the OAuth error-handling reference (ten flat `error` values with their descriptions) and the
+//     API v2 error-handling reference (seven nested `error.code` values WITH HTTP statuses);
+//   • the rate-limit reference (a one-minute sliding window, 600 per endpoint, 429 +
+//     rate_limit_exceeded).
+// NOT from what this twin has built. `verify()` (required to count as done) is ground truth; every
+// `expected:'done'` is genuinely claimed, so a broken one shows as a regression.
+//
+// GRANULARITY: one capability per PROTOCOL BEHAVIOUR (a parameter honoured, an error produced, a
+// field selected) — the googleoauth/xidentity precedent. This surface is six endpoints with dozens
+// of behaviours, so per-endpoint entries would have been a denominator of six and a lie.
+//
+// AND THE ASYMMETRY THAT BUYS, STATED PLAINLY RATHER THAN HIDDEN: the six endpoints this pack
+// SERVES are enumerated at that behaviour granularity, while the vendor products it does not serve
+// yet (Content Posting, Research, Data Portability, Local Services, the Business API, the mobile /
+// QR login variants) are enumerated at OPERATION-FAMILY granularity — one todo per endpoint family
+// rather than per behaviour. That makes the headline percentage flattering: modelling Content
+// Posting would add one `done` per behaviour where one `todo` sits today. The right correction is
+// to expand those rows as each product is actually studied from its own reference, never to pad
+// them now with rows nobody has read the docs for — an invented denominator is the mirror image of
+// an invented numerator. Read the percentage as "the Login Kit + Display half is deep; the rest of
+// the open platform is a list of doors".
+//
+// SCOPE OF THE DENOMINATOR. This is the LOGIN KIT + DISPLAY API service-area of the TikTok vendor
+// pack — the half a user access token reaches, which is the half the motivating application (Dub)
+// calls. The vendor's other open-platform products (Content Posting, Research, Data Portability,
+// Commercial Content, and the mobile/QR login variants) ARE in this denominator as honest todos,
+// one per operation family, because they are real TikTok surface a twin could serve. The separate
+// business-api.tiktok.com Ads/Business API is named as a todo area too rather than silently
+// dropped.
+//
+// EVIDENCE BOUNDARIES: a `done` whose behaviour is derived from RFC 6749/7009 or from a
+// widely-reported capture rather than from a fetched official artefact says so in its title or its
+// comment, and a sibling `todo` pins the live capture. PIN-todos are not padding: each names a
+// behaviour the twin serves whose vendor truth is unverified, and closing one is real work against
+// the live vendor. Coverage % only gets WORSE from carrying them.
+//
+// TWIN-ONLY ROUTES ARE NOT COUNTED. `/_twin/consent`, `/_twin/clients`, `/_twin/accounts`,
+// `/_twin/videos`, `/_twin/session` and `/_twin/rate_limit` are scaffolding (TikTok's consent sheet
+// posts to an undocumented internal endpoint; no API creates a TikTok app, a user or a published
+// video), so they are absent from this denominator exactly as ADDING_A_TWIN.md §6 requires.
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { checkCapabilities, uiDataCoupled, verifyBoundary } from '@volter/world-tooling';
+import { ConsentPage, ErrorPage } from "../client/tiktok-consent.js";
+import { ActionRail, PlayerCaption, ProfileHeader, VideoGrid } from "../client/tiktok-mirror.js";
+import { buildTiktokMirrorClient, createTiktokMirrorServer, mediaSource, PROFILE_FIELDS as MIRROR_PROFILE_FIELDS, tiktokMirrorHtml, tiktokMirrorStyles, VIDEO_READ_FIELDS as MIRROR_VIDEO_FIELDS, } from "./tiktok-mirror-ui.js";
+import { tiktokConsentState } from "./tiktok-consent-ui.js";
+import { checkTikTokConformance, paddedMp4, TINY_MP4 } from "./tiktok-conformance.js";
+import { TikTokBudget, TikTokBudgetError, TIKTOK_BUDGET_CEILING, TIKTOK_CALL_WEIGHTS, tiktokCallWeight } from "./tiktok-budget.js";
+import { deployableEntries } from '@volter/world-core';
+import { liveTikTokExecute, mapUserInfoAccount, mapVideo, pullTikTok, performTikTokAction, pushPendingTikTokActions, syncTikTokFromReal, syncTikTokFromRemote, } from "./tiktok-connector.js";
+import { rfc7636Challenge, tiktokCodeChallenge } from "./tiktok-pkce.js";
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_KEY, DEFAULT_CLIENT_SECRET, DEFAULT_VIDEOS, defaultRedirectUris, openIdFor, } from "./tiktok-store.js";
+import { handleTikTokTwinRequest } from "./tiktok-twin.js";
+import { readAll } from "./tiktok-store.js";
+import { stageChunk } from "./tiktok-blobs.js";
+const AT = '2026-02-01T00:00:00.000Z';
+const atPlus = (seconds) => new Date(Date.parse(AT) + seconds * 1000).toISOString();
+/** The origin this harness's world serves the twin at. The seeded demo app's callbacks are DERIVED
+ *  from it (runtime contract R7: the port belongs to the caller's world, never to the twin's
+ *  source), so the probes below name no port of their own. */
+const DEMO_ORIGIN = 'http://localhost:3000';
+const REDIRECT_URIS = defaultRedirectUris(DEMO_ORIGIN);
+const REDIRECT = REDIRECT_URIS[0];
+const ADA = DEFAULT_ACCOUNTS[0];
+const GRACE = DEFAULT_ACCOUNTS[1];
+const ADA_VIDEOS = DEFAULT_VIDEOS.filter((v) => v.ownerUnionId === ADA.unionId);
+const SCOPE = 'user.info.basic,user.info.profile,user.info.stats,video.list';
+const ADA_OPEN_ID = openIdFor(DEFAULT_CLIENT_KEY, ADA.unionId);
+/** A well-formed PKCE verifier: 43+ characters from the documented unreserved alphabet. */
+const VERIFIER = 'twin-verifier-0123456789-0123456789-0123456789';
+const FORM_CT = { 'content-type': 'application/x-www-form-urlencoded' };
+const JSON_CT = { 'content-type': 'application/json' };
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'tiktok-cap-'));
+    const h = ((s) => handleTikTokTwinRequest({
+        method: s.m,
+        path: s.p,
+        ...(s.b === undefined ? {} : { body: s.b }),
+        ...(s.h ? { headers: s.h } : {}),
+        root,
+        origin: DEMO_ORIGIN,
+        occurredAt: s.at ?? AT,
+    }));
+    h.root = root;
+    try {
+        return await verifyBoundary('tiktok.withRoot', () => steps(h));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const ok = (r) => r.status >= 200 && r.status < 300;
+const body = (r) => r.body;
+const html = (r) => String(r.body);
+const loc = (r) => r.headers?.['location'] ?? '';
+const qp = (r, key) => {
+    try {
+        return new URL(loc(r)).searchParams.get(key);
+    }
+    catch {
+        return null;
+    }
+};
+const user = (r) => (body(r)?.data?.user ?? {});
+const videos = (r) => (body(r)?.data?.videos ?? []);
+const apiCode = (r) => body(r)?.error?.code;
+const form = (params) => new URLSearchParams(params).toString();
+const creds = { client_key: DEFAULT_CLIENT_KEY, client_secret: DEFAULT_CLIENT_SECRET };
+/** Build an authorize URL from parameters, so a verify can vary exactly one of them.
+ *  `undefined` REMOVES a base parameter. */
+function authUrl(params = {}) {
+    const q = new URLSearchParams();
+    const base = {
+        client_key: DEFAULT_CLIENT_KEY,
+        response_type: 'code',
+        redirect_uri: REDIRECT,
+        scope: SCOPE,
+        state: 'cap-state',
+        ...params,
+    };
+    for (const [k, v] of Object.entries(base))
+        if (v !== undefined)
+            q.set(k, v);
+    return `/v2/auth/authorize?${q.toString()}`;
+}
+const AUTH_REQUEST_RE = /name="auth_request" value="([^"]+)"/;
+/** Drive the REAL browser legs: authorize request -> authorization page -> Continue/Cancel -> the
+ *  302. Everything a verify needs from the round trip comes back. */
+async function consentFlow(h, opts = {}) {
+    const auth = await h({ m: 'GET', p: authUrl(opts.params ?? {}), ...(opts.at ? { at: opts.at } : {}) });
+    const requestId = AUTH_REQUEST_RE.exec(html(auth))?.[1] ?? '';
+    const requested = (opts.params?.['scope'] ?? SCOPE).split(',');
+    const decision = new URLSearchParams({ auth_request: requestId, decision: opts.decision ?? 'allow' });
+    for (const s of opts.grant ?? requested)
+        decision.append('scope', s);
+    const redirect = await h({ m: 'POST', p: '/_twin/consent', b: decision.toString(), ...(opts.at ? { at: opts.at } : {}) });
+    return { auth, requestId, redirect, code: qp(redirect, 'code'), state: qp(redirect, 'state'), scopes: qp(redirect, 'scopes') };
+}
+/** The full round trip, ending in redeemed tokens. */
+async function fullFlow(h, opts = {}) {
+    const flow = await consentFlow(h, opts);
+    if (!flow.code)
+        return { code: null, tokens: {}, status: 0, redirect: flow.redirect };
+    const res = await h({
+        m: 'POST',
+        p: '/v2/oauth/token/',
+        b: form({
+            client_key: opts.clientKey ?? DEFAULT_CLIENT_KEY,
+            client_secret: opts.clientSecret ?? DEFAULT_CLIENT_SECRET,
+            code: flow.code,
+            grant_type: 'authorization_code',
+            redirect_uri: opts.redirectUri ?? REDIRECT,
+            ...(opts.verifier ? { code_verifier: opts.verifier } : {}),
+        }),
+        h: { ...FORM_CT, ...(opts.headers ?? {}) },
+        ...(opts.tokenAt ?? opts.at ? { at: opts.tokenAt ?? opts.at } : {}),
+    });
+    return { code: flow.code, tokens: body(res), status: res.status, redirect: flow.redirect };
+}
+/** A live user access token for the seeded persona, with every scope granted. */
+async function accessToken(h, opts = {}) {
+    const { tokens } = await fullFlow(h, opts);
+    return String(tokens['access_token'] ?? '');
+}
+const bearer = (token) => ({ authorization: `Bearer ${token}` });
+// ── shorthands ──
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+// ── the Content Posting harness: a creator and tokens seeded through the twin's own doors, and the
+// vendor's calls driven through the one handler, bytes and all ──
+const POSTING_ORIGIN = 'http://twin.local:4000';
+const POSTER = '11111111-1111-4111-8111-111111111111';
+/** Under TikTok's 5 MB floor: one whole chunk — a real MP4 (1 s, 360x640, 24 FPS) the twin's checks pass. */
+const SMALL = TINY_MP4;
+/** A real MP4 of exactly `n` bytes (TINY_MP4 plus a `free` padding box). */
+const pattern = (n) => paddedMp4(n);
+const sameBytes = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+async function bytesOf(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ReadableStream)
+        return new Uint8Array(await new Response(value).arrayBuffer());
+    return new Uint8Array(0);
+}
+/** status/fetch, read the way a careful client must: the int64 post id off the raw text. */
+function parseStatus(r) {
+    const text = typeof r.body === 'string' ? r.body : JSON.stringify(r.body);
+    let parsed = {};
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch { /* checked by the caller */ }
+    const id = /"publicaly_available_post_id":\[(\d+)/.exec(text)?.[1];
+    return { status: parsed.data?.status, uploaded: parsed.data?.uploaded_bytes, ...(id ? { postId: id } : {}), code: parsed.error?.code, ...(typeof parsed.data?.fail_reason === 'string' ? { failReason: parsed.data.fail_reason } : {}) };
+}
+async function withPosting(steps, rootDir) {
+    const root = rootDir ?? mkdtempSync(join(tmpdir(), 'tiktok-post-'));
+    const send = (req) => handleTikTokTwinRequest({
+        method: req.m,
+        path: req.p,
+        ...(req.b !== undefined ? { body: req.b } : {}),
+        ...(req.bytes ? { bytes: req.bytes } : {}),
+        ...(req.h ? { headers: req.h } : {}),
+        ...(req.originalHost ? { originalHost: req.originalHost } : {}),
+        root,
+        origin: POSTING_ORIGIN,
+        occurredAt: req.at ?? AT,
+    });
+    const seed = async (path, json) => body(await send({ m: 'POST', p: path, b: JSON.stringify(json), h: JSON_CT }));
+    try {
+        return await verifyBoundary('tiktok.withPosting', async () => {
+            await seed('/_twin/accounts', { union_id: POSTER, username: 'poster', display_name: 'The Poster', stitch_disabled: true, max_video_post_duration_sec: 300 });
+            const token = String((await seed('/_twin/tokens', { union_id: POSTER, scopes: ['user.info.basic', 'video.list', 'video.publish', 'video.upload'] })).access_token);
+            const readToken = String((await seed('/_twin/tokens', { union_id: POSTER, client_key: DEFAULT_CLIENT_KEY, scopes: ['user.info.basic'], access_token: 'act.readonlytoken0000' })).access_token);
+            const otherToken = String((await seed('/_twin/tokens', { union_id: GRACE.unionId, scopes: ['video.publish', 'video.upload'] })).access_token);
+            const call = (path, json, bearer, at) => send({ m: 'POST', p: path, b: JSON.stringify(json), h: { ...JSON_CT, authorization: `Bearer ${bearer ?? token}` }, ...(at ? { at } : {}) });
+            const init = (mode, size, chunk, count, opts = {}) => send({
+                m: 'POST',
+                p: mode === 'direct' ? '/v2/post/publish/video/init/' : '/v2/post/publish/inbox/video/init/',
+                b: JSON.stringify({
+                    ...(mode === 'direct' ? { post_info: { privacy_level: opts.privacy ?? 'PUBLIC_TO_EVERYONE', ...(opts.title ? { title: opts.title } : {}) } } : {}),
+                    source_info: { source: 'FILE_UPLOAD', video_size: size, chunk_size: chunk, total_chunk_count: count },
+                }),
+                h: { ...JSON_CT, authorization: `Bearer ${token}` },
+                ...(opts.at ? { at: opts.at } : {}),
+                ...(opts.originalHost ? { originalHost: opts.originalHost } : {}),
+            });
+            const put = (url, bytes, range, at) => {
+                const u = new URL(url);
+                return send({ m: 'PUT', p: `${u.pathname}${u.search}`, bytes, h: { 'content-type': 'video/mp4', 'content-range': range }, ...(at ? { at } : {}) });
+            };
+            const media = (postId, headers, at, bearer) => send({ m: 'GET', p: `/_twin/media/video/${postId}${bearer ? `?access_token=${encodeURIComponent(bearer)}` : ''}`, h: headers, at: at ?? atPlus(600) });
+            const publish = async (bytes, chunk, privacy) => {
+                const count = Math.floor(bytes.length / chunk);
+                const started = await init('direct', bytes.length, chunk, count, { privacy });
+                const url = String(body(started).data?.upload_url);
+                for (let i = 0; i < count; i += 1) {
+                    const first = i * chunk;
+                    const last = i === count - 1 ? bytes.length - 1 : first + chunk - 1;
+                    await put(url, bytes.subarray(first, last + 1), `bytes ${first}-${last}/${bytes.length}`);
+                }
+                const publishId = String(body(started).data?.publish_id);
+                const status = await call('/v2/post/publish/status/fetch/', { publish_id: publishId }, undefined, atPlus(300));
+                const text = String(status.body);
+                const postId = /"publicaly_available_post_id":\[(\d+)/.exec(text)?.[1]
+                    ?? String(readAll(root).find((r) => r.type === 'publish' && r.id === publishId)?.postId ?? '');
+                return { publishId, postId };
+            };
+            return steps({ root, token, readToken, otherToken, call, init, put, media, publish });
+        });
+    }
+    finally {
+        if (!rootDir)
+            rmSync(root, { recursive: true, force: true });
+    }
+}
+// ── the connector's offline fake: a REAL-SHAPED TikTok reply (the vendor's own Get User Info
+// example, extended with the fields the twin models), never an invented one ──
+const FAKE_USER_INFO = {
+    data: {
+        user: {
+            open_id: '723f24d7-e717-40f8-a2b6-cb8464cd23b4',
+            union_id: 'c9c60f44-a68e-4f5d-84dd-ce22faeb0ba1',
+            avatar_url: 'https://p19-sign.tiktokcdn-us.com/tos-avt-0068-tx/b17f0e4b3a4f4a50993cf72cda8b88b8~c5_168x168.jpeg',
+            avatar_url_100: 'https://p19-sign.tiktokcdn-us.com/tos-avt-0068-tx/b17f0e4b3a4f4a50993cf72cda8b88b8~c5_100x100.jpeg',
+            avatar_large_url: 'https://p19-sign.tiktokcdn-us.com/tos-avt-0068-tx/b17f0e4b3a4f4a50993cf72cda8b88b8~c5_1080x1080.jpeg',
+            display_name: 'TikTok Developers',
+            bio_description: 'Build with TikTok',
+            profile_deep_link: 'https://www.tiktok.com/@tiktokdev',
+            is_verified: true,
+            username: 'tiktokdev',
+            follower_count: 583_423,
+            following_count: 2048,
+            likes_count: 1_405_233,
+            video_count: 42,
+        },
+    },
+    error: { code: 'ok', message: '', log_id: '20220829194722CBE87ED59D524E727021' },
+};
+const FAKE_VIDEO_LIST = {
+    data: {
+        videos: [
+            { id: '7010000000000000001', title: 'A real-shaped video', video_description: 'from the vendor example', create_time: 1_700_000_000, duration: 15, height: 1024, width: 576, like_count: 10, comment_count: 2, share_count: 1, view_count: 900 },
+        ],
+        cursor: 1_700_000_000_000,
+        has_more: false,
+    },
+    error: { code: 'ok', message: '', log_id: '20220829194722CBE87ED59D524E727022' },
+};
+const fakeExecute = async (_method, path) => {
+    if (path.startsWith('/v2/user/info'))
+        return structuredClone(FAKE_USER_INFO);
+    if (path.startsWith('/v2/video/list'))
+        return structuredClone(FAKE_VIDEO_LIST);
+    return {};
+};
+// ── the manifest ──────────────────────────────────────────────────────────────────────────────
+export const TIKTOK_CAPABILITIES = [
+    // ═══ authorize — GET www.tiktok.com/v2/auth/authorize ═════════════════════════════════════
+    done('tiktok.authorize.renders_consent', 'authorize', 'A valid authorize request renders the authorization page (HTML, 200) with a settleable request handle', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl() });
+        return r.status === 200 && /ar_[0-9a-f]{32}/.test(html(r)) && html(r).includes('Continue') && html(r).includes('Cancel');
+    })),
+    done('tiktok.authorize.trailing_slash_tolerated', 'authorize', "The vendor's documented path carries a trailing slash (/v2/auth/authorize/) while Dub's URL builder omits it — both reach the same screen", 'api', 'core', () => withRoot(async (h) => {
+        const bare = await h({ m: 'GET', p: authUrl() });
+        const slashed = await h({ m: 'GET', p: authUrl().replace('/v2/auth/authorize?', '/v2/auth/authorize/?') });
+        return bare.status === 200 && slashed.status === 200 && html(slashed).includes('Continue');
+    })),
+    done('tiktok.authorize.requires_client_key', 'authorize', 'A missing client_key renders the error page (no redirect — there is no trusted callback yet); the parameter is client_key, not client_id', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ client_key: undefined }) });
+        return r.status === 400 && html(r).includes('client_key') && !loc(r);
+    })),
+    done('tiktok.authorize.unknown_client_key', 'authorize', 'An unknown client_key renders the error page naming invalid_client (401), never a redirect', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ client_key: 'awnotarealapp00001' }) });
+        return r.status === 401 && html(r).includes('invalid_client') && !loc(r);
+    })),
+    done('tiktok.authorize.requires_redirect_uri', 'authorize', 'A missing redirect_uri renders the error page (no redirect)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ redirect_uri: undefined }) });
+        return r.status === 400 && html(r).includes('redirect_uri') && !loc(r);
+    })),
+    done('tiktok.authorize.redirect_uri_must_be_registered', 'authorize', '"It must match one of the redirect URIs you registered": a near-miss (trailing slash) is refused with the error page, the registered one passes', 'api', 'core', () => withRoot(async (h) => {
+        const near = await h({ m: 'GET', p: authUrl({ redirect_uri: `${REDIRECT}/` }) });
+        const exact = await h({ m: 'GET', p: authUrl() });
+        return near.status === 400 && !loc(near) && html(near).includes('redirect_uri') && exact.status === 200;
+    })),
+    done('tiktok.authorize.fragment_redirect_refused', 'authorize', 'A redirect_uri carrying a fragment is refused outright EVEN WHEN REGISTERED with one (RFC 6749 §3.1.2; a fragment never reaches the server)', 'api', 'niche', () => withRoot(async (h) => {
+        // The discriminating case: an unregistered fragment URI is refused by plain exact-match
+        // anyway, so the guard is only provable against an app REGISTERED with the fragment URI.
+        const fragKey = 'awfragapp000000001';
+        const fragUri = 'http://localhost:3000/cb#frag';
+        await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_key: fragKey, client_secret: 's', name: 'Frag App', redirect_uris: [fragUri] }) });
+        const r = await h({ m: 'GET', p: authUrl({ client_key: fragKey, redirect_uri: fragUri }) });
+        return r.status === 400 && !loc(r);
+    })),
+    done('tiktok.authorize.requires_response_type_code', 'authorize', 'response_type is required and must be `code` — "This value should always be set to code"; anything else bounces unsupported_response_type to the validated callback', 'api', 'core', () => withRoot(async (h) => {
+        const missing = await h({ m: 'GET', p: authUrl({ response_type: undefined }) });
+        const wrong = await h({ m: 'GET', p: authUrl({ response_type: 'token' }) });
+        return missing.status === 302 && loc(missing).startsWith(REDIRECT) && qp(missing, 'error') === 'invalid_request'
+            && wrong.status === 302 && qp(wrong, 'error') === 'unsupported_response_type' && qp(wrong, 'state') === 'cap-state';
+    })),
+    done('tiktok.authorize.requires_scope', 'authorize', 'scope is required (the Login Kit parameter table); a request without one bounces invalid_request', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ scope: undefined }) });
+        return r.status === 302 && qp(r, 'error') === 'invalid_request' && String(qp(r, 'error_description')).includes('scope');
+    })),
+    done('tiktok.authorize.all_unknown_scopes_refused', 'authorize', "A scope string naming nothing in the vendor catalog bounces the vendor's own invalid_scope", 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ scope: 'totally.bogus,also.bogus' }) });
+        return r.status === 302 && qp(r, 'error') === 'invalid_scope'
+            && String(qp(r, 'error_description')).includes('invalid, unknown, or malformed');
+    })),
+    done('tiktok.authorize.state_roundtrip', 'authorize', "The caller's state is echoed VERBATIM on the success redirect", 'api', 'core', () => withRoot(async (h) => {
+        const state = 'st~ate-With_Odd.Chars123';
+        const flow = await consentFlow(h, { params: { state } });
+        return flow.redirect.status === 302 && flow.state === state && !!flow.code;
+    })),
+    done('tiktok.authorize.state_optional', 'authorize', "state is NOT required (the parameter table marks it a CSRF convenience): omitting it still authorizes, and the callback then carries no state at all rather than an empty one", 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h, { params: { state: undefined } });
+        return flow.redirect.status === 302 && !!flow.code && flow.state === null
+            && !new URL(loc(flow.redirect)).searchParams.has('state');
+    })),
+    done('tiktok.authorize.callback_params_exact', 'authorize', 'The success redirect carries EXACTLY code, scopes and state — the three the documented callback table lists, and the twin invents none', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        if (flow.redirect.status !== 302)
+            return false;
+        const keys = [...new URL(loc(flow.redirect)).searchParams.keys()].sort();
+        return keys.length === 3 && keys[0] === 'code' && keys[1] === 'scopes' && keys[2] === 'state';
+    })),
+    done('tiktok.authorize.granted_scopes_on_callback', 'authorize', 'The callback carries `scopes` — "the authorization scope(s) which the user has granted" — comma-separated, reflecting the decision and not the request', 'api', 'core', () => withRoot(async (h) => {
+        const flow = await consentFlow(h, { grant: ['user.info.basic', 'video.list'] });
+        return flow.redirect.status === 302 && flow.scopes === 'user.info.basic,video.list';
+    })),
+    done('tiktok.authorize.pkce_optional_for_web', 'authorize', 'PKCE is OPTIONAL (required for desktop apps only): an authorize request with no code_challenge renders the page and its code redeems with no code_verifier — the exact shape the motivating web app uses', 'api', 'core', () => withRoot(async (h) => {
+        const r = await fullFlow(h);
+        return r.status === 200 && typeof r.tokens['access_token'] === 'string';
+    })),
+    done('tiktok.authorize.challenge_needs_method', 'authorize', 'code_challenge and code_challenge_method travel together — either one alone bounces invalid_request', 'api', 'common', () => withRoot(async (h) => {
+        const noMethod = await h({ m: 'GET', p: authUrl({ code_challenge: tiktokCodeChallenge(VERIFIER) }) });
+        const noChallenge = await h({ m: 'GET', p: authUrl({ code_challenge_method: 'S256' }) });
+        return noMethod.status === 302 && qp(noMethod, 'error') === 'invalid_request'
+            && noChallenge.status === 302 && qp(noChallenge, 'error') === 'invalid_request';
+    })),
+    done('tiktok.authorize.challenge_method_s256_only', 'authorize', '"TikTok only supports S256 as code_challenge_method": `plain` — which RFC 7636 and the X twin both accept — is refused here', 'api', 'common', () => withRoot(async (h) => {
+        const plain = await h({ m: 'GET', p: authUrl({ code_challenge: 'plainvalue', code_challenge_method: 'plain' }) });
+        const s256 = await h({ m: 'GET', p: authUrl({ code_challenge: tiktokCodeChallenge(VERIFIER), code_challenge_method: 'S256' }) });
+        return plain.status === 302 && qp(plain, 'error') === 'invalid_request' && s256.status === 200;
+    })),
+    done('tiktok.authorize.disable_auto_auth_validated', 'authorize', 'disable_auto_auth is an int (0 or 1); anything else bounces invalid_request', 'api', 'niche', () => withRoot(async (h) => {
+        const bad = await h({ m: 'GET', p: authUrl({ disable_auto_auth: 'true' }) });
+        const good = await h({ m: 'GET', p: authUrl({ disable_auto_auth: '1' }) });
+        return bad.status === 302 && qp(bad, 'error') === 'invalid_request' && good.status === 200;
+    })),
+    done('tiktok.authorize.auto_auth_skips_page', 'authorize', '"When set to 0, skips the authorization page for valid sessions": with an existing grant covering the request, disable_auto_auth=0 bounces a code without a screen', 'api', 'common', () => withRoot(async (h) => {
+        const first = await consentFlow(h);
+        if (!first.code)
+            return false;
+        const again = await h({ m: 'GET', p: authUrl({ disable_auto_auth: '0', state: 'auto-state' }) });
+        return again.status === 302 && !!qp(again, 'code') && qp(again, 'state') === 'auto-state'
+            && qp(again, 'scopes') === SCOPE;
+    })),
+    done('tiktok.authorize.auto_auth_needs_covering_grant', 'authorize', "EXTRAPOLATION (§9 F5): the docs say disable_auto_auth=0 skips the page for \"valid sessions\" and say nothing about scope coverage. The twin reads that conservatively — it skips only for a session that ALREADY granted every requested scope, so a first authorization or a widened scope set still shows the page — because skipping on a session alone would hand an app scopes nobody consented to. tiktok.authorize.auto_auth_scope_coverage (todo) pins the live rule", 'api', 'common', () => withRoot(async (h) => {
+        const fresh = await h({ m: 'GET', p: authUrl({ disable_auto_auth: '0' }) });
+        if (fresh.status !== 200)
+            return false;
+        await consentFlow(h, { params: { scope: 'user.info.basic' }, grant: ['user.info.basic'] });
+        const widened = await h({ m: 'GET', p: authUrl({ disable_auto_auth: '0', scope: 'user.info.basic,video.list' }) });
+        return widened.status === 200 && html(widened).includes('Continue');
+    })),
+    done('tiktok.authorize.request_single_use', 'authorize', 'A settled authorization request cannot be settled twice (the browser cannot replay a decision)', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const again = await h({ m: 'POST', p: '/_twin/consent', b: form({ auth_request: flow.requestId, decision: 'allow' }) });
+        return !!flow.code && again.status === 400 && body(again)['error'] === 'invalid_request';
+    })),
+    todo('tiktok.authorize.error_channel', 'authorize', 'PIN which authorize failures TikTok renders as a page vs bounces to the callback (the twin follows RFC 6749 §4.1.2.1 after the redirect_uri boundary, unpinned)', 'api', 'common'),
+    todo('tiktok.authorize.error_page_fidelity', 'authorize', "PIN tiktok.com's live authorize error page (DOM, wording, HTTP status) — the twin renders a plain machine-readable card, unpinned", 'api', 'niche'),
+    todo('tiktok.authorize.auto_auth_scope_coverage', 'authorize', 'PIN what disable_auto_auth=0 actually keys on — the docs say "valid sessions" and say nothing about scope coverage, so the twin additionally requires a grant covering every requested scope', 'api', 'common'),
+    todo('tiktok.authorize.disable_auto_auth_default', 'authorize', 'PIN the live default when disable_auto_auth is ABSENT (the twin shows the page, the conservative reading, because bypassing the human leg is what this pack exists to make visible)', 'api', 'common'),
+    todo('tiktok.authorize.redirect_uri_matching', 'authorize', 'PIN whether TikTok compares Redirect URIs exactly or by prefix (the twin compares exactly, the strict reading)', 'api', 'common'),
+    todo('tiktok.authorize.redirect_uri_scheme_rules', 'authorize', 'MODEL the documented scheme/port restrictions on registered Redirect URIs (https for web; localhost/127.0.0.1 with a port, wildcard port allowed, for desktop)', 'api', 'niche'),
+    todo('tiktok.authorize.challenge_method_case', 'authorize', 'PIN the live case tolerance for code_challenge_method (the twin accepts only the documented `S256`, not `s256`)', 'api', 'niche'),
+    todo('tiktok.authorize.state_length_limit', 'authorize', 'PIN whether TikTok caps the state parameter length (the twin imposes none)', 'api', 'niche'),
+    todo('tiktok.login_kit.qr_code_authorization', 'login_kit', 'Model the QR-code authorization flow (the desktop pairing surface with its own polling endpoint)', 'api', 'common'),
+    todo('tiktok.login_kit.silent_login', 'login_kit', 'Model Silent Login (re-authorization without a visible sheet for an already-connected user)', 'api', 'niche'),
+    todo('tiktok.login_kit.mobile_sdk_flows', 'login_kit', 'Model the iOS/Android Login Kit handshakes (app-to-app authorization via the TikTok app rather than a browser redirect)', 'api', 'common'),
+    todo('tiktok.login_kit.web_sdk_button', 'login_kit', 'Serve the Login Kit JavaScript SDK / login button asset the web quickstart embeds', 'api', 'niche'),
+    // ═══ consent semantics (what the person on the page actually decides) ═════════════════════
+    done('tiktok.consent.granular_subset', 'consent', "Consent is GRANULAR: unchecking a scope yields a token whose `scope` lacks it, and the Display API then refuses the field that scope gated", 'api', 'core', () => withRoot(async (h) => {
+        const { tokens, status } = await fullFlow(h, { grant: ['user.info.basic'] });
+        if (status !== 200 || tokens['scope'] !== 'user.info.basic')
+            return false;
+        const me = await h({ m: 'GET', p: '/v2/user/info/?fields=username', h: bearer(String(tokens['access_token'])) });
+        return me.status === 401 && apiCode(me) === 'scope_not_authorized';
+    })),
+    done('tiktok.consent.cannot_widen_beyond_request', 'consent', 'A hand-crafted decision post cannot grant a scope the authorize request never asked for', 'api', 'core', () => withRoot(async (h) => {
+        const auth = await h({ m: 'GET', p: authUrl({ scope: 'user.info.basic' }) });
+        const rid = AUTH_REQUEST_RE.exec(html(auth))?.[1] ?? '';
+        const decision = new URLSearchParams({ auth_request: rid, decision: 'allow' });
+        decision.append('scope', 'user.info.basic');
+        decision.append('scope', 'video.list');
+        const r = await h({ m: 'POST', p: '/_twin/consent', b: decision.toString() });
+        return r.status === 302 && qp(r, 'scopes') === 'user.info.basic';
+    })),
+    done('tiktok.consent.deny_access_denied', 'consent', 'Cancelling bounces error=access_denied with the vendor\'s own description and the state echoed, and NO code', 'api', 'core', () => withRoot(async (h) => {
+        const flow = await consentFlow(h, { decision: 'deny' });
+        return flow.redirect.status === 302 && qp(flow.redirect, 'error') === 'access_denied'
+            && String(qp(flow.redirect, 'error_description')).includes('denied the request')
+            && flow.state === 'cap-state' && flow.code === null;
+    })),
+    done('tiktok.consent.no_scope_is_denial', 'consent', 'Unchecking EVERY scope is a refusal, not a zero-scope grant — a token that could serve nothing is never minted', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h, { grant: [] });
+        return flow.redirect.status === 302 && qp(flow.redirect, 'error') === 'access_denied' && flow.code === null;
+    })),
+    done('tiktok.consent.session_account_consents', 'consent', "The consent is made BY the tiktok.com session's signed-in account — switching the session switches whose identity the flow yields", 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/_twin/session', b: JSON.stringify({ union_id: GRACE.unionId }) });
+        const token = await accessToken(h);
+        if (!token)
+            return false;
+        const me = await h({ m: 'GET', p: '/v2/user/info/?fields=union_id,username', h: bearer(token) });
+        return ok(me) && user(me)['union_id'] === GRACE.unionId && user(me)['username'] === GRACE.username;
+    })),
+    done('tiktok.consent.regrant_updates_grant', 'consent', "EXTRAPOLATION (§9 F5): no vendor artefact states whether a re-authorization REPLACES or UNIONS the app's recorded scopes, nor whether an older wider token keeps its reach. The twin replaces — the live grant is the authority and an older token is narrowed with it — because the union reading would let a person who revoked a permission on the sheet keep granting it. tiktok.consent.regrant_semantics (todo) pins the live behaviour", 'api', 'common', () => withRoot(async (h) => {
+        const wide = await accessToken(h);
+        const narrow = await fullFlow(h, { grant: ['user.info.basic'] });
+        if (!wide || narrow.status !== 200)
+            return false;
+        // The OLD token's scope string still says video.list, but the live grant no longer does, so
+        // the read is refused — the grant is the authority, not the token's frozen scope string.
+        const stale = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({}), h: { ...bearer(wide), ...JSON_CT } });
+        return stale.status === 401 && apiCode(stale) === 'scope_not_authorized';
+    })),
+    todo('tiktok.consent.regrant_semantics', 'consent', "PIN whether a re-authorization REPLACES or UNIONS the app's recorded scope set, and whether a previously issued wider token keeps its reach after a narrower re-grant (the twin replaces, and narrows the older token with it)", 'api', 'common'),
+    todo('tiktok.consent.optional_scope_toggles', 'consent', "PIN the live authorization sheet's per-scope affordance (which scopes are mandatory, whether they render as toggles or checkboxes) — the twin offers a checkbox per requested scope, unpinned", 'ui', 'common'),
+    todo('tiktok.consent.button_wording', 'consent', "PIN the live sheet's button labels (the twin renders Continue / Cancel)", 'ui', 'niche'),
+    todo('tiktok.consent.no_scope_granted', 'consent', 'PIN what the live endpoint does when a user grants none of the requested scopes (the twin treats it as access_denied)', 'api', 'niche'),
+    // ═══ token — POST open.tiktokapis.com/v2/oauth/token/ (authorization_code) ════════════════
+    done('tiktok.token.code_exchange', 'token', "A minted code redeems for the guide's own body: access_token, expires_in 86400, open_id, refresh_expires_in 31536000, refresh_token, scope, token_type Bearer", 'api', 'core', () => withRoot(async (h) => {
+        const { tokens, status } = await fullFlow(h);
+        return status === 200
+            && String(tokens['access_token']).startsWith('act.')
+            && tokens['expires_in'] === 86_400
+            && tokens['open_id'] === ADA_OPEN_ID
+            && tokens['refresh_expires_in'] === 31_536_000
+            && String(tokens['refresh_token']).startsWith('rft.')
+            && tokens['scope'] === SCOPE
+            && tokens['token_type'] === 'Bearer'
+            && Object.keys(tokens).length === 7;
+    })),
+    done('tiktok.token.body_fields_are_the_scheme', 'token', "The app authenticates with the client_key / client_secret FORM FIELDS — the only scheme TikTok documents. An Authorization: Basic header is IGNORED, neither required nor refused (Dub sends one, its callback route being shared with a Basic-auth provider, and the exchange must still succeed); the same header WITHOUT the body fields authenticates nothing", 'api', 'core', () => withRoot(async (h) => {
+        const basic = `Basic ${Buffer.from(`${DEFAULT_CLIENT_KEY}:${DEFAULT_CLIENT_SECRET}`).toString('base64')}`;
+        // (a) the body fields alone, with NO Authorization header at all, are enough — and the
+        //     open_id that comes back proves the BODY's client_key is what selected the app…
+        const bare = await fullFlow(h, { params: { state: 'bare' } });
+        // (b) …the header alongside them changes nothing…
+        const withHeader = await fullFlow(h, { headers: { authorization: basic } });
+        // …and the header alone is NOT accepted as authentication: the body fields are the scheme.
+        const flow = await consentFlow(h);
+        const headerOnly = await h({
+            m: 'POST',
+            p: '/v2/oauth/token/',
+            b: form({ code: String(flow.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }),
+            h: { ...FORM_CT, authorization: basic },
+        });
+        // …and (c) the header WITHOUT the body fields is not authentication on this vendor.
+        return bare.status === 200 && bare.tokens['open_id'] === ADA_OPEN_ID
+            && withHeader.status === 200 && typeof withHeader.tokens['access_token'] === 'string'
+            && headerOnly.status === 400 && body(headerOnly)['error'] === 'invalid_request';
+    })),
+    done('tiktok.token.missing_client_secret', 'token', 'A request without client_secret is refused with the vendor\'s own wording: "Client secret is missed in request."', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ client_key: DEFAULT_CLIENT_KEY, code: String(flow.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'invalid_request'
+            && body(r)['error_description'] === 'Client secret is missed in request.';
+    })),
+    done('tiktok.token.missing_grant_type', 'token', 'A request without grant_type is refused before anything else is looked at', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'invalid_request' && String(body(r)['error_description']).includes('Grant type');
+    })),
+    done('tiktok.token.unknown_client_key', 'token', 'An unknown client_key fails client authentication: invalid_client, 401', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ client_key: 'awnotarealapp00001', client_secret: 'x', code: String(flow.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        return r.status === 401 && body(r)['error'] === 'invalid_client'
+            && String(body(r)['error_description']).includes('Client authentication failed');
+    })),
+    done('tiktok.token.wrong_client_secret', 'token', 'A wrong client_secret fails client authentication the same way an unknown key does (no oracle for which half was wrong)', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ client_key: DEFAULT_CLIENT_KEY, client_secret: 'not-the-secret', code: String(flow.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        return r.status === 401 && body(r)['error'] === 'invalid_client';
+    })),
+    done('tiktok.token.redirect_uri_must_match', 'token', 'The redirect_uri "must be the same as the redirect_uri used for requesting code" — the vendor\'s own message: "Redirect_uri is not matched with the uri when requesting code."', 'api', 'core', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { redirectUri: REDIRECT_URIS[1] });
+        return r.status === 400 && r.tokens['error'] === 'invalid_request'
+            && r.tokens['error_description'] === 'Redirect_uri is not matched with the uri when requesting code.';
+    })),
+    done('tiktok.token.code_single_use', 'token', 'An authorization code redeems exactly ONCE; the replay is invalid_grant', 'api', 'core', () => withRoot(async (h) => {
+        const first = await fullFlow(h);
+        const again = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, code: String(first.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        return first.status === 200 && again.status === 400 && body(again)['error'] === 'invalid_grant';
+    })),
+    done('tiktok.token.code_expires', 'token', 'An authorization code expires; a redemption after its lifetime is invalid_grant while the same code redeems inside it', 'api', 'common', () => withRoot(async (h) => {
+        const inside = await fullFlow(h, { tokenAt: atPlus(60) });
+        const late = await fullFlow(h, { params: { state: 'late' }, tokenAt: atPlus(3600) });
+        return inside.status === 200 && late.status === 400 && late.tokens['error'] === 'invalid_grant';
+    })),
+    done('tiktok.token.code_bound_to_client', 'token', 'A code minted for one app cannot be redeemed by another (the "was issued to another client" half of invalid_grant)', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_key: 'awotherapp00000001', client_secret: 'other-secret', name: 'Other App', redirect_uris: [REDIRECT] }) });
+        const flow = await consentFlow(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ client_key: 'awotherapp00000001', client_secret: 'other-secret', code: String(flow.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'invalid_grant';
+    })),
+    done('tiktok.token.pkce_hex_sha256', 'token', "TikTok's code_challenge is the HEX SHA-256 of the verifier, NOT RFC 7636's base64url: the hex challenge verifies and the base64url one does not", 'api', 'core', () => withRoot(async (h) => {
+        const good = await fullFlow(h, { params: { code_challenge: tiktokCodeChallenge(VERIFIER), code_challenge_method: 'S256' }, verifier: VERIFIER });
+        const rfc = await fullFlow(h, { params: { code_challenge: rfc7636Challenge(VERIFIER), code_challenge_method: 'S256', state: 'rfc' }, verifier: VERIFIER });
+        return good.status === 200 && rfc.status === 400 && rfc.tokens['error'] === 'invalid_grant';
+    })),
+    done('tiktok.token.pkce_requires_verifier_when_bound', 'token', 'A code minted WITH a challenge demands a code_verifier; a wrong verifier is invalid_grant', 'api', 'common', () => withRoot(async (h) => {
+        const params = { code_challenge: tiktokCodeChallenge(VERIFIER), code_challenge_method: 'S256' };
+        const missing = await fullFlow(h, { params });
+        const wrong = await fullFlow(h, { params: { ...params, state: 'wrong' }, verifier: 'twin-verifier-9999999999-9999999999-9999999999' });
+        return missing.status === 400 && String(missing.tokens['error_description']).includes('Code verifier')
+            && wrong.status === 400 && wrong.tokens['error'] === 'invalid_grant';
+    })),
+    done('tiktok.token.verifier_shape_enforced', 'token', 'A code_verifier outside the documented alphabet/length (43-128 unreserved characters) can never satisfy a challenge', 'api', 'niche', () => withRoot(async (h) => {
+        const short = 'tooshort';
+        const r = await fullFlow(h, { params: { code_challenge: tiktokCodeChallenge(short), code_challenge_method: 'S256' }, verifier: short });
+        return r.status === 400 && r.tokens['error'] === 'invalid_grant';
+    })),
+    done('tiktok.token.unsupported_grant_type', 'token', 'An unknown grant_type is the vendor\'s own unsupported_grant_type with its published description', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'password' }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'unsupported_grant_type'
+            && String(body(r)['error_description']).includes('not supported by the authorization server');
+    })),
+    done('tiktok.token.open_id_is_per_app', 'token', "open_id is APP-SCOPED while union_id is per-human: the same account authorizing two apps yields two different open_ids and one union_id", 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_key: 'awsecondapp0000001', client_secret: 'second-secret', name: 'Second App', redirect_uris: [REDIRECT] }) });
+        const first = await fullFlow(h);
+        const second = await fullFlow(h, { params: { client_key: 'awsecondapp0000001', state: 'second' }, clientKey: 'awsecondapp0000001', clientSecret: 'second-secret' });
+        if (first.status !== 200 || second.status !== 200)
+            return false;
+        const a = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id,union_id', h: bearer(String(first.tokens['access_token'])) });
+        const b = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id,union_id', h: bearer(String(second.tokens['access_token'])) });
+        return user(a)['open_id'] !== user(b)['open_id']
+            && user(a)['union_id'] === user(b)['union_id']
+            && user(a)['union_id'] === ADA.unionId;
+    })),
+    done('tiktok.token.open_id_is_a_valid_uuid', 'token', "open_id and union_id are valid version-4 UUIDs, not merely UUID-shaped: an integration that validates the id it stores (a Zod .uuid(), a Postgres uuid column) must accept the twin's exactly as it accepts the vendor's documented example", 'api', 'core', () => withRoot(async (h) => {
+        // §9 F4: the mint used to slice a hash into 8-4-4-4-12 without setting the version or variant
+        // nibbles, so every open_id this twin issued FAILED uuid validation while TikTok's own example
+        // (723f24d7-e717-40f8-a2b6-cb8464cd23b4) passes. The regex below is the one such a validator
+        // applies, and the vendor's example is asserted against the SAME regex so the bar cannot be
+        // quietly lowered to whatever the twin happens to emit.
+        const V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+        if (!V4.test('723f24d7-e717-40f8-a2b6-cb8464cd23b4'))
+            return false;
+        const token = await accessToken(h);
+        const me = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id,union_id', h: bearer(token) });
+        const u = user(me);
+        return ok(me) && V4.test(String(u['open_id'])) && V4.test(String(u['union_id']))
+            && u['open_id'] !== u['union_id'];
+    })),
+    done('tiktok.token.open_id_is_stable', 'token', 'The same (app, account) pair gets the SAME open_id on every re-authorization — an app that keys its user records on open_id must not see a new user each login', 'api', 'core', () => withRoot(async (h) => {
+        const first = await fullFlow(h);
+        const second = await fullFlow(h, { params: { state: 'again' } });
+        return first.status === 200 && second.status === 200
+            && first.tokens['open_id'] === second.tokens['open_id']
+            && first.tokens['open_id'] === ADA_OPEN_ID;
+    })),
+    done('tiktok.token.code_needs_url_decoding', 'token', 'The code is "URL decoded" at the token endpoint because it carries characters a query string percent-encodes — the raw callback text does NOT redeem, the decoded one does', 'api', 'common', () => withRoot(async (h) => {
+        const flow = await consentFlow(h);
+        const raw = new URL(loc(flow.redirect)).search.match(/[?&]code=([^&]*)/)?.[1] ?? '';
+        // The wire form really IS encoded, and decoding it really does produce the stored code.
+        if (!raw.includes('%') || raw === flow.code || decodeURIComponent(raw) !== flow.code)
+            return false;
+        const undecoded = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, code: raw, grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        const decoded = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, code: String(flow.code), grant_type: 'authorization_code', redirect_uri: REDIRECT }), h: FORM_CT });
+        return undecoded.status === 400 && body(undecoded)['error'] === 'invalid_grant' && decoded.status === 200;
+    })),
+    todo('tiktok.token.error_http_status', 'token', "PIN the HTTP status TikTok pairs with each OAuth `error` value — its reference publishes the codes and descriptions with NO status column, so the twin answers RFC 6749 §5.2's 400/401", 'api', 'common'),
+    todo('tiktok.token.error_wording', 'token', 'PIN the live error_description strings for the cases the docs never exemplify (missing client_key, missing code, missing grant_type)', 'api', 'niche'),
+    todo('tiktok.token.code_format', 'token', 'PIN the live authorization-code format (the twin mints the widely-reported `…*!1!` shape that makes the documented URL-decoding requirement observable)', 'api', 'niche'),
+    todo('tiktok.token.code_ttl', 'token', 'PIN the live authorization-code lifetime (the twin uses ten minutes, the RFC 6749 §4.1.2 recommendation)', 'api', 'niche'),
+    todo('tiktok.token.json_body_tolerance', 'token', 'PIN whether the live token endpoint tolerates a JSON body (the twin accepts only the documented application/x-www-form-urlencoded)', 'api', 'niche'),
+    todo('tiktok.token.basic_auth', 'token', 'PIN whether the live token endpoint ACCEPTS HTTP Basic client authentication as an alternative to the body fields (the twin ignores the header)', 'api', 'common'),
+    todo('tiktok.token.scope_narrowing_at_token', 'token', 'MODEL a `scope` parameter at the token endpoint if TikTok honours one (down-scoping an exchange)', 'api', 'niche'),
+    // ═══ refresh ══════════════════════════════════════════════════════════════════════════════
+    done('tiktok.refresh.rotates', 'refresh', '"The returned refresh_token may be different than the one passed in the payload": the twin always rotates, so a client that fails to persist the new one breaks HERE', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']) }), h: FORM_CT });
+        return r.status === 200 && String(body(r)['refresh_token']).startsWith('rft.')
+            && body(r)['refresh_token'] !== tokens['refresh_token']
+            && String(body(r)['access_token']).startsWith('act.')
+            && body(r)['access_token'] !== tokens['access_token']
+            && body(r)['token_type'] === 'Bearer';
+    })),
+    done('tiktok.refresh.spent_token_refused', 'refresh', 'A rotated-away refresh token is dead: presenting it again is invalid_grant', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const spend = form({ ...creds, grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']) });
+        const first = await h({ m: 'POST', p: '/v2/oauth/token/', b: spend, h: FORM_CT });
+        const second = await h({ m: 'POST', p: '/v2/oauth/token/', b: spend, h: FORM_CT });
+        return first.status === 200 && second.status === 400 && body(second)['error'] === 'invalid_grant';
+    })),
+    done('tiktok.refresh.requires_refresh_token', 'refresh', 'A refresh_token grant with no refresh_token is refused', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'refresh_token' }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'invalid_request' && String(body(r)['error_description']).includes('Refresh token');
+    })),
+    done('tiktok.refresh.preserves_scope_and_open_id', 'refresh', 'A refreshed token carries the SAME granted scope set and the same open_id — a refresh is not a re-authorization', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h, { grant: ['user.info.basic', 'video.list'] });
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']) }), h: FORM_CT });
+        return r.status === 200 && body(r)['scope'] === 'user.info.basic,video.list' && body(r)['open_id'] === ADA_OPEN_ID;
+    })),
+    done('tiktok.refresh.new_token_works', 'refresh', 'The refreshed access token is usable at the Display API and the previous one is not silently kept alive by the refresh itself', 'api', 'common', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']) }), h: FORM_CT });
+        const me = await h({ m: 'GET', p: '/v2/user/info/?fields=union_id', h: bearer(String(body(r)['access_token'])) });
+        return r.status === 200 && me.status === 200 && user(me)['union_id'] === ADA.unionId;
+    })),
+    todo('tiktok.refresh.rotation', 'refresh', 'PIN whether the live vendor ALWAYS rotates the refresh token or only sometimes ("may be different"), and whether the presented one dies', 'api', 'common'),
+    todo('tiktok.refresh.expiry_behaviour', 'refresh', 'PIN what a refresh past the 365-day refresh_expires_in returns, and whether the window restarts on every refresh', 'api', 'niche'),
+    // ═══ revoke ═══════════════════════════════════════════════════════════════════════════════
+    done('tiktok.revoke.empty_success_body', 'revoke', '"If the request is successful, the response struct will be empty" — 200 with an empty object, no envelope', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ ...creds, token }), h: FORM_CT });
+        return r.status === 200 && typeof r.body === 'object' && Object.keys(body(r)).length === 0;
+    })),
+    done('tiktok.revoke.kills_the_access_token', 'revoke', 'A revoked access token no longer answers the Display API (access_token_invalid, 401)', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const before = await h({ m: 'GET', p: '/v2/user/info/?fields=union_id', h: bearer(token) });
+        await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ ...creds, token }), h: FORM_CT });
+        const after = await h({ m: 'GET', p: '/v2/user/info/?fields=union_id', h: bearer(token) });
+        return before.status === 200 && after.status === 401 && apiCode(after) === 'access_token_invalid';
+    })),
+    done('tiktok.revoke.kills_the_grant_pair', 'revoke', 'Revoking the ACCESS half kills the REFRESH half too — "remove this app" disconnects the whole (app, user) grant', 'api', 'core', () => withRoot(async (h) => {
+        const { tokens } = await fullFlow(h);
+        await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ ...creds, token: String(tokens['access_token']) }), h: FORM_CT });
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'refresh_token', refresh_token: String(tokens['refresh_token']) }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'invalid_grant';
+    })),
+    done('tiktok.revoke.unknown_token_succeeds', 'revoke', 'An unknown token answers the same empty success (RFC 7009 §2.2: an app must not be able to probe which tokens exist)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ ...creds, token: 'act.not-a-real-token' }), h: FORM_CT });
+        return r.status === 200 && Object.keys(body(r)).length === 0;
+    })),
+    done('tiktok.revoke.cross_client_no_effect', 'revoke', "Another app's revoke call cannot kill this app's token: the call answers empty success and the token still works", 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_key: 'awthirdapp00000001', client_secret: 'third-secret', name: 'Third App', redirect_uris: [REDIRECT] }) });
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ client_key: 'awthirdapp00000001', client_secret: 'third-secret', token }), h: FORM_CT });
+        const still = await h({ m: 'GET', p: '/v2/user/info/?fields=union_id', h: bearer(token) });
+        return r.status === 200 && still.status === 200 && user(still)['union_id'] === ADA.unionId;
+    })),
+    done('tiktok.revoke.requires_token', 'revoke', 'A revoke without the token field is the vendor\'s own "The request parameters are malformed."', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ ...creds }), h: FORM_CT });
+        return r.status === 400 && body(r)['error'] === 'invalid_request'
+            && body(r)['error_description'] === 'The request parameters are malformed.';
+    })),
+    done('tiktok.revoke.requires_client_auth', 'revoke', 'Revoke authenticates the app exactly as the token endpoint does — a wrong secret is invalid_client, 401', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ client_key: DEFAULT_CLIENT_KEY, client_secret: 'nope', token }), h: FORM_CT });
+        return r.status === 401 && body(r)['error'] === 'invalid_client';
+    })),
+    todo('tiktok.revoke.unknown_token', 'revoke', 'PIN the live answer for an unknown token (the twin follows RFC 7009 §2.2 and answers empty success)', 'api', 'niche'),
+    todo('tiktok.revoke.cross_client', 'revoke', "PIN the live answer when an app revokes another app's token (the twin answers empty success without revoking)", 'api', 'niche'),
+    todo('tiktok.revoke.pair_revocation', 'revoke', 'PIN whether the live revoke kills the whole (app, user) grant or only the named token', 'api', 'common'),
+    todo('tiktok.revoke.refresh_token_hint', 'revoke', 'MODEL revoking by REFRESH token if TikTok accepts one (the documented parameter names the access_token)', 'api', 'niche'),
+    // ═══ client_credentials — the app-only client token ═══════════════════════════════════════
+    done('tiktok.client_credentials.issues_client_token', 'client_credentials', "The app-only grant returns exactly three fields — a `clt.` access_token, expires_in 7200 and token_type Bearer — with no open_id, no scope and no refresh_token", 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'client_credentials' }), h: FORM_CT });
+        return r.status === 200 && String(body(r)['access_token']).startsWith('clt.')
+            && body(r)['expires_in'] === 7200 && body(r)['token_type'] === 'Bearer'
+            && Object.keys(body(r)).length === 3;
+    })),
+    done('tiktok.client_credentials.requires_secret', 'client_credentials', 'The app-only grant is refused without client_secret, with the vendor\'s own example wording', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ client_key: DEFAULT_CLIENT_KEY, grant_type: 'client_credentials' }), h: FORM_CT });
+        return r.status === 400 && body(r)['error_description'] === 'Client secret is missed in request.';
+    })),
+    done('tiktok.client_credentials.not_a_user_token', 'client_credentials', 'A client token is NOT a user token: it cannot read the Display API (access_token_invalid)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'client_credentials' }), h: FORM_CT });
+        const me = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(String(body(r)['access_token'])) });
+        return r.status === 200 && me.status === 401 && apiCode(me) === 'access_token_invalid';
+    })),
+    todo('tiktok.client_credentials.consumers', 'client_credentials', 'MODEL the endpoints a client access token actually reaches (Research API, Commercial Content Library) — the twin issues the token but serves none of them yet', 'api', 'common'),
+    // ═══ user_info — GET open.tiktokapis.com/v2/user/info/ ════════════════════════════════════
+    done('tiktok.user_info.field_selection', 'user_info', 'The `fields` parameter selects exactly what comes back — nothing more, nothing less', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id,display_name', h: bearer(token) });
+        const u = user(r);
+        return ok(r) && Object.keys(u).sort().join(',') === 'display_name,open_id'
+            && u['display_name'] === ADA.displayName && u['open_id'] === ADA_OPEN_ID;
+    })),
+    done('tiktok.user_info.dub_username_read', 'user_info', "The exact call the motivating application makes — GET /v2/user/info/?fields=username with a bearer token — answers data.user.username, the value Dub compares against the partner's declared handle", 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=username', h: bearer(token) });
+        return ok(r) && user(r)['username'] === ADA.username && Object.keys(user(r)).length === 1;
+    })),
+    done('tiktok.user_info.requires_fields', 'user_info', 'The `fields` parameter is REQUIRED; omitting it is invalid_params (400)', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const missing = await h({ m: 'GET', p: '/v2/user/info/', h: bearer(token) });
+        const empty = await h({ m: 'GET', p: '/v2/user/info/?fields=', h: bearer(token) });
+        return missing.status === 400 && apiCode(missing) === 'invalid_params'
+            && empty.status === 400 && apiCode(empty) === 'invalid_params';
+    })),
+    done('tiktok.user_info.invalid_field', 'user_info', 'A field outside the documented table is invalid_params, and the message names it', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id,email_address', h: bearer(token) });
+        return r.status === 400 && apiCode(r) === 'invalid_params' && String(body(r)['error']['message']).includes('email_address');
+    })),
+    done('tiktok.user_info.scope_gated_fields', 'user_info', 'Fields are gated per scope: username needs user.info.profile and follower_count needs user.info.stats — asking without them is scope_not_authorized (401)', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h, { grant: ['user.info.basic'] });
+        const basic = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id,avatar_url,display_name', h: bearer(token) });
+        const profile = await h({ m: 'GET', p: '/v2/user/info/?fields=username', h: bearer(token) });
+        const stats = await h({ m: 'GET', p: '/v2/user/info/?fields=follower_count', h: bearer(token) });
+        return basic.status === 200 && profile.status === 401 && apiCode(profile) === 'scope_not_authorized'
+            && stats.status === 401 && apiCode(stats) === 'scope_not_authorized'
+            && String(body(profile)['error']['message']).includes('user.info.profile');
+    })),
+    done('tiktok.user_info.bearer_required', 'user_info', 'A missing or non-bearer Authorization header is access_token_invalid (401)', 'api', 'core', () => withRoot(async (h) => {
+        const none = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id' });
+        const wrong = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: { authorization: 'Basic abc' } });
+        return none.status === 401 && apiCode(none) === 'access_token_invalid'
+            && wrong.status === 401 && apiCode(wrong) === 'access_token_invalid';
+    })),
+    done('tiktok.user_info.unknown_token', 'user_info', 'An unknown bearer token is access_token_invalid with the vendor\'s own message', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer('act.nope') });
+        return r.status === 401 && apiCode(r) === 'access_token_invalid'
+            && String(body(r)['error']['message']).includes('Please refresh the token and retry');
+    })),
+    done('tiktok.user_info.token_expires', 'user_info', 'An access token stops working after its documented 24 hours', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const inside = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token), at: atPlus(86_000) });
+        const after = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token), at: atPlus(86_401) });
+        return inside.status === 200 && after.status === 401 && apiCode(after) === 'access_token_invalid';
+    })),
+    done('tiktok.user_info.ok_envelope', 'user_info', 'A SUCCESS carries the error object too: {code:"ok", message:"", log_id} beside data — the shape every v2 read returns', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        const e = body(r)['error'];
+        return ok(r) && e.code === 'ok' && e.message === '' && typeof e.log_id === 'string' && e.log_id.length === 34;
+    })),
+    done('tiktok.user_info.all_modeled_fields', 'user_info', 'Every field in the documented table is served with its documented type when the scopes allow it', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const fields = 'open_id,union_id,avatar_url,avatar_url_100,avatar_large_url,display_name,bio_description,profile_deep_link,is_verified,username,follower_count,following_count,likes_count,video_count';
+        const r = await h({ m: 'GET', p: `/v2/user/info/?fields=${fields}`, h: bearer(token) });
+        const u = user(r);
+        return ok(r) && Object.keys(u).length === 14
+            && u['union_id'] === ADA.unionId && u['is_verified'] === ADA.isVerified
+            && u['likes_count'] === ADA.likesCount && u['avatar_large_url'] === ADA.avatarLargeUrl
+            && u['profile_deep_link'] === ADA.profileDeepLink;
+    })),
+    todo('tiktok.user_info.scope_permission_missed', 'user_info', 'MODEL `scope_permission_missed` (400) — the "token lacks the scopes" case the error reference distinguishes from scope_not_authorized', 'api', 'common'),
+    todo('tiktok.user_info.partial_field_errors', 'user_info', 'PIN whether a partially-unauthorized field set returns the authorized fields alongside an error, or refuses the whole read (the twin refuses the whole read)', 'api', 'common'),
+    todo('tiktok.user_info.legacy_v1', 'user_info', 'MODEL the legacy v1 user surface (open-api.tiktok.com /oauth/userinfo/) the migration guide still documents', 'api', 'niche'),
+    // ═══ video — the Display API reads ════════════════════════════════════════════════════════
+    done('tiktok.video.list', 'video', '/v2/video/list/ returns the token owner\'s videos with the requested fields, newest first, in the documented {videos, cursor, has_more} envelope', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/video/list/?fields=id,title,create_time', b: JSON.stringify({}), h: { ...bearer(token), ...JSON_CT } });
+        const vs = videos(r);
+        const newest = [...ADA_VIDEOS].sort((a, b) => b.createTime - a.createTime)[0];
+        return ok(r) && vs.length === ADA_VIDEOS.length && vs[0]['id'] === newest.id
+            && vs[0]['title'] === newest.title
+            && typeof body(r)['data']['cursor'] === 'number' && body(r)['data']['has_more'] === false;
+    })),
+    done('tiktok.video.list_only_owner_videos', 'video', "The list is the TOKEN OWNER's videos — another account's video is never in it", 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({ max_count: 20 }), h: { ...bearer(token), ...JSON_CT } });
+        const ids = videos(r).map((v) => v['id']);
+        const graceVideo = DEFAULT_VIDEOS.find((v) => v.ownerUnionId === GRACE.unionId);
+        return ok(r) && ids.length === ADA_VIDEOS.length && !ids.includes(graceVideo.id);
+    })),
+    done('tiktok.video.list_max_count', 'video', 'max_count defaults to 10 and is capped at 20; a larger or non-integer value is invalid_params', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const one = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({ max_count: 1 }), h: { ...bearer(token), ...JSON_CT } });
+        const tooMany = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({ max_count: 21 }), h: { ...bearer(token), ...JSON_CT } });
+        const zero = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({ max_count: 0 }), h: { ...bearer(token), ...JSON_CT } });
+        return ok(one) && videos(one).length === 1 && body(one)['data']['has_more'] === true
+            && tooMany.status === 400 && apiCode(tooMany) === 'invalid_params'
+            && zero.status === 400 && apiCode(zero) === 'invalid_params';
+    })),
+    done('tiktok.video.list_cursor', 'video', 'The cursor is "a UTC Unix timestamp in milliseconds" that fetches videos posted BEFORE it — paging with the returned cursor walks the account', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const page1 = await h({ m: 'POST', p: '/v2/video/list/?fields=id,create_time', b: JSON.stringify({ max_count: 1 }), h: { ...bearer(token), ...JSON_CT } });
+        const cursor = body(page1)['data']['cursor'];
+        const page2 = await h({ m: 'POST', p: '/v2/video/list/?fields=id,create_time', b: JSON.stringify({ max_count: 1, cursor }), h: { ...bearer(token), ...JSON_CT } });
+        const sorted = [...ADA_VIDEOS].sort((a, b) => b.createTime - a.createTime);
+        return ok(page1) && ok(page2)
+            && videos(page1)[0]['id'] === sorted[0].id
+            && videos(page2)[0]['id'] === sorted[1].id
+            && cursor === sorted[0].createTime * 1000
+            && body(page2)['data']['has_more'] === false;
+    })),
+    done('tiktok.video.requires_video_list_scope', 'video', 'Both video reads need `video.list`; a token without it is scope_not_authorized (401)', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h, { grant: ['user.info.basic'] });
+        const list = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({}), h: { ...bearer(token), ...JSON_CT } });
+        const query = await h({ m: 'POST', p: '/v2/video/query/?fields=id', b: JSON.stringify({ filters: { video_ids: [ADA_VIDEOS[0].id] } }), h: { ...bearer(token), ...JSON_CT } });
+        return list.status === 401 && apiCode(list) === 'scope_not_authorized'
+            && query.status === 401 && apiCode(query) === 'scope_not_authorized';
+    })),
+    done('tiktok.video.query_by_ids', 'video', '/v2/video/query/ returns the named videos in the requested fields, and its envelope has NO cursor or has_more', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const target = ADA_VIDEOS[1];
+        const r = await h({ m: 'POST', p: '/v2/video/query/?fields=id,title,view_count', b: JSON.stringify({ filters: { video_ids: [target.id] } }), h: { ...bearer(token), ...JSON_CT } });
+        return ok(r) && videos(r).length === 1 && videos(r)[0]['id'] === target.id
+            && videos(r)[0]['view_count'] === target.viewCount
+            && Object.keys(body(r)['data']).join(',') === 'videos';
+    })),
+    done('tiktok.video.query_foreign_id_omitted', 'video', "A video id that is not the token owner's is ABSENT from the answer rather than a 404 — the read must not leak whether a foreign video exists", 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const graceVideo = DEFAULT_VIDEOS.find((v) => v.ownerUnionId === GRACE.unionId);
+        const r = await h({ m: 'POST', p: '/v2/video/query/?fields=id', b: JSON.stringify({ filters: { video_ids: [ADA_VIDEOS[0].id, graceVideo.id, '7999999999999999999'] } }), h: { ...bearer(token), ...JSON_CT } });
+        return ok(r) && videos(r).length === 1 && videos(r)[0]['id'] === ADA_VIDEOS[0].id;
+    })),
+    done('tiktok.video.query_id_limit', 'video', '"Up to 20 video IDs can be included per request" — 21 is invalid_params, and an empty or missing filter is too', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const many = Array.from({ length: 21 }, (_, i) => `70000000000000000${String(i).padStart(2, '0')}`);
+        const over = await h({ m: 'POST', p: '/v2/video/query/?fields=id', b: JSON.stringify({ filters: { video_ids: many } }), h: { ...bearer(token), ...JSON_CT } });
+        const none = await h({ m: 'POST', p: '/v2/video/query/?fields=id', b: JSON.stringify({ filters: { video_ids: [] } }), h: { ...bearer(token), ...JSON_CT } });
+        const missing = await h({ m: 'POST', p: '/v2/video/query/?fields=id', b: JSON.stringify({}), h: { ...bearer(token), ...JSON_CT } });
+        return over.status === 400 && apiCode(over) === 'invalid_params'
+            && none.status === 400 && apiCode(none) === 'invalid_params'
+            && missing.status === 400 && apiCode(missing) === 'invalid_params';
+    })),
+    done('tiktok.video.invalid_field', 'video', 'A field outside the Video Object table is invalid_params on both video reads', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/video/list/?fields=id,music_id', b: JSON.stringify({}), h: { ...bearer(token), ...JSON_CT } });
+        return r.status === 400 && apiCode(r) === 'invalid_params' && String(body(r)['error']['message']).includes('music_id');
+    })),
+    done('tiktok.video.all_modeled_fields', 'video', 'Every field in the Video Object table is served, including the derived share_url / embed_link / embed_html and the is_aigc flag', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const fields = 'id,create_time,cover_image_url,share_url,video_description,duration,height,width,title,embed_html,embed_link,like_count,comment_count,share_count,view_count,is_aigc';
+        const r = await h({ m: 'POST', p: `/v2/video/query/?fields=${fields}`, b: JSON.stringify({ filters: { video_ids: [ADA_VIDEOS[0].id] } }), h: { ...bearer(token), ...JSON_CT } });
+        const v = videos(r)[0] ?? {};
+        const id = ADA_VIDEOS[0].id;
+        return ok(r) && Object.keys(v).length === 16
+            && v['share_url'] === `https://www.tiktok.com/@${ADA.username}/video/${id}`
+            && v['embed_link'] === `https://www.tiktok.com/embed/v2/${id}`
+            && String(v['embed_html']).includes(`data-video-id="${id}"`)
+            && v['is_aigc'] === false
+            && v['create_time'] === ADA_VIDEOS[0].createTime;
+    })),
+    done('tiktok.video.malformed_body', 'video', 'A body that is not a JSON object is invalid_params rather than an unhandled crash', 'api', 'niche', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: 'not json at all', h: { ...bearer(token), ...JSON_CT } });
+        return r.status === 400 && apiCode(r) === 'invalid_params';
+    })),
+    todo('tiktok.video.link_shapes', 'video', 'PIN the live CDN/permalink shapes for cover_image_url, share_url, embed_link and embed_html (the twin derives vendor-shaped values from the stored row)', 'api', 'niche'),
+    todo('tiktok.video.cover_image_ttl', 'video', 'MODEL the documented 6-hour TTL on cover_image_url (the twin serves a stable link)', 'api', 'niche'),
+    todo('tiktok.video.query_foreign_id', 'video', "PIN the live answer when a queried video id is not the token owner's (the twin omits it silently)", 'api', 'niche'),
+    todo('tiktok.video.is_aigc_source', 'video', 'PIN where is_aigc comes from and whether it appears for videos posted before the flag existed', 'api', 'niche'),
+    // ═══ scopes catalog ═══════════════════════════════════════════════════════════════════════
+    done('tiktok.scopes.catalog_matches_vendor_list', 'scopes', "The scope ID SET bijects with the vendor's published list — 21 ids across five products, and nothing else (a LITERAL list, so drift in EITHER direction goes red). The three labels the Scopes Overview publishes as scope text are asserted VERBATIM; the other eighteen are twin paraphrases of that page's product prose and are asserted only to be present and non-empty, with tiktok.scopes.consent_wording pinning the live strings", 'api', 'core', async () => {
+        // §9 F3: this used to be titled "…is_vendor_verbatim" while checking 21 ids and 2 labels, with
+        // 18 of the 21 labels being paraphrases — the title claimed more than the assertion or the data
+        // could carry. The ID set really IS the vendor's, verbatim, and that is what this asserts; the
+        // label claim is now scoped to the three the vendor actually publishes as scope text.
+        const PUBLISHED = [
+            'user.info.basic', 'user.info.profile', 'user.info.stats',
+            'video.list', 'video.upload', 'video.publish',
+            'portability.activity.ongoing', 'portability.activity.single',
+            'portability.all.ongoing', 'portability.all.single',
+            'portability.directmessages.ongoing', 'portability.directmessages.single',
+            'portability.postsandprofile.ongoing', 'portability.postsandprofile.single',
+            'research.data.basic', 'research.data.u18eu', 'research.data.vra', 'research.adlib.basic',
+            'local.product.manage', 'local.shop.manage', 'local.voucher.manage',
+        ].sort();
+        // The THREE the Scopes Overview publishes as scope text, word for word.
+        const VERBATIM = {
+            'user.info.basic': "Read a user's profile info (open id, avatar, display name...)",
+            'user.info.profile': 'Read access to profile_web_link, profile_deep_link, bio_description, is_verified',
+            'video.list': "Read a user's public videos on TikTok",
+        };
+        const { SCOPE_CATALOG } = await import("./tiktok-scopes.js");
+        const have = Object.keys(SCOPE_CATALOG).sort();
+        return have.join(',') === PUBLISHED.join(',')
+            && Object.entries(VERBATIM).every(([id, label]) => SCOPE_CATALOG[id].label === label)
+            && have.every((id) => (SCOPE_CATALOG[id].label ?? '').trim().length > 0);
+    }),
+    done('tiktok.scopes.comma_separated', 'scopes', 'The scope parameter is COMMA-separated on the wire, and the token response echoes it comma-joined with no spaces', 'api', 'core', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { params: { scope: 'user.info.basic,video.list' } });
+        return r.status === 200 && r.tokens['scope'] === 'user.info.basic,video.list';
+    })),
+    done('tiktok.scopes.space_separated_is_not_a_list', 'scopes', "A space-separated scope string — the X/Google spelling — is ONE unknown scope here, not a list, and is refused as invalid_scope", 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: authUrl({ scope: 'user.info.basic user.info.profile' }) });
+        return r.status === 302 && qp(r, 'error') === 'invalid_scope';
+    })),
+    done('tiktok.scopes.unknown_scope_is_not_granted', 'scopes', 'A mixed request renders, but an unknown scope can never be granted: it is absent from the callback `scopes` and from the token', 'api', 'common', () => withRoot(async (h) => {
+        const r = await fullFlow(h, { params: { scope: 'user.info.basic,totally.bogus' }, grant: ['user.info.basic', 'totally.bogus'] });
+        return r.status === 200 && r.tokens['scope'] === 'user.info.basic';
+    })),
+    todo('tiktok.scopes.consent_wording', 'scopes', "PIN the live consent sheet's per-scope strings (the twin renders the developer-facing descriptions the Scopes Overview publishes)", 'ui', 'common'),
+    todo('tiktok.scopes.unknown_scope_live', 'scopes', 'PIN what the live authorize endpoint does with an unknown scope alongside known ones (the twin renders it flagged rather than inventing a rejection)', 'api', 'niche'),
+    todo('tiktok.scopes.app_approval_state', 'scopes', "MODEL the developer-portal side: a scope the APP was never approved for is refused before the user ever sees it", 'api', 'common'),
+    // ═══ errors ═══════════════════════════════════════════════════════════════════════════════
+    done('tiktok.errors.two_envelopes', 'errors', 'The OAuth endpoints speak the FLAT {error, error_description, log_id} body and the v2 API speaks the NESTED {error:{code, message, log_id}} one — two contracts, never mixed', 'api', 'core', () => withRoot(async (h) => {
+        const oauth = await h({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'password' }), h: FORM_CT });
+        const api = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer('act.nope') });
+        const o = body(oauth);
+        const a = body(api);
+        return typeof o['error'] === 'string' && typeof o['error_description'] === 'string' && typeof o['log_id'] === 'string'
+            && typeof a['error'] === 'object' && typeof a['error']['code'] === 'string' && typeof a['error']['message'] === 'string' && typeof a['error']['log_id'] === 'string';
+    })),
+    done('tiktok.errors.log_id_shape', 'errors', "Every response carries a log_id in the vendor's own shape (14 digits of UTC yyyyMMddHHmmss plus 20 uppercase hex) and it is DETERMINISTIC, not a clock read", 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const first = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        const second = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        const id = String(body(first)['error']['log_id']);
+        return /^20260201000000[0-9A-F]{20}$/.test(id) && body(second)['error']['log_id'] === id;
+    })),
+    done('tiktok.errors.api_status_matches_code', 'errors', "Each nested error code carries the HTTP status the vendor's own table gives it: access_token_invalid 401, invalid_params 400, scope_not_authorized 401, rate_limit_exceeded 429", 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h, { grant: ['user.info.basic'] });
+        const bad = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer('act.nope') });
+        const params = await h({ m: 'GET', p: '/v2/user/info/?fields=nope', h: bearer(token) });
+        const scope = await h({ m: 'GET', p: '/v2/user/info/?fields=username', h: bearer(token) });
+        await h({ m: 'POST', p: '/_twin/rate_limit', b: JSON.stringify({ endpoint: 'user_info', open_id: ADA_OPEN_ID, used: 600 }) });
+        const rate = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        return bad.status === 401 && params.status === 400 && scope.status === 401 && rate.status === 429
+            && apiCode(rate) === 'rate_limit_exceeded';
+    })),
+    done('tiktok.errors.unknown_route_refuses', 'errors', 'An unmodelled open-API route fails like the vendor rather than faking a success — a named refusal, never a 2xx', 'api', 'core', () => withRoot(async (h) => {
+        const post = await h({ m: 'POST', p: '/v2/post/publish/content/init/', b: '{}' });
+        const research = await h({ m: 'POST', p: '/v2/research/video/query/', b: '{}' });
+        return post.status === 400 && apiCode(post) === 'invalid_params'
+            && String(body(post)['error']['message']).includes('not a TikTok open API endpoint')
+            && research.status === 400 && apiCode(research) === 'invalid_params';
+    })),
+    done('tiktok.errors.malformed_request_contained', 'errors', "A residual TypeError on the authorize path is contained as the vendor's own flat 400 envelope, never a non-vendor 500 and never an HTML surprise", 'api', 'niche', () => withRoot(async (h) => {
+        // §9 F1: the previous version of this verify (a hostile percent-encoding in client_key) never
+        // reached the guard at all — URLSearchParams does not throw, so it took the ordinary
+        // unknown-client 401 branch and the capability was a false green. THIS reaches it: an app
+        // registered with an UNPARSEABLE callback passes the exact-match boundary, and the bounce
+        // then calls `new URL(redirectUri)`, which throws TypeError inside the router.
+        await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_key: 'awbadcallback00001', client_secret: 's', name: 'Bad Callback App', redirect_uris: ['not-a-url'] }) });
+        const r = await h({ m: 'GET', p: authUrl({ client_key: 'awbadcallback00001', redirect_uri: 'not-a-url', response_type: undefined }) });
+        const b = body(r);
+        // The control: with a PARSEABLE registered callback the same request bounces normally, so a
+        // handler that 400'd everything could not pass this.
+        const control = await h({ m: 'GET', p: authUrl({ response_type: undefined }) });
+        return r.status === 400
+            && typeof r.body === 'object'
+            && b['error'] === 'invalid_request'
+            && b['error_description'] === 'The request parameters are malformed.'
+            && typeof b['log_id'] === 'string' && String(b['log_id']).length === 34
+            && control.status === 302 && qp(control, 'error') === 'invalid_request';
+    })),
+    done('tiktok.errors.oauth_codes_are_vendor_verbatim', 'errors', "The ten OAuth error codes AND all ten of their descriptions are the vendor's published list, word for word (a LITERAL map comparison, so a dropped clause goes red)", 'api', 'common', async () => {
+        // §9 F3: this used to spot-check two of the ten, and the gap it hid was real — `invalid_grant`
+        // had lost the vendor's own "(for example, authorization code or resource owner credentials)"
+        // parenthetical. The whole map is compared now.
+        const { OAUTH_ERRORS } = await import("./tiktok-errors.js");
+        const PUBLISHED = {
+            access_denied: 'The resource owner or authorization server denied the request.',
+            invalid_client: 'Client authentication failed (for example, unknown client, no client authentication included, or unsupported authentication method).',
+            invalid_grant: 'The provided authorization grant (for example, authorization code or resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.',
+            invalid_request: 'The request misses a required parameter or is otherwise malformed.',
+            invalid_scope: 'The requested scope is invalid, unknown, or malformed.',
+            unauthorized_client: 'The client is not authorized to request an authorization code using this method.',
+            unsupported_grant_type: 'The authorization grant type is not supported by the authorization server.',
+            unsupported_response_type: 'The authorization server does not support obtaining an authorization code using this method.',
+            server_error: 'Other internal server errors.',
+            temporarily_unavailable: 'Service is temporarily unavailable.',
+        };
+        return Object.keys(OAUTH_ERRORS).sort().join(',') === Object.keys(PUBLISHED).sort().join(',')
+            && Object.entries(PUBLISHED).every(([code, text]) => OAUTH_ERRORS[code] === text);
+    }),
+    done('tiktok.errors.api_codes_and_statuses_match_vendor_table', 'errors', "The seven v2 error codes and their documented HTTP statuses are the vendor's published table, verbatim; the four messages that table quotes are asserted word for word, and the other three are twin prose the reference only describes", 'api', 'common', async () => {
+        const { API_ERRORS } = await import("./tiktok-errors.js");
+        const PUBLISHED = {
+            access_token_invalid: 401, internal_error: 500, invalid_file_upload: 400, invalid_params: 400,
+            rate_limit_exceeded: 429, scope_not_authorized: 401, scope_permission_missed: 400,
+        };
+        // The four the reference quotes as messages rather than describing.
+        const QUOTED = {
+            access_token_invalid: 'The access token is invalid or not found in the request. Please refresh the token and retry.',
+            invalid_file_upload: 'The uploaded file does not meet API specifications. Please correct the file and try again.',
+            rate_limit_exceeded: 'The API rate limit was exceeded. Please try again later.',
+            scope_not_authorized: 'The user did not authorize the scope required for completing this request. Please ask the user to authorize and then retry.',
+        };
+        return Object.keys(API_ERRORS).sort().join(',') === Object.keys(PUBLISHED).sort().join(',')
+            && Object.entries(PUBLISHED).every(([code, status]) => API_ERRORS[code].status === status)
+            && Object.entries(QUOTED).every(([code, text]) => API_ERRORS[code].message === text);
+    }),
+    todo('tiktok.errors.unknown_route_pin', 'errors', "PIN the live answer for an unrouted path on open.tiktokapis.com (the twin answers the API family's invalid_params naming the route)", 'api', 'niche'),
+    todo('tiktok.errors.internal_error_pin', 'errors', 'PIN the live internal_error body and whether it carries a retry hint', 'api', 'niche'),
+    // ═══ rate limiting ════════════════════════════════════════════════════════════════════════
+    done('tiktok.rate.limit_exceeded_429', 'rate', 'Exceeding the documented 600-per-minute limit answers "HTTP status 429 and error code rate_limit_exceeded"', 'api', 'core', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        await h({ m: 'POST', p: '/_twin/rate_limit', b: JSON.stringify({ endpoint: 'user_info', open_id: ADA_OPEN_ID, used: 600 }) });
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        return r.status === 429 && apiCode(r) === 'rate_limit_exceeded'
+            && String(body(r)['error']['message']).includes('rate limit was exceeded');
+    })),
+    done('tiktok.rate.limits_are_per_endpoint', 'rate', '"Limits for each API are set and enforced separately": exhausting /v2/user/info/ leaves /v2/video/list/ serving', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        await h({ m: 'POST', p: '/_twin/rate_limit', b: JSON.stringify({ endpoint: 'user_info', open_id: ADA_OPEN_ID, used: 600 }) });
+        const blocked = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        const served = await h({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({}), h: { ...bearer(token), ...JSON_CT } });
+        return blocked.status === 429 && served.status === 200;
+    })),
+    done('tiktok.rate.sliding_window_rolls', 'rate', 'The window is one minute: a request past it is served again, with the count restarted', 'api', 'common', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        await h({ m: 'POST', p: '/_twin/rate_limit', b: JSON.stringify({ endpoint: 'user_info', open_id: ADA_OPEN_ID, used: 600 }) });
+        const inside = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token), at: atPlus(30) });
+        const after = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token), at: atPlus(61) });
+        return inside.status === 429 && after.status === 200;
+    })),
+    done('tiktok.rate.no_headers_invented', 'rate', "TikTok's rate-limit reference publishes NO response headers, so the twin invents none — a client cannot be taught to read a header the vendor does not send", 'api', 'niche', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const r = await h({ m: 'GET', p: '/v2/user/info/?fields=open_id', h: bearer(token) });
+        const names = Object.keys(r.headers ?? {}).map((k) => k.toLowerCase());
+        return ok(r) && !names.some((n) => n.includes('ratelimit') || n.includes('rate-limit'));
+    })),
+    todo('tiktok.rate.what_counts', 'rate', 'PIN what the live meter counts (refused requests? unauthorized ones?) — the twin spends only on a served success', 'api', 'common'),
+    todo('tiktok.rate.limit_dimension', 'rate', 'PIN whether the published 600/minute is per client key, per user access token or per app+user — the reference states the window and the number but not the dimension (the twin meters per (endpoint, open_id))', 'api', 'common'),
+    todo('tiktok.rate.oauth_endpoint_limits', 'rate', 'PIN the rate limits on the OAuth token/revoke endpoints — the reference lists only the three Display API rows', 'api', 'niche'),
+    // ═══ read-only twin ═══════════════════════════════════════════════════════════════════════
+    done('tiktok.readonly.writes_refused', 'readonly', 'A read-only twin refuses every credential-minting leg (405, the vendor\'s temporarily_unavailable) — D3', 'api', 'common', () => withRoot(async (h) => {
+        await fullFlow(h); // seed a world first, through the ordinary write path
+        const ro = (s) => handleTikTokTwinRequest({ method: s.m, path: s.p, ...(s.b !== undefined ? { body: s.b } : {}), ...(s.h ? { headers: s.h } : {}), root: h.root, origin: DEMO_ORIGIN, occurredAt: AT, readOnly: true });
+        const tok = await ro({ m: 'POST', p: '/v2/oauth/token/', b: form({ ...creds, grant_type: 'authorization_code', code: 'x', redirect_uri: REDIRECT }), h: FORM_CT });
+        const rev = await ro({ m: 'POST', p: '/v2/oauth/revoke/', b: form({ ...creds, token: 'x' }), h: FORM_CT });
+        const auth = await ro({ m: 'GET', p: authUrl() });
+        return tok.status === 405 && body(tok)['error'] === 'temporarily_unavailable' && rev.status === 405 && auth.status === 405;
+    })),
+    done('tiktok.readonly.reads_served', 'readonly', 'A read-only twin still serves the Display API over existing state, with rate accounting suspended', 'api', 'niche', () => withRoot(async (h) => {
+        const token = await accessToken(h);
+        const ro = (s) => handleTikTokTwinRequest({ method: s.m, path: s.p, ...(s.b !== undefined ? { body: s.b } : {}), ...(s.h ? { headers: s.h } : {}), root: h.root, origin: DEMO_ORIGIN, occurredAt: AT, readOnly: true });
+        const me = await ro({ m: 'GET', p: '/v2/user/info/?fields=union_id', h: bearer(token) });
+        const list = await ro({ m: 'POST', p: '/v2/video/list/?fields=id', b: JSON.stringify({}), h: { ...bearer(token), ...JSON_CT } });
+        return me.status === 200 && me.body.data.user.union_id === ADA.unionId && list.status === 200;
+    })),
+    // ═══ conformance (the endpoint census with teeth) ═════════════════════════════════════════
+    done('tiktok.conformance.census', 'conformance', 'The conformance check passes: one real probe per claimed endpoint, the ROUTER_SURFACE census, the live round trip, and a reachability witness per resource type', 'api', 'core', async () => {
+        const report = await checkTikTokConformance();
+        return report.ok && report.endpointsProbed === 11 && report.resourceTypesChecked === 12;
+    }),
+    // ═══ the authorization PAGE (the vendor's own UI — data-coupled, per ADDING_A_TWIN.md §6) ══
+    done('tiktok.ui.authorization_page', 'ui', 'The page names the REGISTERED app and the SIGNED-IN account from the projection (data-coupled: a seeded app + persona appear on screen)', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        // Seed a THIRD persona and a SECOND app through the twin's own write paths, then sign the new
+        // persona in — the screen cannot be passing on the seeded defaults alone.
+        seed: async (h) => {
+            await h({ m: 'POST', p: '/_twin/clients', b: JSON.stringify({ client_key: 'awacmescheduler001', client_secret: 'acme-secret', name: 'Acme Scheduling', redirect_uris: [REDIRECT] }) });
+            await h({ m: 'POST', p: '/_twin/accounts', b: JSON.stringify({ union_id: '00000000-0000-4000-8000-000000000003', username: 'katherine_twin', display_name: 'Katherine Johnson' }) });
+            await h({ m: 'POST', p: '/_twin/session', b: JSON.stringify({ union_id: '00000000-0000-4000-8000-000000000003' }) });
+        },
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ client_key: 'awacmescheduler001' }) })),
+        assert: (markup) => markup.includes('Acme Scheduling')
+            && markup.includes('would like to access your TikTok account')
+            && markup.includes('Katherine Johnson') && markup.includes('@katherine_twin')
+            && !markup.includes('Twin Demo App') && !markup.includes('@ada_twin'),
+    })),
+    done('tiktok.ui.scope_checkboxes', 'ui', "Each requested scope renders as its OWN checkbox carrying the scope id as its value, with the vendor's published wording (data-coupled to the auth request)", 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ scope: 'user.info.basic,video.list' }) }),
+        // §9 nit: read the VENDOR's own path. The twin-only `/_twin/consent` re-render door serves the
+        // same component from the same state builder, so asserting there proved the screen but not the
+        // ROUTE a browser is actually redirected to.
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ scope: 'user.info.basic,video.list' }) })),
+        assert: (markup) => (markup.match(/name="scope"/g) ?? []).length === 2
+            && markup.includes('value="user.info.basic"')
+            && markup.includes('value="video.list"')
+            && markup.includes("Read a user&#x27;s profile info (open id, avatar, display name...)")
+            && markup.includes("Read a user&#x27;s public videos on TikTok")
+            && !markup.includes('value="user.info.stats"'),
+    })),
+    done('tiktok.ui.decision_buttons', 'ui', 'The page\'s two decisions are REAL form submits — Continue and Cancel carry decision values into the twin\'s consent post', 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl() }),
+        // §9 nit: the VENDOR's own path, not the twin-only re-render door.
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl() })),
+        // Attribute ORDER is the renderer's business (React emits value before name) — assert each
+        // decision button as a whole tag, order-independent within it.
+        assert: (markup) => /<button[^>]*value="allow"[^>]*>Continue<\/button>/.test(markup)
+            && /<button[^>]*value="deny"[^>]*>Cancel<\/button>/.test(markup)
+            && (markup.match(/name="decision"/g) ?? []).length === 2
+            && markup.includes('/_twin/consent'),
+    })),
+    done('tiktok.ui.redirect_notice', 'ui', "The page shows WHERE the browser will be sent — the validated redirect_uri's host, from the auth request (data-coupled: the SECOND registered callback's host, so a hardcoded first/default host fails)", 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ redirect_uri: REDIRECT_URIS[1] }) }),
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ redirect_uri: REDIRECT_URIS[1] }) })),
+        // The assertion is pinned to the NOTICE ELEMENT itself rather than the whole page: the twin
+        // is served at the first callback's origin, so that host also appears in the consent form's
+        // own action — a whole-markup `!includes` would fail for a reason unrelated to coupling.
+        assert: (markup) => markup.includes('redirected to')
+            && markup.includes(`class="redirect-host">${new URL(REDIRECT_URIS[1]).host}<`)
+            && !markup.includes(`class="redirect-host">${new URL(REDIRECT_URIS[0]).host}<`),
+    })),
+    done('tiktok.ui.unknown_scope_flagged', 'ui', 'A scope outside the vendor catalog renders VISIBLY FLAGGED rather than silently or prettily (a typo\'d scope is a real integration bug)', 'ui', 'common', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ scope: 'user.info.basic,totally.bogus' }) }),
+        fetch: async (h) => html(await h({ m: 'GET', p: authUrl({ scope: 'user.info.basic,totally.bogus' }) })),
+        assert: (markup) => markup.includes('totally.bogus') && markup.includes('not in the twin&#x27;s scope catalog'),
+    })),
+    done('tiktok.ui.consent_state_renders_real_component', 'ui', "The SHIPPED ConsentPage component renders the twin's OWN view model (the same state builder the served page uses) — one renderer, no lookalike", 'ui', 'core', uiDataCoupled({
+        withRoot,
+        seed: (h) => h({ m: 'GET', p: authUrl({ scope: 'user.info.basic,user.info.profile' }) }),
+        // The handle comes off the VENDOR path (§9 nit); the view model is then read from the state
+        // builder on purpose — proving the SHIPPED component renders the twin's own projection is
+        // this capability's whole claim, and `tiktok.ui.scope_checkboxes` above asserts the served
+        // bytes of that same route.
+        fetch: async (h) => {
+            const a = await h({ m: 'GET', p: authUrl({ scope: 'user.info.basic,user.info.profile' }) });
+            const rid = AUTH_REQUEST_RE.exec(html(a))?.[1] ?? '';
+            return tiktokConsentState({ root: h.root, requestId: rid, origin: 'https://www.tiktok.com' });
+        },
+        render: (view) => (view ? renderToStaticMarkup(createElement(ConsentPage, { view })) : ''),
+        assert: (view, markup) => !!view && !!markup
+            && view.scopes.length === 2
+            && view.account.username === ADA.username
+            && view.app.name === 'Twin Demo App'
+            && markup.includes(`@${ADA.username}`)
+            && markup.includes('Read access to profile_web_link, profile_deep_link, bio_description, is_verified'),
+    })),
+    done('tiktok.ui.error_page_renders_real_component', 'ui', 'The authorize endpoint SERVES the real ErrorPage component for an un-redirectable failure (driven through the handler, not a lookalike render)', 'ui', 'common', () => withRoot(async (h) => {
+        const served = await h({ m: 'GET', p: authUrl({ client_key: 'awnotarealapp00001' }) });
+        // The SERVED page must literally CONTAIN the real component's own render for the same
+        // failure facts — a hand-rolled template carrying the same headline strings cannot pass.
+        const direct = renderToStaticMarkup(createElement(ErrorPage, {
+            status: 401,
+            code: 'invalid_client',
+            detail: 'The client_key does not name a known TikTok app.',
+            requestParam: 'client_key=awnotarealapp00001',
+        }));
+        return served.status === 401 && html(served).includes('Something went wrong') && html(served).includes(direct);
+    })),
+    done('tiktok.ui.page_needs_no_javascript', 'ui', 'The whole decision is a plain form: the served page carries no script tag, so curl, a redirect-following library and a headless browser all complete the flow identically', 'ui', 'niche', () => withRoot(async (h) => {
+        const page = await h({ m: 'GET', p: authUrl() });
+        const markup = html(page);
+        // Attribute ORDER is the renderer's business (React emits className first), so the form is
+        // matched as a whole tag rather than as a literal prefix.
+        return page.status === 200 && !markup.includes('<script')
+            && /<form[^>]*method="POST"[^>]*>/.test(markup) && markup.includes('type="submit"')
+            && markup.includes('<style>') && markup.includes('.scope-check');
+    })),
+    // ═══ the MIRROR (tiktok.com's profile and player over the twin's own API — every one DATA-COUPLED:
+    // seed and post through the handler, read the SAME routes the screen reads, render the mirror's OWN
+    // components over them) ══════════════════════════════════════════════════════════════════════
+    done('tiktok.mirror.profile_header', 'ui', "The profile header renders the creator /v2/user/info/ returns — @username, nickname, the verified tick, the Following / Followers / Likes counts in tiktok.com's compact form and the bio — and draws NO count the read did not return", 'ui', 'core', () => withPosting(async (p) => {
+        const seed = async (json) => p.call('/_twin/accounts', json);
+        await seed({ union_id: '22222222-2222-4222-8222-222222222222', username: 'counted', display_name: 'Counted Creator', is_verified: true, follower_count: 12840, following_count: 12, likes_count: 1_450_000, bio_description: 'Release videos.' });
+        await seed({ union_id: '33333333-3333-4333-8333-333333333333', username: 'bare', display_name: 'Bare Creator' });
+        const tokenFor = async (id) => String(body(await p.call('/_twin/tokens', { union_id: id, scopes: ['user.info.basic', 'user.info.profile', 'user.info.stats'] })).access_token);
+        const readGet = async (id) => body(await handleTikTokTwinRequest({ method: 'GET', path: `/v2/user/info/?fields=${MIRROR_PROFILE_FIELDS}`, headers: { authorization: `Bearer ${await tokenFor(id)}` }, root: p.root, occurredAt: AT })).data?.user;
+        const counted = await readGet('22222222-2222-4222-8222-222222222222');
+        const bare = await readGet('33333333-3333-4333-8333-333333333333');
+        if (!counted || !bare)
+            return false;
+        const a = renderToStaticMarkup(createElement(ProfileHeader, { user: counted, own: true }));
+        const b = renderToStaticMarkup(createElement(ProfileHeader, { user: bare, own: true }));
+        return a.includes('>counted</h1>') && a.includes('Counted Creator') && a.includes('Verified account')
+            && a.includes('<strong>12</strong><span class="stat-label">Following</span>') && a.includes('<strong>12.8K</strong><span class="stat-label">Followers</span>')
+            && a.includes('<strong>1.4M</strong><span class="stat-label">Likes</span>') && a.includes('Release videos.') && a.includes('Edit profile')
+            && b.includes('>bare</h1>') && !b.includes('Followers') && !b.includes('Likes') && !b.includes('Verified account');
+    })),
+    done('tiktok.mirror.video_grid', 'ui', "The Videos grid renders the creator's posts /v2/video/list/ returns, newest first, each tile the post's own bytes from the twin's media route (with the creator's token) and its play count", 'ui', 'core', () => withPosting(async (p) => {
+        const first = await p.publish(SMALL, SMALL.length, 'PUBLIC_TO_EVERYONE');
+        const second = await p.publish(pattern(3000), 3000, 'SELF_ONLY');
+        const listed = await p.call(`/v2/video/list/?fields=${MIRROR_VIDEO_FIELDS}`, { max_count: 20 }, undefined, atPlus(600));
+        const videos = (body(listed).data?.videos ?? []);
+        const markup = renderToStaticMarkup(createElement(VideoGrid, { videos, sourceOf: (id) => mediaSource('/w', id, p.token), onOpen: () => { } }));
+        const src = (id) => `src="/w/_twin/media/video/${id}?access_token=${encodeURIComponent(p.token)}#t=0.1"`;
+        const played = await p.media(second.postId, {}, atPlus(600), p.token);
+        return videos.map((v) => v.id).join(',') === `${second.postId},${first.postId}`
+            && markup.indexOf(`data-video-id="${second.postId}"`) < markup.indexOf(`data-video-id="${first.postId}"`)
+            && markup.includes(src(first.postId)) && markup.includes(src(second.postId))
+            && (markup.match(/class="tile-views"/g) ?? []).length === 2
+            && played.status === 200 && sameBytes(await bytesOf(played.body), pattern(3000));
+    })),
+    done('tiktok.mirror.vertical_player', 'ui', "The player renders a posted video's caption (its #hashtags bolded), the @handle, the sound line and the action rail with the Video Object's own counts — and no count where the API returns none", 'ui', 'core', () => withPosting(async (p) => {
+        await p.init('direct', SMALL.length, SMALL.length, 1, { title: 'Launch day #release @poster' }).then(async (init) => {
+            await p.put(String(body(init).data?.upload_url), SMALL, `bytes 0-${SMALL.length - 1}/${SMALL.length}`);
+        });
+        const video = (body(await p.call(`/v2/video/list/?fields=${MIRROR_VIDEO_FIELDS}`, { max_count: 1 }, undefined, atPlus(600))).data?.videos ?? [])[0];
+        const me = body(await handleTikTokTwinRequest({ method: 'GET', path: '/v2/user/info/?fields=open_id,union_id,display_name', headers: { authorization: `Bearer ${p.token}` }, root: p.root, occurredAt: atPlus(600) })).data?.user;
+        if (!video || !me)
+            return false;
+        const user = { ...me, username: 'poster' };
+        const caption = renderToStaticMarkup(createElement(PlayerCaption, { user, video }));
+        const rail = renderToStaticMarkup(createElement(ActionRail, { user, video }));
+        return caption.includes('@poster') && caption.includes('<strong class="tag">#release</strong>') && caption.includes('<strong class="tag">@poster</strong>')
+            && caption.includes('Launch day ') && caption.includes('original sound - The Poster')
+            && (rail.match(/<strong>0<\/strong>/g) ?? []).length === 3 && rail.includes('<strong></strong>');
+    })),
+    done('tiktok.mirror.serves_the_vendor_api_on_its_own_origin', 'ui', 'The mirror origin serves the shell (base href, relative assets, #/ routes) and the REAL TikTok handler behind it — the Display API read, the Content Posting init and the upload PUT on one origin, one serving code path', 'ui', 'core', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-cap-mirror-'));
+        const server = await createTiktokMirrorServer({ root, port: 0 });
+        try {
+            const json = { 'content-type': 'application/json' };
+            await fetch(`${server.url}/_twin/accounts`, { method: 'POST', headers: json, body: JSON.stringify({ union_id: POSTER, username: 'origin', display_name: 'Origin' }) });
+            const token = String((await (await fetch(`${server.url}/_twin/tokens`, { method: 'POST', headers: json, body: JSON.stringify({ union_id: POSTER, scopes: ['user.info.basic', 'user.info.profile', 'video.publish'] }) })).json()).access_token);
+            const auth = { authorization: `Bearer ${token}`, ...json };
+            const me = (await (await fetch(`${server.url}/v2/user/info/?fields=username`, { headers: auth })).json());
+            const init = (await (await fetch(`${server.url}/v2/post/publish/video/init/`, { method: 'POST', headers: auth, body: JSON.stringify({ post_info: { privacy_level: 'SELF_ONLY' }, source_info: { source: 'FILE_UPLOAD', video_size: SMALL.length, chunk_size: SMALL.length, total_chunk_count: 1 } }) })).json());
+            const uploadUrl = String(init.data?.upload_url ?? '');
+            const put = await fetch(uploadUrl, { method: 'PUT', headers: { 'content-type': 'video/mp4', 'content-range': `bytes 0-${SMALL.length - 1}/${SMALL.length}` }, body: SMALL });
+            const shell = await (await fetch(`${server.url}/`)).text();
+            const css = await fetch(`${server.url}/assets/styles.css`);
+            return me.data?.user?.username === 'origin' && uploadUrl.startsWith(`${server.url}/video/?upload_id=`) && put.status === 201
+                && shell.includes('<base href="/">') && shell.includes('<div id="root">') && shell.includes('src="assets/app.js"') && css.status === 200;
+        }
+        finally {
+            server.stop();
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('tiktok.mirror.hosted_mount_exports', 'ui', "The module the hosted mirror mount reads exports the shell (a <base href=\"/\"> it rewrites and relative assets/ it remaps), a client bundle that BUILDS for the browser, and the stylesheet", 'ui', 'common', async () => {
+        const html = tiktokMirrorHtml();
+        const css = await tiktokMirrorStyles();
+        const client = await buildTiktokMirrorClient();
+        return html.includes('<base href="/">') && html.includes('href="assets/styles.css"') && html.includes('src="assets/app.js"')
+            && css.includes('.player-frame') && css.includes('aspect-ratio: 9 / 16') && client.length > 1000;
+    }),
+    // ═══ connector (dimension: connector — the saboteur phase keys on this) ═══════════════════
+    done('tiktok.connector.pull_identity', 'connector', "Pull observes the real account behind the operator's token (a real-shaped /v2/user/info/ reply over an injected fake) and folds it into the twin, keyed by union_id", 'connector', 'core', async () => verifyBoundary('tiktok.connector.pull_identity', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-conn-'));
+        try {
+            const n = await pullTikTok(fakeExecute, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            const { readOne } = await import("./tiktok-store.js");
+            const row = readOne(root, 'account', 'c9c60f44-a68e-4f5d-84dd-ce22faeb0ba1');
+            return n === 1 && row?.username === 'tiktokdev' && row?.displayName === 'TikTok Developers'
+                && row?.followerCount === 583_423 && row?.isVerified === true && row?.pulled === true;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.pull_idempotent', 'connector', 'A re-pull of identical vendor state appends NOTHING (shadow-diffed sync; deltasAppended 0 on the second pass)', 'connector', 'core', async () => verifyBoundary('tiktok.connector.pull_idempotent', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-conn-'));
+        try {
+            const first = await syncTikTokFromReal(fakeExecute, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            const second = await syncTikTokFromReal(fakeExecute, { root, occurredAt: '2026-02-01T00:00:02.000Z' });
+            return first.deltasAppended > 0 && second.deltasAppended === 0 && second.observed === 1;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.pull_requests_modeled_fields', 'connector', 'The pull asks for every modelled user field (a default-field pull would silently observe a bald persona) and narrows on request', 'connector', 'common', async () => verifyBoundary('tiktok.connector.pull_requests_modeled_fields', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-conn-'));
+        const seen = [];
+        const recording = async (m, p) => {
+            seen.push(`${m} ${p}`);
+            return structuredClone(FAKE_USER_INFO);
+        };
+        try {
+            await pullTikTok(recording, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            await pullTikTok(recording, { root, occurredAt: '2026-02-01T00:00:02.000Z', userFields: ['open_id', 'union_id'] });
+            const wide = seen[0] ?? '';
+            const narrow = seen[1] ?? '';
+            return seen.length === 2
+                && wide.startsWith('GET /v2/user/info/?fields=')
+                && ['open_id', 'union_id', 'avatar_large_url', 'bio_description', 'is_verified', 'follower_count', 'video_count'].every((f) => wide.includes(f))
+                && narrow === 'GET /v2/user/info/?fields=open_id,union_id';
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.pull_videos_opt_in', 'connector', 'Videos are pulled only when asked for — the video reads need the separate video.list scope, so a default pull observes the account and nothing else', 'connector', 'common', async () => verifyBoundary('tiktok.connector.pull_videos_opt_in', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-conn-'));
+        const seen = [];
+        const recording = async (m, p) => {
+            seen.push(`${m} ${p.split('?')[0]}`);
+            return p.startsWith('/v2/video/list') ? structuredClone(FAKE_VIDEO_LIST) : structuredClone(FAKE_USER_INFO);
+        };
+        try {
+            const withoutVideos = await pullTikTok(recording, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            const withVideos = await pullTikTok(recording, { root, occurredAt: '2026-02-01T00:00:02.000Z', videos: true });
+            const { readOne } = await import("./tiktok-store.js");
+            const video = readOne(root, 'video', '7010000000000000001');
+            return withoutVideos === 1 && withVideos === 2
+                && seen.filter((s) => s.includes('/v2/video/list')).length === 1
+                && video?.ownerUnionId === 'c9c60f44-a68e-4f5d-84dd-ce22faeb0ba1'
+                && video?.viewCount === 900 && video?.pulled === true;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.refused_pull_throws', 'connector', "A REFUSED pull is NOT an empty account: TikTok's nested error object arrives even under HTTP 200, so a non-ok code THROWS instead of folding emptiness over observed state", 'connector', 'core', async () => verifyBoundary('tiktok.connector.refused_pull_throws', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-conn-'));
+        const refusing = async () => ({ data: {}, error: { code: 'scope_not_authorized', message: 'The user did not authorize the scope', log_id: '20260201000000AAAAAAAAAAAAAAAAAAAAAA' } });
+        try {
+            // The HAPPY path must still work first — otherwise a dead connector that throws on
+            // EVERYTHING would satisfy the refusal expectation below.
+            const n = await pullTikTok(fakeExecute, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            if (n !== 1)
+                return false;
+            await pullTikTok(refusing, { root, occurredAt: '2026-02-01T00:00:02.000Z' });
+            return false; // the refusal must throw
+        }
+        catch (e) {
+            if (!String(e).includes('refused'))
+                return false;
+            const { readOne, readType } = await import("./tiktok-store.js");
+            // The earlier good pull SURVIVES the refused one — nothing was folded over it.
+            return readType(root, 'account').length === 1
+                && readOne(root, 'account', 'c9c60f44-a68e-4f5d-84dd-ce22faeb0ba1')?.username === 'tiktokdev';
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.remote_refresh_folds_nothing_when_unreadable', 'connector', "The protocol-2 refresh adapter and the operator's pull differ ON PURPOSE, and both halves are pinned here: a wire that discloses no account makes the REFRESH observe zero and fold NOTHING (a previously pulled persona survives untouched), while the same executor makes the PULL throw", 'connector', 'core', async () => verifyBoundary('tiktok.connector.remote_refresh_folds_nothing_when_unreadable', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-conn-'));
+        // The twin's own answer to a credential it does not know — the exact body the kernel executor
+        // gets when a root holds no TikTok credential yet.
+        const refusingRemote = async () => ({ status: 401, headers: {}, body: JSON.stringify({ error: { code: 'access_token_invalid', message: 'The access token is invalid or not found in the request. Please refresh the token and retry.', log_id: '20260201000000AAAAAAAAAAAAAAAAAAAA' } }) });
+        try {
+            // A REAL observation first: without it "nothing was overwritten" is true by construction.
+            const seeded = await pullTikTok(fakeExecute, { root, occurredAt: '2026-02-01T00:00:01.000Z' });
+            const { readOne, readType } = await import("./tiktok-store.js");
+            const before = readOne(root, 'account', 'c9c60f44-a68e-4f5d-84dd-ce22faeb0ba1');
+            if (seeded !== 1 || before?.username !== 'tiktokdev')
+                return false;
+            // (a) the REFRESH observes nothing and folds nothing…
+            const refreshed = await syncTikTokFromRemote(refusingRemote, { root, occurredAt: '2026-02-01T00:00:02.000Z' });
+            const after = readOne(root, 'account', 'c9c60f44-a68e-4f5d-84dd-ce22faeb0ba1');
+            if (refreshed.observed !== 0 || refreshed.deltasAppended !== 0)
+                return false;
+            if (readType(root, 'account').length !== 1 || after?.username !== 'tiktokdev' || after?.followerCount !== before.followerCount)
+                return false;
+            // …and (b) the operator's own pull over a refusing executor still THROWS, so the sharp
+            // refusal rule keeps every tooth it had.
+            try {
+                await pullTikTok(async () => ({ error: { code: 'access_token_invalid', message: 'nope', log_id: 'x' } }), { root, occurredAt: '2026-02-01T00:00:03.000Z' });
+                return false;
+            }
+            catch (e) {
+                return String(e).includes('refused or malformed');
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.mapping_invents_nothing', 'connector', 'The mappings record ONLY what the reply disclosed — a scope-narrowed reply leaves the fields it omitted ABSENT, never placeholders', 'connector', 'common', async () => {
+        const mapped = mapUserInfoAccount({ data: { user: { union_id: 'u-1', open_id: 'o-1', display_name: 'Terse' } } });
+        const f = mapped.fields;
+        const video = mapVideo({ id: '7010000000000000009', title: 'T' }, 'u-1');
+        const vf = video.fields;
+        return mapped.id === 'u-1' && f['displayName'] === 'Terse'
+            && !('username' in f) && !('followerCount' in f) && !('isVerified' in f) && !('avatarUrl' in f)
+            && f['pulled'] === true
+            && video.id === '7010000000000000009' && vf['ownerUnionId'] === 'u-1'
+            && !('viewCount' in vf) && !('createTime' in vf) && vf['pulled'] === true;
+    }),
+    done('tiktok.connector.open_id_is_not_the_key', 'connector', "A pulled account is keyed by union_id, never open_id: one human authorizing two apps must be ONE twin account, not two", 'connector', 'core', async () => {
+        const a = mapUserInfoAccount({ data: { user: { union_id: 'same-human', open_id: 'app-a-view', username: 'x' } } });
+        const b = mapUserInfoAccount({ data: { user: { union_id: 'same-human', open_id: 'app-b-view', username: 'x' } } });
+        return a.id === 'same-human' && b.id === 'same-human' && a.id === b.id;
+    }),
+    done('tiktok.connector.budget_enforced', 'connector', "The live executor is fail-closed: at the ceiling the next call THROWS with the injected fetch's call count UNCHANGED (counted on the fake — nothing reached the vendor)", 'connector', 'core', async () => verifyBoundary('tiktok.connector.budget_enforced', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-budget-'));
+        let calls = 0;
+        const fakeFetch = (async () => {
+            calls += 1;
+            return new Response(JSON.stringify(structuredClone(FAKE_USER_INFO)), { status: 200, headers: { 'content-type': 'application/json' } });
+        });
+        try {
+            const clock = { t: 1_700_000_000_000 };
+            const execute = liveTikTokExecute('act.cap-test-token', { fetchImpl: fakeFetch, budgetOptions: { path: join(root, 'ledger.json'), now: () => clock.t } });
+            // Spent through the WEIGHTED path — the destructive revoke costs 60, so the vendor's own
+            // 600/minute ceiling is reached in ten calls. That the weights are what fill the ledger is
+            // the point: a flat-priced budget would let sixty revocations through where ten belong.
+            const allowed = TIKTOK_BUDGET_CEILING / TIKTOK_CALL_WEIGHTS.revoke;
+            for (let i = 0; i < allowed; i += 1)
+                await execute('POST', '/v2/oauth/revoke/');
+            if (calls !== allowed)
+                return false;
+            try {
+                await execute('POST', '/v2/oauth/revoke/');
+                return false; // the ceiling must throw
+            }
+            catch (e) {
+                return e instanceof TikTokBudgetError && calls === allowed;
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.destructive_call_priced_above_reads', 'connector', "The budget prices the one destructive call above a read, and the vendor's OWN trailing-slash spelling is priced the same as the bare one (a rule anchored on the bare path alone would under-price the documented URL)", 'connector', 'common', async () => {
+        return tiktokCallWeight('GET', '/v2/user/info/?fields=open_id') === TIKTOK_CALL_WEIGHTS.displayRead
+            && tiktokCallWeight('POST', '/v2/oauth/revoke/') === TIKTOK_CALL_WEIGHTS.revoke
+            && tiktokCallWeight('post', '/v2/oauth/revoke') === TIKTOK_CALL_WEIGHTS.revoke
+            && tiktokCallWeight('POST', '/v2/oauth/token/') === TIKTOK_CALL_WEIGHTS.other
+            && TIKTOK_CALL_WEIGHTS.revoke > TIKTOK_CALL_WEIGHTS.displayRead;
+    }),
+    done('tiktok.connector.unmapped_path_refused', 'connector', 'The live executor refuses an unmapped TikTok path OUTRIGHT — zero requests issued (the raw-vendor-call ban, D8)', 'connector', 'common', async () => verifyBoundary('tiktok.connector.unmapped_path_refused', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'tiktok-budget-'));
+        let calls = 0;
+        const fakeFetch = (async () => {
+            calls += 1;
+            return new Response('{}', { status: 200 });
+        });
+        try {
+            const execute = liveTikTokExecute('act.cap-test-token', { fetchImpl: fakeFetch, budgetOptions: { path: join(root, 'ledger.json'), now: () => 1_700_000_000_000 } });
+            try {
+                await execute('POST', '/v2/post/publish/video/init/');
+                return false;
+            }
+            catch {
+                return calls === 0;
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    })),
+    done('tiktok.connector.push_reports_impossible', 'connector', 'Push never fakes: TikTok has no write API for this surface, so push confirms nothing and REPORTS the real pending count as unpushable', 'connector', 'common', () => 
+    // Runs inside withRoot so real local writes exist first — on a virgin root the pending count is
+    // zero BY CONSTRUCTION and "reports the pending count" would be unproven.
+    withRoot(async (h) => {
+        const before = pushPendingTikTokActions(h.root);
+        const { status } = await fullFlow(h);
+        const after = pushPendingTikTokActions(h.root);
+        return status === 200 && before.pushed === 0 && after.pushed === 0 && after.unpushable > before.unpushable;
+    })),
+    done('tiktok.connector.perform_direct_post', 'connector', "A World's Direct Post performs against a vendor TikTok (a second twin) through the vendor's own flow — creator_info, video/init, every chunk PUT PRESIGNED to the upload_url it returned and carrying no Authorization, status/fetch to PUBLISH_COMPLETE — and the vendor ends holding the published video with identical bytes, its id the entry's external id", 'connector', 'core', async () => {
+        const vendorRoot = mkdtempSync(join(tmpdir(), 'tiktok-vendor-'));
+        const ledger = mkdtempSync(join(tmpdir(), 'tiktok-ledger-'));
+        try {
+            const MB5 = 5 * 1024 * 1024;
+            const media = pattern(2 * MB5 + 777);
+            // the vendor: a creator and the credential a root would seal
+            let vendorToken = '';
+            await withPosting(async (v) => { vendorToken = v.token; return true; }, vendorRoot);
+            return await withPosting(async (w) => {
+                const posted = await w.publish(media, MB5, 'PUBLIC_TO_EVERYONE');
+                const action = deployableEntries('tiktok', w.root).find((a) => a.operation === 'video.publish');
+                if (!action || !posted.postId)
+                    return false;
+                const seen = [];
+                let clock = Date.parse(AT);
+                const execute = async (req) => {
+                    clock += 20_000;
+                    const url = new URL(req.path, POSTING_ORIGIN);
+                    const headers = Object.fromEntries(Object.entries(req.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+                    seen.push({ method: req.method, path: url.pathname, presigned: req.presigned === true, authorized: headers['authorization'] !== undefined });
+                    // what the kernel executor does: the sealed credential rides every anchored request, never a presigned one
+                    const res = await handleTikTokTwinRequest({
+                        method: req.method,
+                        path: `${url.pathname}${url.search}`,
+                        ...(typeof req.body === 'string' ? { body: req.body } : {}),
+                        ...(req.body instanceof Uint8Array ? { bytes: req.body } : {}),
+                        headers: req.presigned ? headers : { ...headers, authorization: `Bearer ${vendorToken}` },
+                        root: vendorRoot,
+                        origin: POSTING_ORIGIN,
+                        occurredAt: new Date(clock).toISOString(),
+                    });
+                    return { status: res.status, headers: res.headers ?? {}, body: typeof res.body === 'string' ? res.body : JSON.stringify(res.body ?? '') };
+                };
+                const outcome = await performTikTokAction(execute, action, { resolve: (_t, id) => id, root: w.root }, new TikTokBudget({ path: join(ledger, 'ledger.json') }));
+                const vendorVideo = readAll(vendorRoot).find((r) => r.type === 'video' && r.id === outcome.externalId);
+                const served = await handleTikTokTwinRequest({ method: 'GET', path: `/_twin/media/video/${outcome.externalId}`, root: vendorRoot, occurredAt: new Date(clock + 60_000).toISOString() });
+                const puts = seen.filter((c) => c.method === 'PUT');
+                return seen[0]?.path === '/v2/post/publish/creator_info/query/' && seen[1]?.path === '/v2/post/publish/video/init/'
+                    && puts.length === 2 && puts.every((c) => c.presigned && !c.authorized && c.path === '/video/')
+                    && seen.slice(1).some((c) => c.path === '/v2/post/publish/status/fetch/')
+                    && /^\d{19}$/.test(String(outcome.externalId)) && outcome.externalId !== posted.postId
+                    && vendorVideo?.privacyLevel === 'PUBLIC_TO_EVERYONE'
+                    && served.status === 200 && sameBytes(await bytesOf(served.body), media);
+            });
+        }
+        finally {
+            rmSync(vendorRoot, { recursive: true, force: true });
+            rmSync(ledger, { recursive: true, force: true });
+        }
+    }),
+    done('tiktok.connector.perform_never_posts_twice', 'connector', "A kept publish is re-opened only when TikTok says it is gone: a publish answering PROCESSING_UPLOAD with 0 bytes after its chunks were refused is NOT re-initialized — the perform fails retryably and keeps it — and a later perform resumes the SAME publish on its kept upload_url, so the vendor holds one post from one init", 'connector', 'core', async () => {
+        const vendorRoot = mkdtempSync(join(tmpdir(), 'tiktok-vendor-'));
+        const ledger = mkdtempSync(join(tmpdir(), 'tiktok-ledger-'));
+        try {
+            let vendorToken = '';
+            await withPosting(async (v) => { vendorToken = v.token; return true; }, vendorRoot);
+            return await withPosting(async (w) => {
+                await w.publish(SMALL, SMALL.length, 'PUBLIC_TO_EVERYONE');
+                const action = deployableEntries('tiktok', w.root).find((a) => a.operation === 'video.publish');
+                if (!action)
+                    return false;
+                let clock = Date.parse(AT);
+                let refusePuts = true;
+                let inits = 0;
+                const execute = async (req) => {
+                    clock += 20_000;
+                    const url = new URL(req.path, POSTING_ORIGIN);
+                    if (url.pathname === '/v2/post/publish/video/init/')
+                        inits += 1;
+                    // the upload host is down: the chunk never arrives
+                    if (req.presigned && refusePuts)
+                        return { status: 503, headers: {}, body: 'upload host unavailable' };
+                    const headers = Object.fromEntries(Object.entries(req.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+                    const res = await handleTikTokTwinRequest({
+                        method: req.method,
+                        path: `${url.pathname}${url.search}`,
+                        ...(typeof req.body === 'string' ? { body: req.body } : {}),
+                        ...(req.body instanceof Uint8Array ? { bytes: req.body } : {}),
+                        headers: req.presigned ? headers : { ...headers, authorization: `Bearer ${vendorToken}` },
+                        root: vendorRoot,
+                        origin: POSTING_ORIGIN,
+                        occurredAt: new Date(clock).toISOString(),
+                    });
+                    return { status: res.status, headers: res.headers ?? {}, body: typeof res.body === 'string' ? res.body : JSON.stringify(res.body ?? '') };
+                };
+                const perform = () => performTikTokAction(execute, action, { resolve: (_t, id) => id, root: w.root }, new TikTokBudget({ path: join(ledger, 'ledger.json') }));
+                const attempt = async () => { try {
+                    await perform();
+                    return 'deployed';
+                }
+                catch (e) {
+                    return e.retryable === true ? 'retryable' : 'failed';
+                } };
+                const first = await attempt(); // the init lands, the chunk does not
+                const second = await attempt(); // PROCESSING_UPLOAD, 0 bytes: the same publish, still refused
+                const publishesAfterTwo = readAll(vendorRoot).filter((r) => r.type === 'publish').length;
+                refusePuts = false;
+                const outcome = await perform(); // the same publish resumes and completes
+                const posts = readAll(vendorRoot).filter((r) => r.type === 'video' && r.publishId !== undefined);
+                return first === 'retryable' && second === 'retryable' && inits === 1 && publishesAfterTwo === 0
+                    && posts.length === 1 && String(outcome.externalId) === String(posts[0].id);
+            });
+        }
+        finally {
+            rmSync(vendorRoot, { recursive: true, force: true });
+            rmSync(ledger, { recursive: true, force: true });
+        }
+    }),
+    done('tiktok.connector.posting_calls_priced_at_their_published_limits', 'connector', "The budget prices each Content Posting call at 600 divided by its reference's per-token minute (creator_info 20 -> 30, the inits 6 -> 100, status/fetch 30 -> 20), so none can outrun its own allowance inside the ledger's minute", 'connector', 'common', async () => tiktokCallWeight('POST', '/v2/post/publish/creator_info/query/') === TIKTOK_BUDGET_CEILING / 20
+        && tiktokCallWeight('POST', '/v2/post/publish/video/init/') === TIKTOK_BUDGET_CEILING / 6
+        && tiktokCallWeight('POST', '/v2/post/publish/inbox/video/init') === TIKTOK_CALL_WEIGHTS.postInit
+        && tiktokCallWeight('POST', '/v2/post/publish/status/fetch/') === TIKTOK_BUDGET_CEILING / 30),
+    todo('tiktok.connector.push', 'connector', 'PUSH remains structurally impossible (TikTok exposes no app/user/grant write API); revisit if TikTok ever ships one', 'connector', 'niche'),
+    todo('tiktok.connector.pull_clients', 'connector', 'PULL the developer-app registry — impossible today (TikTok apps live in the developer portal; no API reads them)', 'connector', 'niche'),
+    todo('tiktok.connector.pull_grants', 'connector', "PULL the token's granted scope set — impossible today (TikTok publishes no token-introspection endpoint)", 'connector', 'niche'),
+    // ═══ adjacent TikTok open-platform surface this pack does not model yet (honest denominator) ══
+    // ═══ the Content Posting API (developers.tiktok.com content-posting references, fetched 2026-09-27) ══
+    done('tiktok.content_posting.creator_info', 'content_posting', 'POST /v2/post/publish/creator_info/query/ answers the creator the token names — username, nickname, avatar, privacy_level_options, the comment/duet/stitch switches and max_video_post_duration_sec — and needs video.publish', 'api', 'common', () => withPosting(async (p) => {
+        const ok = await p.call('/v2/post/publish/creator_info/query/', {});
+        const d = body(ok).data ?? {};
+        const bare = await p.call('/v2/post/publish/creator_info/query/', {}, p.readToken);
+        return ok.status === 200 && body(ok).error?.code === 'ok'
+            && d.creator_username === 'poster' && d.creator_nickname === 'The Poster'
+            && JSON.stringify(d.privacy_level_options) === JSON.stringify(['PUBLIC_TO_EVERYONE', 'MUTUAL_FOLLOW_FRIENDS', 'SELF_ONLY'])
+            && d.stitch_disabled === true && d.max_video_post_duration_sec === 300 && d.comment_disabled === false
+            && bare.status === 401 && body(bare).error?.code === 'scope_not_authorized';
+    })),
+    done('tiktok.content_posting.direct_post_init', 'content_posting', 'POST /v2/post/publish/video/init/ with FILE_UPLOAD answers a v_pub_file publish_id and an upload_url on the upload path with upload_id + upload_token; a privacy_level outside the creator\'s options is privacy_level_option_mismatch (403) and PULL_FROM_URL without a verified domain is url_ownership_unverified (403)', 'api', 'common', () => withPosting(async (p) => {
+        const init = await p.init('direct', SMALL.length, SMALL.length, 1);
+        const url = new URL(String(body(init).data?.upload_url ?? 'http://x/'));
+        const mismatch = await p.call('/v2/post/publish/video/init/', { post_info: { privacy_level: 'FOLLOWER_OF_CREATOR' }, source_info: { source: 'FILE_UPLOAD', video_size: 10, chunk_size: 10, total_chunk_count: 1 } });
+        const pull = await p.call('/v2/post/publish/video/init/', { post_info: { privacy_level: 'SELF_ONLY' }, source_info: { source: 'PULL_FROM_URL', video_url: 'https://example.com/v.mp4' } });
+        const noScope = await p.call('/v2/post/publish/video/init/', { post_info: { privacy_level: 'SELF_ONLY' }, source_info: { source: 'FILE_UPLOAD', video_size: 10, chunk_size: 10, total_chunk_count: 1 } }, p.readToken);
+        return init.status === 200 && /^v_pub_file~v2-1\.\d+$/.test(String(body(init).data?.publish_id))
+            && url.origin === POSTING_ORIGIN && url.pathname === '/video/' && /^\d+$/.test(url.searchParams.get('upload_id') ?? '') && (url.searchParams.get('upload_token') ?? '') !== ''
+            && mismatch.status === 403 && body(mismatch).error?.code === 'privacy_level_option_mismatch'
+            && pull.status === 403 && body(pull).error?.code === 'url_ownership_unverified'
+            && noScope.status === 401 && body(noScope).error?.code === 'scope_not_authorized';
+    })),
+    done('tiktok.content_posting.upload_url_vendor_host_through_the_injector', 'content_posting', 'A request that names open.tiktokapis.com (the injector\'s x-volter-twin-original-host) gets its upload_url on the vendor\'s own upload host, open-upload.tiktokapis.com/video/, which the pack claims so the PUT routes back here', 'api', 'common', () => withPosting(async (p) => {
+        const init = await p.init('direct', SMALL.length, SMALL.length, 1, { originalHost: 'open.tiktokapis.com' });
+        return String(body(init).data?.upload_url ?? '').startsWith('https://open-upload.tiktokapis.com/video/?upload_id=');
+    })),
+    done('tiktok.content_posting.chunk_rules', 'content_posting', "The init enforces the media transfer guide's chunk rules: a video under 5 MB is one whole chunk, chunks are 5–64 MB, total_chunk_count is video_size / chunk_size rounded down (the final chunk carries the rest, up to 128 MB), and a 4 GB file maximum — each refusal is invalid_param (400)", 'api', 'common', () => withPosting(async (p) => {
+        const MB5 = 5 * 1024 * 1024;
+        const refused = async (size, chunk, count) => {
+            const r = await p.init('direct', size, chunk, count);
+            return r.status === 400 && body(r).error?.code === 'invalid_param';
+        };
+        const accepted = async (size, chunk, count) => (await p.init('direct', size, chunk, count)).status === 200;
+        return (await refused(1000, 500, 2)) // under 5 MB: whole
+            && (await accepted(1000, 1000, 1))
+            && (await refused(20 * MB5, MB5 - 1, 20)) // below the minimum chunk
+            && (await refused(20 * MB5, 65 * 1024 * 1024, 1)) // above the maximum chunk
+            && (await refused(3 * MB5 + 7, MB5, 4)) // count must round DOWN
+            && (await accepted(3 * MB5 + 7, MB5, 3))
+            && (await refused(100 * 1024 * 1024, 64 * 1024 * 1024, 1)) // over 64 MB in one chunk
+            && (await refused(5 * 1024 * 1024 * 1024, 64 * 1024 * 1024, 80)); // over 4 GB
+    })),
+    done('tiktok.content_posting.upload_video', 'content_posting', 'The chunked PUT to the upload_url: Content-Range bytes a-b/total per chunk, 206 while chunks remain and 201 when the last lands; out of order is 416, a size or total that disagrees with the plan is 400, and the stored video is byte-identical to what was sent', 'api', 'common', () => withPosting(async (p) => {
+        const MB5 = 5 * 1024 * 1024;
+        const media = pattern(2 * MB5 + 12345);
+        const init = await p.init('direct', media.length, MB5, 2);
+        const url = String(body(init).data?.upload_url);
+        const second = media.subarray(MB5);
+        const early = await p.put(url, second, `bytes ${MB5}-${media.length - 1}/${media.length}`);
+        const wrongTotal = await p.put(url, media.subarray(0, MB5), `bytes 0-${MB5 - 1}/${media.length + 1}`);
+        const first = await p.put(url, media.subarray(0, MB5), `bytes 0-${MB5 - 1}/${media.length}`);
+        const last = await p.put(url, second, `bytes ${MB5}-${media.length - 1}/${media.length}`);
+        const publishId = String(body(init).data?.publish_id);
+        const status = parseStatus(await p.call('/v2/post/publish/status/fetch/', { publish_id: publishId }, undefined, atPlus(120)));
+        const served = await p.media(status.postId ?? '', {}, atPlus(120));
+        return early.status === 416 && wrongTotal.status === 400 && first.status === 206 && last.status === 201
+            && served.status === 200 && sameBytes(await bytesOf(served.body), media);
+    })),
+    done('tiktok.content_posting.upload_url_signed', 'content_posting', "The upload_url's upload_token is VERIFIED, not looked up: a token altered by one character is 403, an unknown upload_id is 404, and the URL is refused (403) once its one hour of World time has passed", 'api', 'common', () => withPosting(async (p) => {
+        const init = await p.init('direct', SMALL.length, SMALL.length, 1);
+        const url = new URL(String(body(init).data?.upload_url));
+        const token = url.searchParams.get('upload_token') ?? '';
+        const tampered = new URL(url);
+        tampered.searchParams.set('upload_token', `${token.slice(0, -1)}${token.endsWith('A') ? 'B' : 'A'}`);
+        const unknown = new URL(url);
+        unknown.searchParams.set('upload_id', '7000000000000000000');
+        const range = `bytes 0-${SMALL.length - 1}/${SMALL.length}`;
+        const bad = await p.put(tampered.toString(), SMALL, range);
+        const missing = await p.put(unknown.toString(), SMALL, range);
+        const expired = await p.put(url.toString(), SMALL, range, atPlus(3601));
+        const fresh = await p.put(url.toString(), SMALL, range, atPlus(60));
+        return bad.status === 403 && missing.status === 404 && expired.status === 403 && fresh.status === 201;
+    })),
+    done('tiktok.content_posting.post_status', 'content_posting', 'POST /v2/post/publish/status/fetch/ walks the publish by World time: PROCESSING_UPLOAD with uploaded_bytes while chunks arrive and while TikTok processes, then PUBLISH_COMPLETE with publicaly_available_post_id as bare int64 numbers; an unknown id is invalid_publish_id and another creator\'s is token_not_authorized_for_specified_publish_id', 'api', 'common', () => withPosting(async (p) => {
+        const MB5 = 5 * 1024 * 1024;
+        const media = pattern(2 * MB5);
+        const init = await p.init('direct', media.length, MB5, 2);
+        const url = String(body(init).data?.upload_url);
+        const publishId = String(body(init).data?.publish_id);
+        const read = async (at, token) => p.call('/v2/post/publish/status/fetch/', { publish_id: publishId }, token, at);
+        await p.put(url, media.subarray(0, MB5), `bytes 0-${MB5 - 1}/${media.length}`);
+        const partway = parseStatus(await read(atPlus(1)));
+        await p.put(url, media.subarray(MB5), `bytes ${MB5}-${media.length - 1}/${media.length}`, atPlus(2));
+        const processing = parseStatus(await read(atPlus(3)));
+        const doneRead = await read(atPlus(30));
+        const done = parseStatus(doneRead);
+        const unknown = await p.call('/v2/post/publish/status/fetch/', { publish_id: 'v_pub_file~v2-1.1' });
+        const foreign = await read(atPlus(30), p.otherToken);
+        return partway.status === 'PROCESSING_UPLOAD' && partway.uploaded === MB5
+            && processing.status === 'PROCESSING_UPLOAD' && processing.uploaded === media.length
+            && done.status === 'PUBLISH_COMPLETE' && /^\d{19}$/.test(done.postId ?? '')
+            && new RegExp(`"publicaly_available_post_id":\\[${done.postId}\\]`).test(String(doneRead.body))
+            && unknown.status === 400 && body(unknown).error?.code === 'invalid_publish_id'
+            && foreign.status === 400 && parseStatus(foreign).code === 'token_not_authorized_for_specified_publish_id';
+    })),
+    done('tiktok.content_posting.published_video_listed', 'content_posting', 'A Direct Post becomes a Video Object on the creator\'s profile when its processing ends — /v2/video/list/ does not list it while PROCESSING_UPLOAD and lists it (caption, duration, id) after', 'api', 'common', () => withPosting(async (p) => {
+        const init = await p.init('direct', SMALL.length, SMALL.length, 1, { title: 'Release 0.5.68 #volter' });
+        await p.put(String(body(init).data?.upload_url), SMALL, `bytes 0-${SMALL.length - 1}/${SMALL.length}`);
+        const list = async (at) => p.call('/v2/video/list/?fields=id,video_description,title', { max_count: 20 }, undefined, at);
+        const before = body(await list(AT)).data?.videos ?? [];
+        const after = body(await list(atPlus(30))).data?.videos ?? [];
+        return before.length === 0 && after.length === 1 && after[0].video_description === 'Release 0.5.68 #volter';
+    })),
+    done('tiktok.content_posting.inbox_upload', 'content_posting', 'POST /v2/post/publish/inbox/video/init/ (video.upload) answers a v_inbox_file publish_id; the upload ends at SEND_TO_USER_INBOX and posts nothing to the profile; a sixth pending share inside 24 hours is spam_risk_too_many_pending_share', 'api', 'common', () => withPosting(async (p) => {
+        const upload = async (at) => {
+            const init = await p.init('inbox', SMALL.length, SMALL.length, 1, { at });
+            if (init.status !== 200)
+                return { init, publishId: '' };
+            await p.put(String(body(init).data?.upload_url), SMALL, `bytes 0-${SMALL.length - 1}/${SMALL.length}`, at);
+            return { init, publishId: String(body(init).data?.publish_id) };
+        };
+        const first = await upload(AT);
+        const status = parseStatus(await p.call('/v2/post/publish/status/fetch/', { publish_id: first.publishId }, undefined, atPlus(60)));
+        const listed = body(await p.call('/v2/video/list/?fields=id', { max_count: 20 }, undefined, atPlus(60))).data?.videos ?? [];
+        for (let i = 1; i < 5; i += 1)
+            await upload(atPlus(i * 10));
+        const sixth = await p.init('inbox', SMALL.length, SMALL.length, 1, { at: atPlus(70) });
+        return /^v_inbox_file~v2\.\d+$/.test(first.publishId) && status.status === 'SEND_TO_USER_INBOX' && listed.length === 0
+            && sixth.status === 403 && body(sixth).error?.code === 'spam_risk_too_many_pending_share';
+    })),
+    done('tiktok.content_posting.rate_limits', 'content_posting', "Each Content Posting endpoint meters its OWN per-token minute: the Direct Post init's seventh call inside a minute is 429 rate_limit_exceeded (the reference: 6 per minute)", 'api', 'niche', () => withPosting(async (p) => {
+        const codes = [];
+        for (let i = 0; i < 7; i += 1)
+            codes.push((await p.init('direct', SMALL.length, SMALL.length, 1, { at: atPlus(i) })).status);
+        return codes.slice(0, 6).every((c) => c === 200) && codes[6] === 429;
+    })),
+    done('tiktok.content_posting.media_served_with_range', 'content_posting', "A published video's bytes are served at the twin's media route under its public base: Range answers 206 with Content-Range, an open-ended range is capped at 8 MiB, past the end is 416, and a SELF_ONLY post plays only with its creator's access_token", 'api', 'common', () => withPosting(async (p) => {
+        const MB5 = 5 * 1024 * 1024;
+        const media = pattern(2 * MB5);
+        const pub = await p.publish(media, MB5, 'PUBLIC_TO_EVERYONE');
+        const ranged = await p.media(pub.postId, { range: 'bytes=10-19' });
+        const open = await p.media(pub.postId, { range: 'bytes=0-' });
+        const past = await p.media(pub.postId, { range: `bytes=${media.length}-` });
+        const backwards = await p.media(pub.postId, { range: 'bytes=5-3' });
+        const priv = await p.publish(SMALL, SMALL.length, 'SELF_ONLY');
+        const anon = await p.media(priv.postId, {});
+        const owner = await p.media(priv.postId, {}, undefined, p.token);
+        return ranged.status === 206 && ranged.headers?.['content-range'] === `bytes 10-19/${media.length}` && sameBytes(await bytesOf(ranged.body), media.subarray(10, 20))
+            && open.status === 206 && open.headers?.['content-range'] === `bytes 0-${8 * 1024 * 1024 - 1}/${media.length}`
+            && past.status === 416 && backwards.status === 200 && anon.status === 403 && owner.status === 200;
+    })),
+    done('tiktok.content_posting.privacy_level_required', 'content_posting', "A Direct Post init with no post_info.privacy_level, or one outside the creator's privacy_level_options, is privacy_level_option_mismatch (403) — the Direct Post reference's code for both", 'api', 'common', () => withPosting(async (p) => {
+        const plan = { source: 'FILE_UPLOAD', video_size: SMALL.length, chunk_size: SMALL.length, total_chunk_count: 1 };
+        const missing = await p.call('/v2/post/publish/video/init/', { post_info: { title: 'no privacy' }, source_info: plan });
+        const unknown = await p.call('/v2/post/publish/video/init/', { post_info: { privacy_level: 'EVERYONE' }, source_info: plan });
+        return missing.status === 403 && body(missing).error?.code === 'privacy_level_option_mismatch'
+            && unknown.status === 403 && body(unknown).error?.code === 'privacy_level_option_mismatch';
+    })),
+    done('tiktok.content_posting.processing_checks', 'content_posting', "Processing FAILS what TikTok's checks refuse, by the file's own headers: bytes that are no readable video are file_format_check_failed, and a frame rate outside 23–60 FPS is frame_rate_check_failed — nothing is posted", 'api', 'common', () => withPosting(async (p) => {
+        const failed = async (bytes) => {
+            const init = await p.init('direct', bytes.length, bytes.length, 1);
+            await p.put(String(body(init).data?.upload_url), bytes, `bytes 0-${bytes.length - 1}/${bytes.length}`);
+            return parseStatus(await p.call('/v2/post/publish/status/fetch/', { publish_id: String(body(init).data?.publish_id) }, undefined, atPlus(60)));
+        };
+        const zeros = await failed(new Uint8Array(1024 * 1024));
+        // TINY_MP4's 24 frames over a media duration doubled in its mdhd: 12 FPS
+        const slow = TINY_MP4.slice();
+        const at = Buffer.from(slow).indexOf('mdhd') + 4;
+        const view = new DataView(slow.buffer);
+        view.setUint32(at + 16, view.getUint32(at + 16) * 2);
+        const slowStatus = await failed(slow);
+        const good = await failed(TINY_MP4);
+        const listed = body(await p.call('/v2/video/list/?fields=id', { max_count: 20 }, undefined, atPlus(120))).data?.videos ?? [];
+        return zeros.status === 'FAILED' && zeros.failReason === 'file_format_check_failed'
+            && slowStatus.status === 'FAILED' && slowStatus.failReason === 'frame_rate_check_failed'
+            && good.status === 'PUBLISH_COMPLETE' && listed.length === 1;
+    })),
+    done('tiktok.content_posting.final_put_completes_after_a_stop', 'content_posting', 'A process that stopped after the last chunk was staged and before the publish was written leaves the upload whole but unfinished; the repeated final PUT completes it (201) and the post publishes once', 'api', 'niche', () => withPosting(async (p) => {
+        const init = await p.init('direct', SMALL.length, SMALL.length, 1);
+        const url = String(body(init).data?.upload_url);
+        // the stop: the one chunk staged, nothing after it ran
+        await stageChunk(new URL(url).searchParams.get('upload_id') ?? '', 0, SMALL, p.root);
+        const again = await p.put(url, SMALL, `bytes 0-${SMALL.length - 1}/${SMALL.length}`);
+        const status = parseStatus(await p.call('/v2/post/publish/status/fetch/', { publish_id: String(body(init).data?.publish_id) }, undefined, atPlus(60)));
+        const once = readAll(p.root).filter((r) => r.type === 'publish').length;
+        return again.status === 201 && status.status === 'PUBLISH_COMPLETE' && once === 1;
+    })),
+    done('tiktok.token.no_credential_in_the_clear', 'token', "No credential is kept in the clear: after a posted video, an inbox draft, a /_twin/tokens token and the whole Login Kit round trip, no file under the root — event log, projection, byte annex, staging records — contains any access token, refresh token, authorization code, client secret or upload token", 'api', 'core', () => withPosting(async (p) => {
+        await p.publish(SMALL, SMALL.length, 'PUBLIC_TO_EVERYONE');
+        const inbox = await p.init('inbox', SMALL.length, SMALL.length, 1);
+        const uploadUrl = new URL(String(body(inbox).data?.upload_url));
+        await p.put(uploadUrl.toString(), SMALL, `bytes 0-${SMALL.length - 1}/${SMALL.length}`);
+        // the OAuth leg on the same root: consent, redeem, refresh
+        const send = (m, path, b, h) => handleTikTokTwinRequest({ method: m, path, ...(b !== undefined ? { body: b } : {}), ...(h ? { headers: h } : {}), root: p.root, origin: POSTING_ORIGIN, occurredAt: AT });
+        const cb = `${POSTING_ORIGIN}/api/auth/callback/tiktok`;
+        const auth = await send('GET', `/v2/auth/authorize?client_key=${DEFAULT_CLIENT_KEY}&response_type=code&scope=user.info.basic&redirect_uri=${encodeURIComponent(cb)}&state=s`);
+        const request = /name="auth_request" value="([^"]+)"/.exec(String(auth.body))?.[1] ?? '';
+        const consent = await send('POST', '/_twin/consent', `auth_request=${request}&decision=allow&scope=user.info.basic`, FORM_CT);
+        const code = new URL(consent.headers?.location ?? 'http://x/').searchParams.get('code') ?? '';
+        const minted = body(await send('POST', '/v2/oauth/token/', new URLSearchParams({ client_key: DEFAULT_CLIENT_KEY, client_secret: DEFAULT_CLIENT_SECRET, grant_type: 'authorization_code', code, redirect_uri: cb }).toString(), FORM_CT));
+        const rotated = body(await send('POST', '/v2/oauth/token/', new URLSearchParams({ client_key: DEFAULT_CLIENT_KEY, client_secret: DEFAULT_CLIENT_SECRET, grant_type: 'refresh_token', refresh_token: String(minted.refresh_token) }).toString(), FORM_CT));
+        const secrets = [p.token, p.readToken, p.otherToken, code, String(minted.access_token), String(minted.refresh_token), String(rotated.access_token), String(rotated.refresh_token), DEFAULT_CLIENT_SECRET, uploadUrl.searchParams.get('upload_token') ?? '']
+            .filter((v) => v.length >= 8);
+        const files = [];
+        const walk = (dir) => { for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const f = join(dir, e.name);
+            if (e.isDirectory())
+                walk(f);
+            else
+                files.push(f);
+        } };
+        walk(p.root);
+        const leaks = files.filter((f) => { const text = readFileSync(f).toString('latin1'); return secrets.some((v) => text.includes(v)); });
+        return secrets.length === 10 && files.length > 5 && leaks.length === 0;
+    })),
+    todo('tiktok.content_posting.large_files', 'content_posting', "Accept TikTok's full 4 GB: the twin holds a video whole at its last chunk (the blob seam's put takes bytes), so it refuses an init over 512 MiB — a streaming join onto the blob seam would lift it", 'api', 'niche'),
+    todo('tiktok.content_posting.photo_post', 'content_posting', 'Model POST /v2/post/publish/content/init/ — the photo post, which is PULL_FROM_URL only (images fetched from a verified domain)', 'api', 'niche'),
+    todo('tiktok.content_posting.pull_from_url', 'content_posting', 'Model PULL_FROM_URL: the developer-portal registry of verified URL prefixes and domains, the fetch, PROCESSING_DOWNLOAD and downloaded_bytes (today every pull is url_ownership_unverified)', 'api', 'niche'),
+    todo('tiktok.content_posting.upload_bodies', 'content_posting', 'PIN the body the upload URL answers with each status (the media transfer guide publishes the statuses only; the twin answers a plain-text reason)', 'api', 'niche'),
+    todo('tiktok.content_posting.caption_fields', 'content_posting', "PIN which Video Object fields a Direct Post's post_info.title fills (the twin fills video_description and title with the caption)", 'api', 'niche'),
+    todo('tiktok.content_posting.processing_time', 'content_posting', 'PIN how long TikTok takes to process a posted video (the twin holds PROCESSING_UPLOAD for 2 s plus 1 s per 10 MiB of World time)', 'api', 'niche'),
+    todo('tiktok.content_posting.daily_post_cap', 'content_posting', 'Model spam_risk_too_many_posts and reached_active_user_cap — the per-creator daily post cap and the per-client active-user cap (the references name the codes, not the numbers)', 'api', 'niche'),
+    todo('tiktok.content_posting.unaudited_client', 'content_posting', "Model the unaudited-client rule: \"All content posted by unaudited clients will be restricted to private viewing mode\" and unaudited_client_can_only_post_to_private_accounts", 'api', 'common'),
+    todo('tiktok.research.query_videos', 'research', 'Model POST /v2/research/video/query/ — the Research API video search with its own field and condition grammar', 'api', 'niche'),
+    todo('tiktok.research.query_users', 'research', 'Model POST /v2/research/user/info/ and the follower/following reads', 'api', 'niche'),
+    todo('tiktok.research.query_comments', 'research', 'Model POST /v2/research/video/comment/list/', 'api', 'niche'),
+    todo('tiktok.research.adlib', 'research', 'Model the Commercial Content Library / ad-library research reads', 'api', 'niche'),
+    todo('tiktok.portability.add_request', 'portability', 'Model POST /v2/portability/data/add/ — a data-portability export request', 'api', 'niche'),
+    todo('tiktok.portability.check_request', 'portability', 'Model the export status poll', 'api', 'niche'),
+    todo('tiktok.portability.download', 'portability', 'Model the export download endpoint and its archive shape', 'api', 'niche'),
+    todo('tiktok.local_services.product_manage', 'local_services', 'Model the Local Services product/shop/voucher management surface behind the local.*.manage scopes', 'api', 'niche'),
+    // ── webhooks: the Events page's own event catalog (§9: the names below are the vendor's) ──
+    todo('tiktok.webhooks.delivery', 'webhooks', "Model webhook DELIVERY itself: the registered callback URL, the envelope (client_key, event, create_time, user_openid, content) and the signature scheme a receiver verifies", 'api', 'common'),
+    todo('tiktok.webhooks.authorization_removed', 'webhooks', "Model the `authorization.removed` event — fired when a user disconnects the app, carrying the REASON enum that says whether the user, the platform or a policy action removed it. The twin already models the revoke that causes it and tells nobody", 'api', 'common'),
+    todo('tiktok.webhooks.video_publish_completed', 'webhooks', 'Model the `video.publish.completed` event (Content Posting: a Direct Post finished publishing)', 'api', 'common'),
+    todo('tiktok.webhooks.video_upload_failed', 'webhooks', 'Model the `video.upload.failed` event (Content Posting: an upload did not become a post)', 'api', 'common'),
+    todo('tiktok.webhooks.portability_download_ready', 'webhooks', 'Model the `portability.download.ready` event (Data Portability: an export archive is ready to fetch)', 'api', 'niche'),
+    // ── oEmbed: the one PUBLIC, unauthenticated read this vendor publishes ──
+    todo('tiktok.oembed.lookup', 'oembed', 'Model GET https://www.tiktok.com/oembed?url=… — the public oEmbed read (no token, no app) returning title, author_name, author_url, thumbnail_url, html and the player dimensions for a video URL', 'api', 'common'),
+    // ── product families this pack does not serve, named so each is a visible gap ──
+    todo('tiktok.share_kit.share', 'share_kit', 'Model Share Kit — the app-to-app hand-off that opens the TikTok composer with media a partner app supplies, and its share-status callbacks', 'api', 'common'),
+    todo('tiktok.mini_apps.mini_games', 'mini_apps', 'Model the Mini Games platform surface (its own developer APIs and in-app runtime)', 'api', 'niche'),
+    todo('tiktok.mini_apps.mini_dramas', 'mini_apps', 'Model the Mini Dramas platform surface', 'api', 'niche'),
+    todo('tiktok.mini_apps.tiktok_go', 'mini_apps', 'Model the TikTok GO platform surface', 'api', 'niche'),
+    todo('tiktok.business.ads_api', 'business', 'Model the business-api.tiktok.com Business/Ads API — a SEPARATE service-area of this same vendor (its own host, its own access-token scheme and the tiktok-business-api-sdk clients), named here so it is a visible gap rather than a silent omission', 'api', 'common'),
+    todo('tiktok.business.webhooks', 'business', 'Model the Business API webhook subscriptions', 'api', 'niche'),
+];
+/** 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 const TIKTOK_AREAS = [
+    '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 function tiktokCapabilities() {
+    return checkCapabilities('tiktok', TIKTOK_CAPABILITIES);
+}