@volter/twin-xidentity 0.1.0

package/src/xidentity-conformance.ts

@@ -0,0 +1,370 @@
+// X identity 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, and to the two escalating false-greens the tinybird reviews
+// found there:
+//   • 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
+// authorization request, a real consent, a real 302 carrying a real code+state, that code redeemed
+// (PKCE verified) for a real token, and that token answering GET /2/users/me 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 { pkceS256 } from './xidentity-pkce.ts';
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, DEFAULT_PUBLIC_CLIENT_ID, defaultRedirectUris } from './xidentity-store.ts';
+import { handleXIdentityTwinRequest, xIdentityTwinSnapshot, type XResponse } from './xidentity-twin.ts';
+
+export type XIdentityConformanceReport = {
+  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 clients' 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_URI = REDIRECT_URIS[0]!;
+const SCOPE = 'tweet.read users.read offline.access';
+const AT = '2026-02-01T00:00:00.000Z';
+const VERIFIER = 'probe-verifier-0123456789-0123456789-0123456789';
+const ADA = DEFAULT_ACCOUNTS[0]!;
+
+/** Placeholders substituted with values the live flow actually minted. */
+const CODE = 'PROBE_CODE';
+const ACCESS = 'PROBE_ACCESS_TOKEN';
+const REFRESH = 'PROBE_REFRESH_TOKEN';
+
+const authQuery = `response_type=code&client_id=${encodeURIComponent(DEFAULT_CLIENT_ID)}`
+  + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&scope=${encodeURIComponent(SCOPE)}`
+  + `&state=probe-state&code_challenge=${pkceS256(VERIFIER)}&code_challenge_method=S256`;
+
+const form = (params: Record<string, string>) => new URLSearchParams(params).toString();
+const basic = `Basic ${Buffer.from(`${DEFAULT_CLIENT_ID}:${DEFAULT_CLIENT_SECRET}`).toString('base64')}`;
+
+/** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
+const PROBES: Record<string, Probe> = {
+  'GET /i/oauth2/authorize': {
+    method: 'GET',
+    path: `/i/oauth2/authorize?${authQuery}`,
+    status: [200],
+    // The authorize surface is HTML, and its content is the claim: the app name from the client
+    // registry, the signed-in persona, both buttons, and a scope's consent wording — X's own,
+    // from the OpenAPI scope catalog — must all be ON the page.
+    expect: htmlContaining('Authorize app', 'Cancel', 'Twin Demo App', `@${ADA.username}`, 'View all posts you can see'),
+  },
+  'POST /2/oauth2/token': {
+    method: 'POST',
+    path: '/2/oauth2/token',
+    body: form({ grant_type: 'authorization_code', code: CODE, client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT_URI, code_verifier: VERIFIER }),
+    headers: { authorization: basic },
+    status: [200],
+    // Literals, deliberately (the token shape both official SDKs type): lowercase bearer, the
+    // documented 2-hour expiry, an X-shaped base64url token, and a refresh_token because the
+    // grant carries offline.access.
+    expect: (b) =>
+      isObject(b)
+      && b.token_type === 'bearer'
+      && b.expires_in === 7200
+      && typeof b.access_token === 'string'
+      && Buffer.from(String(b.access_token), 'base64url').toString('utf8').includes(':at:')
+      && b.scope === SCOPE
+      && typeof b.refresh_token === 'string'
+      && Buffer.from(String(b.refresh_token), 'base64url').toString('utf8').includes(':rt:'),
+  },
+  'POST /2/oauth2/revoke': {
+    method: 'POST',
+    path: '/2/oauth2/revoke',
+    body: form({ token: ACCESS, client_id: DEFAULT_CLIENT_ID, token_type_hint: 'access_token' }),
+    headers: { authorization: basic },
+    status: [200],
+    expect: (b) => isObject(b) && b.revoked === true && Object.keys(b).length === 1,
+  },
+  'GET /2/users/me': {
+    method: 'GET',
+    path: '/2/users/me',
+    headers: { authorization: `Bearer ${ACCESS}` },
+    status: [200],
+    expect: (b) =>
+      isObject(b)
+      && isObject(b.data)
+      && b.data['id'] === ADA.id
+      && b.data['username'] === ADA.username
+      && b.data['name'] === ADA.name,
+  },
+};
+
+/**
+ * Every VENDOR method/path pair a reader of `routeXIdentityTwinRequest` can see the router branch
+ * on, PLUS near-miss pairs (wrong method on a claimed path, the OpenAPI's alternate authorize
+ * host path, a sibling /2 users route) that must answer the vendor-shaped not-found envelope.
+ * Written by hand from the router, so the census can catch VENDOR surface that is served without
+ * being claimed. The `/_twin/*` control routes `twinControl` dispatches are DELIBERATELY outside
+ * this census: they are twin-only scaffolding (ADDING_A_TWIN.md §6), answer non-404 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 instead.
+ */
+const ROUTER_SURFACE: Array<[string, string]> = [
+  ['GET', `/i/oauth2/authorize?${authQuery}`],
+  ['POST', '/i/oauth2/authorize'],
+  ['POST', '/2/oauth2/token'],
+  ['GET', '/2/oauth2/token'],
+  ['POST', '/2/oauth2/revoke'],
+  ['GET', '/2/oauth2/revoke'],
+  ['GET', '/2/users/me'],
+  ['POST', '/2/users/me'],
+  ['GET', '/2/oauth2/authorize'],
+  ['GET', '/2/users/by'],
+  ['GET', '/oauth2/token'],
+];
+
+const isNotFoundEnvelope = (res: XResponse): boolean =>
+  res.status === 404
+  && isObject(res.body)
+  && res.body['title'] === 'Not Found Error'
+  && res.body['type'] === 'about:blank';
+
+export async function checkXIdentityConformance(opts: { root?: string } = {}): Promise<XIdentityConformanceReport> {
+  void opts;
+  const snapshot = xIdentityTwinSnapshot();
+  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 log them out of their own twin.
+  const root = mkdtempSync(join(tmpdir(), 'xidentity-conformance-'));
+  const call = (method: string, path: string, body?: string, headers?: Record<string, string>): Promise<XResponse> =>
+    handleXIdentityTwinRequest({ method, path, ...(body !== undefined ? { body } : {}), ...(headers ? { headers } : {}), root, origin: DEMO_ORIGIN, occurredAt: AT });
+
+  /** Drive a full consent and return the minted code (empty string on any failure). */
+  const mintCode = async (scope = SCOPE): Promise<string> => {
+    const q = authQuery.replace(`scope=${encodeURIComponent(SCOPE)}`, `scope=${encodeURIComponent(scope)}`);
+    const a = await call('GET', `/i/oauth2/authorize?${q}`);
+    const rid = /name="auth_request" value="([^"]+)"/.exec(String(a.body))?.[1] ?? '';
+    const d = await call('POST', '/_twin/consent', form({ auth_request: rid, decision: 'allow' }));
+    return new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+  };
+  const redeem = (code: string) =>
+    call('POST', '/2/oauth2/token', form({ grant_type: 'authorization_code', code, client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT_URI, code_verifier: VERIFIER }), { authorization: basic });
+
+  let probed = 0;
+  try {
+    // ── the ROUND TRIP, driven for real, before any probing ──
+    const authRes = await call('GET', `/i/oauth2/authorize?${authQuery}`);
+    const requestId = /name="auth_request" value="([^"]+)"/.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 = await call('POST', '/_twin/consent', form({ auth_request: requestId, decision: 'allow' }));
+    const location = decision.headers?.location ?? '';
+    if (decision.status !== 302 || !location.startsWith(REDIRECT_URI)) {
+      violations.push(`consent did not 302 back to the registered redirect_uri: ${decision.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 (!Buffer.from(code, 'base64url').toString('utf8').includes(':ac:')) {
+      violations.push(`the redirect did not carry an X-shaped authorization code: ${code}`);
+    }
+    const extras = [...back.searchParams.keys()].filter((k) => k !== 'state' && k !== 'code');
+    if (extras.length > 0) {
+      // The documented callback carries EXACTLY state and code; 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 X'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 /2/users/me with the consenting persona and the
+    // documented rate headers.
+    const me = await call('GET', '/2/users/me', undefined, { authorization: `Bearer ${tokens?.access_token}` });
+    const meBody = me.body as Record<string, any>;
+    if (me.status !== 200 || meBody?.data?.id !== ADA.id || meBody?.data?.username !== ADA.username) {
+      violations.push(`the minted token did not answer /2/users/me with the consenting persona: ${me.status} ${JSON.stringify(me.body).slice(0, 160)}`);
+    }
+    if (me.headers?.['x-rate-limit-limit'] !== '75' || typeof me.headers?.['x-rate-limit-remaining'] !== 'string' || typeof me.headers?.['x-rate-limit-reset'] !== 'string') {
+      violations.push(`/2/users/me did not carry the documented x-rate-limit-* headers: ${JSON.stringify(me.headers)}`);
+    }
+    // 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_request') {
+      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', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+    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', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+    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]}`;
+      if (!isNotFoundEnvelope(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 (client, user) grant family, which would take the users/me probe's 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({ account_id: DEFAULT_ACCOUNTS[1]!.id }));
+    const revokeFixture = await probeTokens();
+    await call('POST', '/_twin/session', JSON.stringify({ account_id: ADA.id }));
+    const meFixture = await probeTokens();
+    const tokenProbeCode = await mintCode();
+
+    const substitute = (s: string) =>
+      s.replace(CODE, tokenProbeCode)
+        .replace(ACCESS, String(meFixture?.access_token ?? ''))
+        .replace(REFRESH, String(meFixture?.refresh_token ?? ''));
+
+    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.split('?')[0] ?? '') !== 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 /2/oauth2/revoke'
+        ? form({ token: String(revokeFixture?.access_token ?? ''), client_id: DEFAULT_CLIENT_ID, token_type_hint: '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);
+      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', '/2/oauth2/token', form({ grant_type: grantType, client_id: DEFAULT_PUBLIC_CLIENT_ID }));
+      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 screen if the oauth_client row projected
+      oauth_client: async () => String((await call('GET', `/i/oauth2/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', '/2/users/me', undefined, { authorization: `Bearer ${t?.access_token}` });
+        return r.status === 200 && (r.body as Record<string, any>)?.data?.username === ADA.username;
+      },
+      // switching the session changes WHO the authorize screen consents as
+      session: async () => {
+        const grace = DEFAULT_ACCOUNTS[1]!;
+        await call('POST', '/_twin/session', JSON.stringify({ account_id: grace.id }));
+        const shows = String((await call('GET', `/i/oauth2/authorize?${authQuery}`)).body).includes(`@${grace.username}`);
+        await call('POST', '/_twin/session', JSON.stringify({ account_id: ADA.id }));
+        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', `/i/oauth2/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', '/2/users/me', undefined, { authorization: `Bearer ${t?.access_token}` })).status === 200;
+      },
+      refresh_token: async () => {
+        const t = await probeTokens();
+        return (await call('POST', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(t?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic })).status === 200;
+      },
+      // 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', '/2/oauth2/revoke', form({ token: String(t?.access_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+        const r = await call('POST', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(t?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+        return r.status === 400;
+      },
+      // an armed rate window turns the NEXT read into the documented 429 + code 88
+      rate_window: async () => {
+        const t = await probeTokens();
+        await call('POST', '/_twin/rate_limit', JSON.stringify({ account_id: ADA.id, used: 75 }));
+        const r = await call('GET', '/2/users/me', undefined, { authorization: `Bearer ${t?.access_token}` });
+        await call('POST', '/_twin/rate_limit', JSON.stringify({ account_id: ADA.id, used: 0 }));
+        const errs = (r.body as Record<string, any>)?.errors;
+        return r.status === 429 && Array.isArray(errs) && errs[0]?.code === 88;
+      },
+    };
+    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,
+  };
+}

package/src/xidentity-connector.ts

@@ -0,0 +1,269 @@
+// X identity CONNECTOR — the live-vendor pull path.
+//
+// PULL (real → twin): the twin's persona registry is only as useful as the identities in it, and
+// this surface exposes exactly ONE authenticated read: `GET /2/users/me`. A pull observes the real
+// account behind the operator's own user access token (every modelled user.field requested) and
+// folds it into the observed log.
+//
+// WHAT A PULL CANNOT OBSERVE, recorded as reasoned gaps rather than faked:
+//   • the OAuth CLIENT registry — X Apps are created in the developer portal; no API reads them
+//     (`xidentity.connector.pull_clients`, todo);
+//   • the GRANT (which scopes this token holds) — X has no tokeninfo/introspection endpoint; a
+//     users/me success evidences tweet.read+users.read but cannot enumerate the rest
+//     (`xidentity.connector.pull_grants`, todo).
+//
+// PUSH IS AN HONEST GAP, not an omission: X exposes NO write API for this identity surface —
+// clients live in the developer portal, and a user's app authorizations are managed at
+// x.com/settings. `pushPendingXIdentityActions` exists only to report that; filed as
+// `xidentity.connector.push` (todo). ADDING_A_TWIN.md §10 sanctions exactly this for a vendor
+// with no write path.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO X
+// credential and import NO network client. Offline/tests pass a fake executor; live runs pass
+// `liveXIdentityExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, deployableEntries, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, TwinAction, SyncResource } from '@volter/world-core';
+import { XIdentityBudget, XIdentityBudgetError, xIdentityBudgetPath, xIdentityCallWeight, type XIdentityBudgetOptions } from './xidentity-budget.ts';
+
+const SERVICE = 'xidentity';
+
+/** X's real hosts — the live executor's routing table. ONLY mapped paths may be called live.
+ *  The token/revoke paths are mapped so a live BYOT rehearsal can refresh or revoke the
+ *  operator's OWN token through the guarded path — nothing else on api.x.com is reachable. */
+const HOSTS: Record<string, string> = {
+  '/2/users/me': 'https://api.x.com',
+  '/2/oauth2/token': 'https://api.x.com',
+  '/2/oauth2/revoke': 'https://api.x.com',
+};
+
+/** The modelled user.fields a pull requests — every field the twin's account rows can hold. */
+export const PULL_USER_FIELDS = [
+  'created_at',
+  'description',
+  'location',
+  'profile_image_url',
+  'protected',
+  'public_metrics',
+  'url',
+  'verified',
+  'verified_type',
+  'confirmed_email',
+] as const;
+
+/**
+ * The injected real-X boundary. `execute` issues ONE request and returns the parsed JSON body.
+ * A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type XIdentityExecute = (
+  method: 'GET' | 'POST',
+  path: string,
+  init?: { headers?: Record<string, string>; body?: string },
+) => Promise<Record<string, any>>;
+
+export type LiveXIdentityOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: XIdentityBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: XIdentityBudgetOptions;
+};
+
+/**
+ * A live executor against the real X API, holding the operator's OWN user access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live X request, and therefore the one place the rate
+ * budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request goes
+ * out (`checkBudget`, which THROWS instead of returning when the ceiling or a cooldown says stop)
+ * and the response is fed back (`recordCall`) so a 429 / `Retry-After` becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching X. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client
+ * (`assertBudgetGuardIntact`).
+ */
+export function liveXIdentityExecute(accessToken: string, opts: LiveXIdentityOptions = {}): XIdentityExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, XIdentityBudget, 'liveXIdentityExecute')
+    : new XIdentityBudget({ ...(opts.budgetOptions ?? {}), token: accessToken });
+  const explicitLedger = opts.budgetOptions?.path !== undefined || opts.budgetOptions?.root !== undefined;
+  if (opts.budget && !explicitLedger && budget.path !== xIdentityBudgetPath({ token: accessToken })) {
+    throw new Error('liveXIdentityExecute: injected budget is not keyed to the credential this client will send');
+  }
+  return async (method, path, init) => {
+    const bare = path.split('?')[0] ?? path;
+    const host = HOSTS[bare];
+    if (!host) throw new Error(`liveXIdentityExecute: refusing to call an unmapped X path: ${bare}`);
+    const weight = xIdentityCallWeight(method, path);
+    if (Object.keys(init?.headers ?? {}).some((name) => name.toLowerCase() === 'authorization')) {
+      throw new Error('liveXIdentityExecute: refusing an injected Authorization header; the guarded credential is fixed at construction');
+    }
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${host}${path}`, {
+      method,
+      headers: { ...(init?.headers ?? {}), Authorization: `Bearer ${accessToken}` },
+      ...(init?.body !== undefined ? { body: init.body } : {}),
+    });
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => {
+      resHeaders[k.toLowerCase()] = v;
+    });
+    // Settles the reservation and, on a back-off signal, arms the cooldown. The cooldown is
+    // persisted before body parsing or any throw, so even an HTML/plain-text 429 survives it.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer X ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof XIdentityBudgetError) || !res.ok) throw error;
+    }
+    const raw = await res.text();
+    let parsed: Record<string, any>;
+    try {
+      parsed = raw === '' ? {} : JSON.parse(raw) as Record<string, any>;
+    } catch {
+      throw new Error(`x identity returned non-JSON for ${method} ${bare}: HTTP ${res.status}`);
+    }
+    // A REFUSED pull is NOT an empty account. X can answer failures with a problem envelope
+    // (`title`/`type`), a legacy `errors` array, OR a 200 whose body carries partial `errors` —
+    // a status check alone cannot tell refusal from emptiness, so every refusal shape throws.
+    if (res.status >= 400) throw new Error(`x identity refused ${method} ${bare}: HTTP ${res.status} ${JSON.stringify(parsed)}`);
+    if (parsed && typeof parsed === 'object' && !('data' in parsed) && ('errors' in parsed || 'title' in parsed)) {
+      throw new Error(`x identity refused ${method} ${bare}: ${JSON.stringify(parsed)}`);
+    }
+    return parsed;
+  };
+}
+
+/** Map a real `GET /2/users/me` response → the account (persona) SyncResource. Nothing invented:
+ *  a field the response omits records NOTHING rather than a placeholder — including username and
+ *  name (§9 round one: a `?? null` there let a partial-errors reply fold null over a previously
+ *  pulled persona's real values). */
+export function mapUsersMeAccount(body: Record<string, any>): SyncResource {
+  const data = (body?.data ?? {}) as Record<string, any>;
+  return {
+    type: 'account',
+    id: String(data.id ?? ''),
+    fields: {
+      ...(typeof data.username === 'string' ? { username: data.username } : {}),
+      ...(typeof data.name === 'string' ? { name: data.name } : {}),
+      ...(typeof data.created_at === 'string' ? { createdAt: data.created_at } : {}),
+      ...(typeof data.description === 'string' ? { description: data.description } : {}),
+      ...(typeof data.location === 'string' ? { location: data.location } : {}),
+      ...(typeof data.profile_image_url === 'string' ? { profileImageUrl: data.profile_image_url } : {}),
+      ...(typeof data.protected === 'boolean' ? { protectedAccount: data.protected } : {}),
+      ...(data.public_metrics && typeof data.public_metrics === 'object' ? { publicMetrics: data.public_metrics } : {}),
+      ...(typeof data.url === 'string' ? { url: data.url } : {}),
+      ...(typeof data.verified === 'boolean' ? { verified: data.verified } : {}),
+      ...(typeof data.verified_type === 'string' ? { verifiedType: data.verified_type } : {}),
+      ...(typeof data.confirmed_email === 'string' ? { confirmedEmail: data.confirmed_email } : {}),
+      pulled: true,
+    },
+  };
+}
+
+/**
+ * A MOVING pull timestamp, forced strictly increasing within the process — never a pinned
+ * constant (ADDING_A_TWIN.md §6: under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the delta silently vanishes).
+ */
+let lastPollMs = 0;
+function pollTimestamp(): string {
+  const now = Date.now();
+  lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+  return new Date(lastPollMs).toISOString();
+}
+
+async function collectXIdentity(execute: XIdentityExecute): Promise<SyncResource[]> {
+  const body = await execute('GET', `/2/users/me?user.fields=${PULL_USER_FIELDS.join(',')}`);
+  // The refusal check lives HERE, not only in the live executor: an injected executor (or a
+  // vendor 200 carrying a problem envelope) must never fold an empty account over observed state.
+  // A reply without `data`, or whose id is not an X-shaped NUMERIC string, is a refusal or a
+  // malformed body, and either one THROWS. The numeric check also keeps a foreign id out of the
+  // `clientId:sub` grant-key space (§9 round two: the scaffolding refuses ":" but the pull path
+  // is where foreign ids enter).
+  const id = (body as Record<string, any> | null)?.['data']?.id;
+  if (!body || typeof body !== 'object' || typeof id !== 'string' || !/^\d+$/.test(id)) {
+    throw new Error(`x identity pull refused or malformed: ${JSON.stringify(body).slice(0, 200)}`);
+  }
+  return [mapUsersMeAccount(body)];
+}
+
+/** PULL the operator's own identity into the twin's observed log (idempotent). */
+export async function pullXIdentity(execute: XIdentityExecute, root?: string, occurredAt?: string): Promise<number> {
+  const resources = await collectXIdentity(execute);
+  ((__at) => observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt ?? pollTimestamp());
+  return resources.length;
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real X identity surface
+ * and fold it into the twin in ONE observation, returning the standard
+ * `{ observed, deltasAppended }`. Idempotent — a re-pull of identical state appends nothing.
+ */
+export async function syncXIdentityFromReal(
+  execute: XIdentityExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const occurredAt = opts.occurredAt ?? pollTimestamp();
+  const resources = await collectXIdentity(execute);
+  const result = ((__at) => observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt);
+  return { observed: resources.length, deltasAppended: result.appended };
+}
+
+/**
+ * PUSH — structurally impossible on this vendor, and reported as such rather than faked. X has no
+ * API that creates an OAuth App, seeds a user, or grants a scope: those are developer-portal and
+ * x.com/settings actions. This never confirms an action and never pretends to have pushed one; it
+ * returns the pending count so a caller can see exactly how much local state has no upstream home.
+ */
+export function pushPendingXIdentityActions(root?: string): { pushed: 0; unpushable: number } {
+  return { pushed: 0, unpushable: deployableEntries(SERVICE, root).length };
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+
+/** An `XIdentityExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function xIdentityExecuteOver(execute: RemoteExecute): XIdentityExecute {
+  return async (method, path, init) => {
+    const res = await execute({
+      method,
+      path,
+      headers: { accept: 'application/json', authorization: 'Bearer twin', ...(init?.headers ?? {}) },
+      ...(init?.body === undefined ? {} : { body: init.body }),
+    });
+    try { return JSON.parse(res.body || '{}'); } catch { return {}; }
+  };
+}
+
+/** The refresh adapter: `GET /2/users/me` is a real read of the real account, so the operator's own
+ *  identity comes back from X itself. It is also the ONLY thing this vendor lets a client read
+ *  about its own identity surface — Apps, grants and scopes are portal state, not API state. */
+export async function syncXIdentityFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  return syncXIdentityFromReal(xIdentityExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  });
+}
+
+/**
+ * The perform adapter — and its answer is always the same, honestly.
+ *
+ * X publishes NO API that creates an OAuth App, seeds a user, or grants a scope: those are
+ * developer-portal and x.com/settings actions a person takes in a browser. So nothing a world
+ * writes here has an upstream home, and saying so is the whole point — the pack's push has always
+ * reported the unpushable count rather than confirming an action it never made.
+ */
+export async function performXIdentityAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  void execute;
+  const op = action.operation ?? `${action.subject.type}.update`;
+  return {
+    externalId: action.subject.id,
+    data: { performed: false, reason: `${op} has nowhere to go: X creates OAuth Apps, users and scope grants in the developer portal and in account settings, and publishes no API for any of them` },
+  };
+}