@volter/twin-tiktok 0.1.0

package/src/tiktok-conformance.ts

@@ -0,0 +1,526 @@
+// TikTok conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// ── THIS CHECK DRIVES THE ROUTER AND ASSERTS WHAT CAME BACK ─────────────────────────────────────
+// Held to ADDING_A_TWIN.md §6's bar:
+//   • two constants asserting about each other is not a check — every expectation below is a
+//     LITERAL, never a value read back out of the handler's own module;
+//   • "not the router's own miss" has teeth at the dispatch and nowhere deeper — each probe
+//     declares the STATUS SET and a PREDICATE over the body a live handler produces, the endpoint
+//     census is a two-way bijection with the snapshot, and a hand-enumerated ROUTER_SURFACE catches
+//     served-but-unclaimed surface (the direction probes<->snapshot is blind to).
+//
+// And the whole point of this pack — the ROUND TRIP — is checked as a round trip: a real authorize
+// request, a real consent with a real per-scope decision, a real 302 carrying code + scopes +
+// state, that code redeemed for a token, and that token answering the Display API with the
+// consenting persona. A router that dispatches every route while folding nothing cannot pass that.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_KEY, DEFAULT_CLIENT_SECRET, DEFAULT_VIDEOS, defaultRedirectUris, openIdFor } from './tiktok-store.ts';
+import { handleTikTokTwinRequest, tiktokTwinSnapshot, type TikTokResponse } from './tiktok-twin.ts';
+
+export { paddedMp4, TINY_MP4 } from './tiktok-sample-mp4.ts';
+import { TINY_MP4 } from './tiktok-sample-mp4.ts';
+
+export type TikTokConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  endpointsProbed: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+type Probe = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  /** The status(es) a WORKING handler answers with. */
+  status: number[];
+  /** What a working handler's body must look like. */
+  expect?: (body: unknown) => boolean;
+};
+
+const isObject = (b: unknown): b is Record<string, unknown> => !!b && typeof b === 'object';
+const htmlContaining = (...needles: string[]) => (b: unknown) => typeof b === 'string' && needles.every((n) => b.includes(n));
+
+/** 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_URI = defaultRedirectUris(DEMO_ORIGIN)[0]!;
+const SCOPE = 'user.info.basic,user.info.profile,user.info.stats,video.list';
+const AT = '2026-02-01T00:00:00.000Z';
+const ADA = DEFAULT_ACCOUNTS[0]!;
+const GRACE = DEFAULT_ACCOUNTS[1]!;
+const ADA_OPEN_ID = openIdFor(DEFAULT_CLIENT_KEY, ADA.unionId);
+const ADA_VIDEO = DEFAULT_VIDEOS[0]!;
+
+/** Placeholders substituted with values the live flow actually minted. */
+const CODE = 'PROBE_CODE';
+const ACCESS = 'PROBE_ACCESS_TOKEN';
+/** A token holding video.publish + video.upload (issued through /_twin/tokens: no consent is needed
+ *  to prove the posting surface), a staged publish to read, and an upload URL to PUT to. */
+const POSTER = 'PROBE_POST_TOKEN';
+const PUBLISH = 'PROBE_PUBLISH_ID';
+const UPLOAD = 'PROBE_UPLOAD_PATH';
+/** One whole chunk (under TikTok's 5 MB floor). */
+const CHUNK = TINY_MP4;
+const postHeaders = { authorization: `Bearer ${POSTER}`, 'content-type': 'application/json; charset=UTF-8' };
+const sourceInfo = { source: 'FILE_UPLOAD', video_size: CHUNK.length, chunk_size: CHUNK.length, total_chunk_count: 1 };
+const initData = (prefix: string) => (b: unknown) => {
+  if (!isObject(b) || !isObject(b.data)) return false;
+  const d = b.data as Record<string, unknown>;
+  return typeof d['publish_id'] === 'string' && d['publish_id'].startsWith(prefix)
+    && typeof d['upload_url'] === 'string' && /\/video\/\?upload_id=\d+&upload_token=[^&]+$/.test(d['upload_url'])
+    && isObject(b.error) && (b.error as Record<string, unknown>)['code'] === 'ok';
+};
+
+const authQuery = `client_key=${encodeURIComponent(DEFAULT_CLIENT_KEY)}&response_type=code`
+  + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&scope=${encodeURIComponent(SCOPE)}&state=probe-state`;
+
+const form = (params: Record<string, string>) => new URLSearchParams(params).toString();
+const clientCreds = { client_key: DEFAULT_CLIENT_KEY, client_secret: DEFAULT_CLIENT_SECRET };
+
+/** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
+const PROBES: Record<string, Probe> = {
+  'GET /v2/auth/authorize': {
+    method: 'GET',
+    path: `/v2/auth/authorize?${authQuery}`,
+    status: [200],
+    // The authorization page is HTML, and its content is the claim: the app name from the app
+    // registry, the signed-in persona, both buttons, and a scope's consent wording — TikTok's own,
+    // from the scope catalog — must all be ON the page.
+    // NB the scope wording is asserted WITHOUT its apostrophe: the served markup is React's, and
+    // React escapes `'` to `&#x27;` in text content.
+    expect: htmlContaining('Continue', 'Cancel', 'Twin Demo App', `@${ADA.username}`, 'public videos on TikTok'),
+  },
+  'POST /v2/oauth/token': {
+    method: 'POST',
+    path: '/v2/oauth/token/',
+    body: form({ ...clientCreds, code: CODE, grant_type: 'authorization_code', redirect_uri: REDIRECT_URI }),
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    status: [200],
+    // Literals, deliberately (the field table the guide publishes): capital-B `Bearer`, the
+    // documented 24-hour expiry and 365-day refresh expiry, TikTok-shaped `act.`/`rft.` tokens, the
+    // per-app open_id, and the comma-separated granted scope string.
+    expect: (b) =>
+      isObject(b)
+      && b.token_type === 'Bearer'
+      && b.expires_in === 86_400
+      && b.refresh_expires_in === 31_536_000
+      && typeof b.access_token === 'string' && b.access_token.startsWith('act.')
+      && typeof b.refresh_token === 'string' && b.refresh_token.startsWith('rft.')
+      && b.open_id === ADA_OPEN_ID
+      && b.scope === SCOPE,
+  },
+  'POST /v2/oauth/revoke': {
+    method: 'POST',
+    path: '/v2/oauth/revoke/',
+    body: form({ ...clientCreds, token: ACCESS }),
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    status: [200],
+    // "If the request is successful, the response struct will be empty."
+    expect: (b) => isObject(b) && Object.keys(b).length === 0,
+  },
+  'GET /v2/user/info': {
+    method: 'GET',
+    path: '/v2/user/info/?fields=open_id,union_id,display_name,username,follower_count',
+    headers: { authorization: `Bearer ${ACCESS}` },
+    status: [200],
+    expect: (b) =>
+      isObject(b)
+      && isObject(b.data)
+      && isObject((b.data as Record<string, unknown>)['user'])
+      && ((b.data as Record<string, any>)['user']['open_id']) === ADA_OPEN_ID
+      && ((b.data as Record<string, any>)['user']['union_id']) === ADA.unionId
+      && ((b.data as Record<string, any>)['user']['username']) === ADA.username
+      && ((b.data as Record<string, any>)['user']['display_name']) === ADA.displayName
+      && ((b.data as Record<string, any>)['user']['follower_count']) === ADA.followerCount
+      && isObject(b.error) && (b.error as Record<string, unknown>)['code'] === 'ok',
+  },
+  'POST /v2/video/list': {
+    method: 'POST',
+    path: '/v2/video/list/?fields=id,title,create_time,share_url',
+    body: JSON.stringify({ max_count: 20 }),
+    headers: { authorization: `Bearer ${ACCESS}`, 'content-type': 'application/json' },
+    status: [200],
+    expect: (b) => {
+      if (!isObject(b) || !isObject(b.data)) return false;
+      const data = b.data as Record<string, any>;
+      const videos = data['videos'] as Array<Record<string, unknown>> | undefined;
+      return Array.isArray(videos)
+        && videos.some((v) => v['id'] === ADA_VIDEO.id && v['title'] === ADA_VIDEO.title
+          && v['share_url'] === `https://www.tiktok.com/@${ADA.username}/video/${ADA_VIDEO.id}`)
+        && typeof data['cursor'] === 'number'
+        && typeof data['has_more'] === 'boolean';
+    },
+  },
+  'POST /v2/video/query': {
+    method: 'POST',
+    path: '/v2/video/query/?fields=id,view_count',
+    body: JSON.stringify({ filters: { video_ids: [ADA_VIDEO.id] } }),
+    headers: { authorization: `Bearer ${ACCESS}`, 'content-type': 'application/json' },
+    status: [200],
+    expect: (b) => {
+      if (!isObject(b) || !isObject(b.data)) return false;
+      const videos = (b.data as Record<string, any>)['videos'] as Array<Record<string, unknown>> | undefined;
+      return Array.isArray(videos) && videos.length === 1
+        && videos[0]!['id'] === ADA_VIDEO.id && videos[0]!['view_count'] === ADA_VIDEO.viewCount;
+    },
+  },
+  'POST /v2/post/publish/creator_info/query': {
+    method: 'POST',
+    path: '/v2/post/publish/creator_info/query/',
+    body: '{}',
+    headers: postHeaders,
+    status: [200],
+    // the reference's own field set, with the reference's own example options for a public account
+    expect: (b) => {
+      if (!isObject(b) || !isObject(b.data)) return false;
+      const d = b.data as Record<string, any>;
+      return d['creator_username'] === ADA.username && d['creator_nickname'] === ADA.displayName
+        && JSON.stringify(d['privacy_level_options']) === '["PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","SELF_ONLY"]'
+        && d['comment_disabled'] === false && d['duet_disabled'] === false && d['stitch_disabled'] === false
+        && d['max_video_post_duration_sec'] === 600 && typeof d['creator_avatar_url'] === 'string';
+    },
+  },
+  'POST /v2/post/publish/video/init': {
+    method: 'POST',
+    path: '/v2/post/publish/video/init/',
+    body: JSON.stringify({ post_info: { title: 'probe #conformance', privacy_level: 'SELF_ONLY' }, source_info: sourceInfo }),
+    headers: postHeaders,
+    status: [200],
+    expect: initData('v_pub_file~v2-1.'),
+  },
+  'POST /v2/post/publish/inbox/video/init': {
+    method: 'POST',
+    path: '/v2/post/publish/inbox/video/init/',
+    body: JSON.stringify({ source_info: sourceInfo }),
+    headers: postHeaders,
+    status: [200],
+    expect: initData('v_inbox_file~v2.'),
+  },
+  'POST /v2/post/publish/status/fetch': {
+    method: 'POST',
+    path: '/v2/post/publish/status/fetch/',
+    body: JSON.stringify({ publish_id: PUBLISH }),
+    headers: postHeaders,
+    status: [200],
+    // a publish whose chunk has not arrived: PROCESSING_UPLOAD with nothing uploaded, an empty id list
+    expect: (b) => typeof b === 'string'
+      && b.includes('"status":"PROCESSING_UPLOAD"') && b.includes('"publicaly_available_post_id":[]') && b.includes('"uploaded_bytes":0')
+      && b.includes('"code":"ok"'),
+  },
+  'PUT /video': {
+    method: 'PUT',
+    path: UPLOAD,
+    headers: { 'content-type': 'video/mp4', 'content-range': `bytes 0-${CHUNK.length - 1}/${CHUNK.length}` },
+    // the one chunk of a one-chunk upload: 201, "All chunks uploaded; processing begins"
+    status: [201],
+  },
+};
+
+/**
+ * Every VENDOR method/path pair a reader of `routeTikTokTwinRequest` can see the router branch on,
+ * PLUS near-miss pairs (wrong method on a claimed path, a sibling open-API route, the legacy v1
+ * path) that must answer the vendor-shaped refusal. Written by hand from the router, so the census
+ * can catch VENDOR surface that is served without being claimed. The `/_twin/*` control routes are
+ * DELIBERATELY outside this census: they are twin-only scaffolding (ADDING_A_TWIN.md §6), answer
+ * non-refusal by design, and are never claimable — so this check is blind to them BY CONSTRUCTION,
+ * and a §9 reader must compare `twinControl`'s branches against the scaffolding list in the README.
+ */
+const ROUTER_SURFACE: Array<[string, string]> = [
+  ['GET', `/v2/auth/authorize?${authQuery}`],
+  // The vendor's OWN spelling carries a trailing slash; it must reach the same route.
+  ['GET', `/v2/auth/authorize/?${authQuery}`],
+  ['POST', '/v2/auth/authorize'],
+  ['POST', '/v2/oauth/token/'],
+  ['GET', '/v2/oauth/token/'],
+  ['POST', '/v2/oauth/revoke/'],
+  ['GET', '/v2/oauth/revoke/'],
+  ['GET', '/v2/user/info/'],
+  // …and the slash-less spelling Dub's own client builds (`${baseUrl}/user/info/` lands with one,
+  // but a hand-written integration may not) — it must reach the same route, not refuse.
+  ['GET', '/v2/user/info'],
+  ['POST', '/v2/user/info/'],
+  ['POST', '/v2/video/list/'],
+  ['GET', '/v2/video/list/'],
+  ['POST', '/v2/video/query/'],
+  ['GET', '/v2/video/query/'],
+  ['POST', '/v2/post/publish/creator_info/query/'],
+  ['GET', '/v2/post/publish/creator_info/query/'],
+  ['POST', '/v2/post/publish/video/init/'],
+  ['POST', '/v2/post/publish/inbox/video/init/'],
+  ['POST', '/v2/post/publish/status/fetch/'],
+  ['PUT', '/video/'],
+  ['GET', '/video/'],
+  // Unmodelled TikTok open-API surface — every one must refuse, never fake a success.
+  ['POST', '/v2/post/publish/content/init/'],
+  ['POST', '/v2/research/video/query/'],
+  ['POST', '/oauth/access_token/'],
+];
+
+/** The refusal an unmodelled route gets: the API family's `invalid_params`, naming the route. */
+const isRefusal = (res: TikTokResponse): boolean =>
+  res.status === 400
+  && isObject(res.body)
+  && isObject((res.body as Record<string, unknown>)['error'])
+  && ((res.body as Record<string, any>)['error']['code']) === 'invalid_params'
+  && String((res.body as Record<string, any>)['error']['message']).includes('is not a TikTok open API endpoint');
+
+const AUTH_REQUEST_RE = /name="auth_request" value="([^"]+)"/;
+
+export async function checkTikTokConformance(opts: { root?: string } = {}): Promise<TikTokConformanceReport> {
+  void opts;
+  const snapshot = tiktokTwinSnapshot();
+  const violations: string[] = [];
+  // Always a THROWAWAY root, even when a caller passes one: the check mints and then REVOKES
+  // credentials, and doing that in an operator's world would disconnect them from their own twin.
+  const root = mkdtempSync(join(tmpdir(), 'tiktok-conformance-'));
+  const call = (method: string, path: string, body?: string, headers?: Record<string, string>, extra: { bytes?: Uint8Array; at?: string } = {}): Promise<TikTokResponse> =>
+    handleTikTokTwinRequest({ method, path, ...(body !== undefined ? { body } : {}), ...(headers ? { headers } : {}), ...(extra.bytes ? { bytes: extra.bytes } : {}), root, origin: DEMO_ORIGIN, occurredAt: extra.at ?? AT });
+
+  /** Drive a full consent (granting every requested scope) and return the minted code. */
+  const mintCode = async (scope = SCOPE): Promise<string> => {
+    const q = authQuery.replace(`scope=${encodeURIComponent(SCOPE)}`, `scope=${encodeURIComponent(scope)}`);
+    const a = await call('GET', `/v2/auth/authorize?${q}`);
+    const rid = AUTH_REQUEST_RE.exec(String(a.body))?.[1] ?? '';
+    const decision = new URLSearchParams({ auth_request: rid, decision: 'allow' });
+    for (const s of scope.split(',')) decision.append('scope', s);
+    const d = await call('POST', '/_twin/consent', decision.toString());
+    return new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+  };
+  const redeem = (code: string) =>
+    call('POST', '/v2/oauth/token/', form({ ...clientCreds, code, grant_type: 'authorization_code', redirect_uri: REDIRECT_URI }), { 'content-type': 'application/x-www-form-urlencoded' });
+
+  let probed = 0;
+  try {
+    // ── the ROUND TRIP, driven for real, before any probing ──
+    const authRes = await call('GET', `/v2/auth/authorize?${authQuery}`);
+    const requestId = AUTH_REQUEST_RE.exec(String(authRes.body))?.[1] ?? '';
+    if (!requestId) violations.push('the authorize endpoint did not render a consent form carrying an auth_request handle');
+    const decision = new URLSearchParams({ auth_request: requestId, decision: 'allow' });
+    for (const s of SCOPE.split(',')) decision.append('scope', s);
+    const settled = await call('POST', '/_twin/consent', decision.toString());
+    const location = settled.headers?.location ?? '';
+    if (settled.status !== 302 || !location.startsWith(REDIRECT_URI)) {
+      violations.push(`consent did not 302 back to the registered redirect_uri: ${settled.status} ${location}`);
+    }
+    const back = new URL(location || 'http://invalid.test/');
+    const code = back.searchParams.get('code') ?? '';
+    if (back.searchParams.get('state') !== 'probe-state') {
+      violations.push(`the redirect did not echo the caller's state verbatim: ${back.searchParams.get('state')}`);
+    }
+    if (back.searchParams.get('scopes') !== SCOPE) {
+      violations.push(`the redirect did not carry the documented granted-scopes parameter: ${back.searchParams.get('scopes')}`);
+    }
+    if (!code.includes('*!')) {
+      violations.push(`the redirect did not carry a TikTok-shaped authorization code: ${code}`);
+    }
+    const extras = [...back.searchParams.keys()].filter((k) => k !== 'state' && k !== 'code' && k !== 'scopes');
+    if (extras.length > 0) {
+      // The documented callback carries exactly code, scopes and state; an invented parameter is
+      // surface an integration could come to depend on and then break against the real vendor.
+      violations.push(`the success redirect carries parameters TikTok's documented callback does not: ${extras.join(', ')}`);
+    }
+
+    const tokenRes = await redeem(code);
+    const tokens = tokenRes.body as Record<string, any>;
+    if (tokenRes.status !== 200 || typeof tokens?.access_token !== 'string') {
+      violations.push(`the minted code was not redeemable at the token endpoint: ${tokenRes.status} ${JSON.stringify(tokenRes.body).slice(0, 160)}`);
+    }
+    // …and the token is USABLE: it answers the Display API with the consenting persona.
+    const me = await call('GET', '/v2/user/info/?fields=open_id,union_id,username', undefined, { authorization: `Bearer ${tokens?.access_token}` });
+    const meUser = (me.body as Record<string, any>)?.data?.user;
+    if (me.status !== 200 || meUser?.union_id !== ADA.unionId || meUser?.username !== ADA.username || meUser?.open_id !== ADA_OPEN_ID) {
+      violations.push(`the minted token did not answer /v2/user/info/ with the consenting persona: ${me.status} ${JSON.stringify(me.body).slice(0, 160)}`);
+    }
+    // A redeemed code must be DEAD. This is the security property, so it is checked here and not
+    // only in the manifest.
+    const replay = await redeem(code);
+    if (replay.status !== 400 || (replay.body as Record<string, unknown>)?.['error'] !== 'invalid_grant') {
+      violations.push(`a replayed authorization code was not refused: ${replay.status} ${JSON.stringify(replay.body).slice(0, 120)}`);
+    }
+    // The refresh token ROTATES: the replacement works, the spent one is refused.
+    const refresh1 = await call('POST', '/v2/oauth/token/', form({ ...clientCreds, grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token) }), { 'content-type': 'application/x-www-form-urlencoded' });
+    const refreshed = refresh1.body as Record<string, any>;
+    if (refresh1.status !== 200 || typeof refreshed?.refresh_token !== 'string' || refreshed.refresh_token === tokens?.refresh_token) {
+      violations.push(`the refresh grant did not rotate the refresh token: ${refresh1.status} ${JSON.stringify(refresh1.body).slice(0, 120)}`);
+    }
+    const spent = await call('POST', '/v2/oauth/token/', form({ ...clientCreds, grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token) }), { 'content-type': 'application/x-www-form-urlencoded' });
+    if (spent.status !== 400) violations.push(`a spent refresh token was accepted a second time: ${spent.status}`);
+
+    // ── the endpoint census, THREE ways ──
+    const claimed = new Set(snapshot.implementedEndpoints);
+    for (const key of Object.keys(PROBES)) {
+      if (!claimed.has(key)) violations.push(`probe '${key}' does not correspond to any claimed endpoint — the probe table has drifted`);
+    }
+    for (const [method, probePath] of ROUTER_SURFACE) {
+      const res = await call(method, probePath);
+      const key = `${method} ${(probePath.split('?')[0] ?? '').replace(/\/+$/, '')}`;
+      if (!isRefusal(res) && !claimed.has(key)) {
+        violations.push(`the router answers '${key}' (${res.status}) but the snapshot does not claim it — served surface outside the census is deletable without this check noticing`);
+      }
+    }
+
+    // Fixtures per destructive probe, so probe ORDER cannot make this check lie: the revoke probe
+    // kills a WHOLE (app, user) grant family, which would take the Display API probes' token with
+    // it if the two fixtures shared a user. The revoke fixture is therefore minted under the
+    // SECOND persona's session (switched and restored via the twin-only session control).
+    const probeTokens = async () => (await redeem(await mintCode())).body as Record<string, any>;
+    await call('POST', '/_twin/session', JSON.stringify({ union_id: GRACE.unionId }));
+    const revokeFixture = await probeTokens();
+    await call('POST', '/_twin/session', JSON.stringify({ union_id: ADA.unionId }));
+    const displayFixture = await probeTokens();
+    const tokenProbeCode = await mintCode();
+
+    // the posting fixtures: a token that may post, a publish to read (staged, nothing uploaded yet)
+    // and a second one whose upload URL the PUT probe sends its one chunk to
+    const posterToken = String(((await call('POST', '/_twin/tokens', JSON.stringify({ union_id: ADA.unionId, scopes: ['user.info.basic', 'video.list', 'video.publish', 'video.upload'] }))).body as Record<string, any>)?.access_token ?? '');
+    const postAuth = { ...postHeaders, authorization: `Bearer ${posterToken}` };
+    const initFixture = async () => ((await call('POST', '/v2/post/publish/video/init/', JSON.stringify({ post_info: { privacy_level: 'PUBLIC_TO_EVERYONE' }, source_info: sourceInfo }), postAuth)).body as Record<string, any>)?.data ?? {};
+    const statusFixture = await initFixture();
+    const uploadFixture = await initFixture();
+    const uploadPath = (() => { try { const u = new URL(String(uploadFixture.upload_url)); return `${u.pathname}${u.search}`; } catch { return '/video/'; } })();
+
+    const substitute = (s: string) => s.replace(CODE, tokenProbeCode).replace(ACCESS, String(displayFixture?.access_token ?? ''))
+      .replace(POSTER, posterToken).replace(PUBLISH, String(statusFixture.publish_id ?? '')).replace(UPLOAD, uploadPath);
+
+    for (const endpoint of snapshot.implementedEndpoints) {
+      const probe = PROBES[endpoint];
+      if (!probe) {
+        violations.push(`endpoint '${endpoint}' is claimed but has no conformance probe — the claim is unverified`);
+        continue;
+      }
+      const [claimedMethod, claimedPath] = endpoint.split(' ');
+      if (probe.method !== claimedMethod) {
+        violations.push(`probe '${endpoint}' drives ${probe.method}, not ${claimedMethod}`);
+        continue;
+      }
+      if (probe.path !== UPLOAD && (probe.path.split('?')[0] ?? '').replace(/\/+$/, '') !== claimedPath) {
+        violations.push(`probe '${endpoint}' drives ${probe.path}, which is not the claimed path ${claimedPath}`);
+        continue;
+      }
+      const path = substitute(probe.path);
+      const body = endpoint === 'POST /v2/oauth/revoke'
+        ? form({ ...clientCreds, token: String(revokeFixture?.access_token ?? '') })
+        : probe.body === undefined ? undefined : substitute(probe.body);
+      const headers = probe.headers ? Object.fromEntries(Object.entries(probe.headers).map(([k, v]) => [k, substitute(v)])) : undefined;
+      const res = await call(probe.method, path, body, headers, endpoint === 'PUT /video' ? { bytes: CHUNK } : {});
+      probed += 1;
+      if (!probe.status.includes(res.status)) {
+        violations.push(`endpoint '${endpoint}' answered ${res.status} (expected ${probe.status.join('/')}): ${JSON.stringify(res.body).slice(0, 160)}`);
+        continue;
+      }
+      if (probe.expect && !probe.expect(res.body)) {
+        violations.push(`endpoint '${endpoint}' answered ${res.status} but the body is not the shape this route returns: ${JSON.stringify(res.body).slice(0, 200)}`);
+      }
+    }
+
+    // Every grant type the snapshot claims must actually dispatch — an unsupported one answers
+    // `unsupported_grant_type`, so a claimed-but-missing grant is caught by name.
+    for (const grantType of snapshot.grantTypes) {
+      const res = await call('POST', '/v2/oauth/token/', form({ ...clientCreds, grant_type: grantType }), { 'content-type': 'application/x-www-form-urlencoded' });
+      const err = (res.body as Record<string, unknown> | null)?.['error'];
+      if (err === 'unsupported_grant_type') violations.push(`grant type '${grantType}' is claimed but the token endpoint does not dispatch it`);
+    }
+
+    // Every resource type the twin projects must be reachable through the protocol — a type with
+    // no observable effect is state a consumer can never see. Each witness reads a VALUE only a
+    // live handler that genuinely projects that type can produce (never a bare status, and never
+    // the snapshot asserting about itself).
+    const witness: Record<string, () => Promise<boolean>> = {
+      // the app's registered NAME is only on the page if the oauth_client row projected
+      oauth_client: async () => String((await call('GET', `/v2/auth/authorize?${authQuery}`)).body).includes('Twin Demo App'),
+      // the persona's username comes back only if the account row projected
+      account: async () => {
+        const t = await probeTokens();
+        const r = await call('GET', '/v2/user/info/?fields=username', undefined, { authorization: `Bearer ${t?.access_token}` });
+        return r.status === 200 && (r.body as Record<string, any>)?.data?.user?.username === ADA.username;
+      },
+      // switching the session changes WHO the authorization page consents as
+      session: async () => {
+        await call('POST', '/_twin/session', JSON.stringify({ union_id: GRACE.unionId }));
+        const shows = String((await call('GET', `/v2/auth/authorize?${authQuery}`)).body).includes(`@${GRACE.username}`);
+        await call('POST', '/_twin/session', JSON.stringify({ union_id: ADA.unionId }));
+        return shows;
+      },
+      // an auth_request that did not project could not have carried a settleable handle
+      auth_request: async () => /name="auth_request" value="ar_[0-9a-f]{32}"/.test(String((await call('GET', `/v2/auth/authorize?${authQuery}`)).body)),
+      // a code that did not project could not be REDEEMED — the witness is the SUCCESS, because
+      // the refusal is exactly what a twin projecting nothing would also say
+      _authorization_code: async () => {
+        const r = await redeem(await mintCode());
+        return r.status === 200 && typeof (r.body as Record<string, unknown>)?.['access_token'] === 'string';
+      },
+      _access_token: async () => {
+        const t = await probeTokens();
+        return (await call('GET', '/v2/user/info/?fields=open_id', undefined, { authorization: `Bearer ${t?.access_token}` })).status === 200;
+      },
+      _refresh_token: async () => {
+        const t = await probeTokens();
+        return (await call('POST', '/v2/oauth/token/', form({ ...clientCreds, grant_type: 'refresh_token', refresh_token: String(t?.refresh_token) }), { 'content-type': 'application/x-www-form-urlencoded' })).status === 200;
+      },
+      _client_token: async () => {
+        const r = await call('POST', '/v2/oauth/token/', form({ ...clientCreds, grant_type: 'client_credentials' }), { 'content-type': 'application/x-www-form-urlencoded' });
+        const b = r.body as Record<string, any>;
+        return r.status === 200 && typeof b?.access_token === 'string' && b.access_token.startsWith('clt.') && b.expires_in === 7200;
+      },
+      // the grant row is what revocation resolves: revoking the ACCESS half must kill the REFRESH
+      // half too, and only a projected grant makes that pair-wide sweep possible
+      grant: async () => {
+        const t = await probeTokens();
+        await call('POST', '/v2/oauth/revoke/', form({ ...clientCreds, token: String(t?.access_token) }), { 'content-type': 'application/x-www-form-urlencoded' });
+        const r = await call('POST', '/v2/oauth/token/', form({ ...clientCreds, grant_type: 'refresh_token', refresh_token: String(t?.refresh_token) }), { 'content-type': 'application/x-www-form-urlencoded' });
+        return r.status === 400;
+      },
+      // a video row that did not project could not appear in the list read
+      video: async () => {
+        const t = await probeTokens();
+        const r = await call('POST', '/v2/video/list/?fields=id,title', JSON.stringify({ max_count: 20 }), { authorization: `Bearer ${t?.access_token}`, 'content-type': 'application/json' });
+        const videos = (r.body as Record<string, any>)?.data?.videos as Array<Record<string, unknown>> | undefined;
+        return r.status === 200 && Array.isArray(videos) && videos.some((v) => v['id'] === ADA_VIDEO.id);
+      },
+      // a publish row is what status/fetch reads once the last chunk has landed: a finished Direct
+      // Post answers PUBLISH_COMPLETE and names its post, which only a projected publish can say
+      publish: async () => {
+        // a token of its own: the grant witness's revoke has swept every token of this (app, user) pair
+        const fresh = String(((await call('POST', '/_twin/tokens', JSON.stringify({ union_id: ADA.unionId, scopes: ['video.publish'] }))).body as Record<string, any>)?.access_token ?? '');
+        const auth = { ...postHeaders, authorization: `Bearer ${fresh}` };
+        const started = ((await call('POST', '/v2/post/publish/video/init/', JSON.stringify({ post_info: { privacy_level: 'PUBLIC_TO_EVERYONE' }, source_info: sourceInfo }), auth)).body as Record<string, any>)?.data ?? {};
+        const url = new URL(String(started.upload_url ?? 'http://invalid.test/video/'));
+        await call('PUT', `${url.pathname}${url.search}`, undefined, { 'content-type': 'video/mp4', 'content-range': `bytes 0-${CHUNK.length - 1}/${CHUNK.length}` }, { bytes: CHUNK });
+        const later = new Date(Date.parse(AT) + 60_000).toISOString();
+        const r = await call('POST', '/v2/post/publish/status/fetch/', JSON.stringify({ publish_id: started.publish_id }), auth, { at: later });
+        return typeof r.body === 'string' && r.body.includes('"status":"PUBLISH_COMPLETE"') && /"publicaly_available_post_id":\[\d{19}\]/.test(r.body);
+      },
+      // an armed rate window turns the NEXT read into the documented 429 + rate_limit_exceeded
+      _rate_window: async () => {
+        const t = await probeTokens();
+        await call('POST', '/_twin/rate_limit', JSON.stringify({ endpoint: 'user_info', open_id: ADA_OPEN_ID, used: 600 }));
+        const r = await call('GET', '/v2/user/info/?fields=open_id', undefined, { authorization: `Bearer ${t?.access_token}` });
+        await call('POST', '/_twin/rate_limit', JSON.stringify({ endpoint: 'user_info', open_id: ADA_OPEN_ID, used: 0 }));
+        return r.status === 429 && (r.body as Record<string, any>)?.error?.code === 'rate_limit_exceeded';
+      },
+    };
+    for (const type of snapshot.resourceTypes) {
+      const probe = witness[type];
+      if (!probe) {
+        violations.push(`resource type '${type}' has no reachability witness — the claim is unverified`);
+        continue;
+      }
+      if (!(await probe())) violations.push(`resource type '${type}' is not reachable through any served endpoint`);
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+
+  return {
+    ok: violations.length === 0,
+    endpointsChecked: snapshot.implementedEndpoints.length,
+    endpointsProbed: probed,
+    resourceTypesChecked: snapshot.resourceTypes.length,
+    violations,
+  };
+}