@volter/twin-veriff 0.1.0

package/src/veriff-capabilities.ts

@@ -0,0 +1,1157 @@
+// Veriff capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from what Veriff's Public API v1 actually does — NOT from what this twin has built. This is the
+// honest denominator: many entries are `todo` and will stay that way until the twin reaches them.
+// `verify()` (required to count as done) is ground truth; every `expected:'done'` is genuinely
+// claimed, so a broken one shows as a regression.
+//
+// ── WHERE THE DENOMINATOR CAME FROM ─────────────────────────────────────────────────────────
+// Veriff publishes `devdocs.veriff.com/llms.txt`, a machine-readable index of all 140 doc pages,
+// and every `/apidocs/*` page EMBEDS its real OpenAPI 3.0.0 document. The surface below was
+// enumerated from that index top-down: the 18 documented Public API v1 operations, the three
+// Feedback/Fraud API operations, the sync-api registry operation, and the per-SOLUTION doc pages
+// (Document+Selfie, Document-only, Biometric Authentication/Liveness, Selfie2Selfie, Age
+// Estimation, Unstructured Docs, Proof of Address, AML screening, NFC/ePassport, UK DIATF, and the
+// nine database verifications). Statuses, codes, error bodies and payload shapes are quoted from
+// those documents; where two Veriff pages CONTRADICT each other, this manifest says so and files a
+// todo rather than picking a side silently.
+//
+// ── NO UI CAPABILITIES ──────────────────────────────────────────────────────────────────────
+// Veriff is an API-first vendor for the party that integrates it: creating a session, embedding the
+// hosted flow, receiving the decision webhook and reading the decision is ALL code. The only screen
+// in the loop is Veriff's own HOSTED capture flow (camera, document capture, liveness), which is
+// Veriff's own product surface rather than a customer-operated console; the twin returns a real
+// session `url` so the redirect/embed path is exercised. The reference consumer settles it
+// the same way: dub embeds Veriff's hosted frame and then built its OWN admin review screen rather
+// than working in Veriff's. So this pack ships no mirror and has zero `ui` capabilities. See
+// README.md `## Coverage` → `### No UI mirror`, and the ui-scope.json entry, which records the
+// counter-argument rather than pretending the call was obvious.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, verifyBoundary, type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+import { VERIFF_BUDGET_CEILING, VERIFF_CALL_WEIGHTS, VeriffBudget, VeriffBudgetError } from './veriff-budget.ts';
+import {
+  liveVeriffExecute,
+  mapSessionAttempt,
+  mapSessionDecision,
+  mapSessionMedia,
+  pullVeriffAttempts,
+  pullVeriffDecisions,
+  pullVeriffMedia,
+  pushPendingVeriffActions,
+  signaturePayloadFor,
+  syncVeriffFromReal,
+  veriffRequestForAction,
+  type VeriffExecute,
+} from './veriff-connector.ts';
+import { buildSignedDelivery, verifyWebhook, VeriffWebhookVerificationError } from './veriff-events.ts';
+import { createVeriffTwinServer, veriffResponseHeaders } from './veriff-server.ts';
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, veriffSignature, verifyVeriffSignature } from './veriff-signature.ts';
+import {
+  handleVeriffTwinRequest,
+  TWIN_API_KEY,
+  TWIN_SHARED_SECRET,
+  VERIFF_DECISION_CODES,
+  type VeriffResponse,
+} from './veriff-twin.ts';
+
+// ── driving the twin: fresh root, correct auth, pinned-but-distinct instants ──
+
+type Step = { m: string; p: string; b?: unknown; noAuth?: boolean; sig?: string };
+type Body = Record<string, any>;
+type H = (s: Step) => Promise<VeriffResponse>;
+
+/**
+ * Instants are pinned (deterministic ids/timestamps) but DISTINCT per write. The kernel dedupes an
+ * action by content + MILLISECOND, so a verify that repeats an identical transition under one fixed
+ * timestamp is a coin flip — same-ms lands as `replayed`, different-ms as a second write. Pinning a
+ * per-call ordinal makes the outcome chosen rather than rolled.
+ */
+let tick = 0;
+const at = () => new Date(Date.UTC(2026, 7, 1, 0, 0, 0, tick++ % 1000)).toISOString();
+
+/** Sign a request the way the vendor requires: body for POST/PATCH, path resource id for GET/DELETE. */
+function signFor(m: string, p: string, raw: string): string {
+  const segments = (p.split('?')[0] ?? p).replace(/^\/v1\/?/, '').replace(/^\/+/, '').split('/');
+  return veriffSignature(m === 'GET' || m === 'DELETE' ? (segments[1] ?? '') : raw, TWIN_SHARED_SECRET);
+}
+
+async function withRoot(steps: (h: H, root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'veriff-cap-'));
+  const h: H = (s) => {
+    const raw = s.b === undefined ? '' : JSON.stringify(s.b);
+    const headers: Record<string, string> = s.noAuth ? {} : { [AUTH_CLIENT_HEADER]: TWIN_API_KEY, [HMAC_SIGNATURE_HEADER]: s.sig ?? signFor(s.m, s.p, raw) };
+    return handleVeriffTwinRequest({ method: s.m, path: s.p, ...(s.b === undefined ? {} : { body: raw }), headers, root, occurredAt: at() });
+  };
+  try { return await verifyBoundary('veriff.withRoot', () => steps(h, root)); } finally { rmSync(root, { recursive: true, force: true }); }
+}
+
+const ok = (r: VeriffResponse) => r.status >= 200 && r.status < 300;
+const env = (r: VeriffResponse) => (r.body as { status?: string }).status;
+const b = (r: VeriffResponse) => r.body as Body;
+const failed = (r: VeriffResponse, status: number, code: string) => r.status === status && env(r) === 'fail' && b(r).code === code && typeof b(r).message === 'string' && b(r).message.length > 0;
+
+/** Create a session and return its id (and the raw response, for the callers that assert on it). */
+async function open(h: H, verification: Record<string, unknown> = {}): Promise<{ id: string; res: VeriffResponse }> {
+  const res = await h({ m: 'POST', p: '/v1/sessions', b: { verification } });
+  return { id: String(b(res).verification?.id ?? ''), res };
+}
+
+/** Drive a session all the way to a terminal decision, through the real PATCH + the twin-only arm. */
+async function decide(h: H, id: string, status: string, extra: Record<string, unknown> = {}): Promise<VeriffResponse> {
+  await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+  return h({ m: 'POST', p: `/v1/_twin/sessions/${id}/decision`, b: { status, ...extra } });
+}
+
+const IMG = 'data:image/jpeg;base64,aGVsbG8td29ybGQ='; // "hello-world" → 11 decoded bytes
+
+// ── shorthands ──
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+
+/**
+ * The AREA CENSUS — enumerated TOP-DOWN from Veriff's own documentation navigation (the
+ * `llms.txt` index: API reference groups + one page per solution), NOT derived from the manifest
+ * below. Deriving it from the manifest would make the bijection check a tautology; the point is
+ * that a whole Veriff product area cannot silently vanish from the denominator.
+ */
+export const VERIFF_AREAS = [
+  'sessions',
+  'decisions',
+  'attempts',
+  'person',
+  'media',
+  'auth',
+  'webhooks',
+  'errors',
+  'watchlist',
+  'idv',
+  'proof_of_address',
+  'database_verification',
+  'fraud',
+  'collected_data',
+  'faces',
+  'registry',
+  'platform',
+  'sdk',
+  'connector',
+] as const;
+
+export const VERIFF_CAPABILITIES: CapabilitySpec[] = [
+  // ── Sessions (the entry point of every integration) ───────────────────────
+  done('veriff.sessions.create', 'sessions', 'POST /v1/sessions — create a verification session (201 + the seven required verification fields)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id, res } = await open(h, { vendorData: 'partner_123', endUserId: 'eu_1' });
+      const v = b(res).verification;
+      return res.status === 201 && env(res) === 'success'
+        && typeof id === 'string' && id.length === 36
+        && v.status === 'created' && v.vendorData === 'partner_123' && v.endUserId === 'eu_1'
+        && typeof v.sessionToken === 'string' && typeof v.host === 'string' && typeof v.url === 'string';
+    })),
+  done('veriff.sessions.create_minimal', 'sessions', 'POST /v1/sessions accepts the documented minimum body `{"verification":{}}`, returning vendorData/endUserId as null', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { res } = await open(h);
+      const v = b(res).verification;
+      return res.status === 201 && v.vendorData === null && v.endUserId === null && v.status === 'created';
+    })),
+  done('veriff.sessions.url_is_host_plus_token', 'sessions', 'verification.url is exactly host + "/v/" + sessionToken (the documented composition the hosted flow is opened with)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { res } = await open(h);
+      const v = b(res).verification;
+      return v.url === `${v.host}/v/${v.sessionToken}` && String(v.sessionToken).split('.').length === 3;
+    })),
+  done('veriff.sessions.create_requires_verification', 'sessions', 'POST /v1/sessions without a `verification` object → 400 "Validation failed" (1101)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const miss = await h({ m: 'POST', p: '/v1/sessions', b: {} });
+      const wrong = await h({ m: 'POST', p: '/v1/sessions', b: { verification: 'nope' } });
+      return failed(miss, 400, '1101') && failed(wrong, 400, '1101');
+    })),
+  done('veriff.sessions.create_vendor_data_type', 'sessions', 'POST /v1/sessions rejects a non-string vendorData → 400 (1501)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/sessions', b: { verification: { vendorData: 42 } } });
+      // The message is asserted as a STRING LITERAL, quoted from Veriff's troubleshooting-codes
+      // table. Comparing against VERIFF_ERROR_MESSAGES — which is what the handler emits — would be
+      // two constants agreeing with each other: a §9 round-two review replaced all four constants
+      // with garbage and got ZERO regressions.
+      return failed(r, 400, '1501')
+        && b(r).message === '`vendorData` must be a string. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer\'s domain)';
+    })),
+  done('veriff.sessions.create_vendor_data_length', 'sessions', 'POST /v1/sessions rejects a vendorData over the documented 1,000-character limit → 400 (1500)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const long = await h({ m: 'POST', p: '/v1/sessions', b: { verification: { vendorData: 'x'.repeat(1001) } } });
+      const edge = await h({ m: 'POST', p: '/v1/sessions', b: { verification: { vendorData: 'x'.repeat(1000) } } });
+      return failed(long, 400, '1500')
+        && b(long).message === '`vendorData` field cannot be more than 1000 symbols. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer\'s domain)'
+        && edge.status === 201;
+    })),
+  done('veriff.sessions.create_https_callback_only', 'sessions', 'POST /v1/sessions rejects a non-HTTPS callback → 400 "Only HTTPS return URLs are allowed." (1302)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const http = await h({ m: 'POST', p: '/v1/sessions', b: { verification: { callback: 'http://example.test/hook' } } });
+      const junk = await h({ m: 'POST', p: '/v1/sessions', b: { verification: { callback: 'not-a-url' } } });
+      const good = await h({ m: 'POST', p: '/v1/sessions', b: { verification: { callback: 'https://example.test/hook' } } });
+      return failed(http, 400, '1302') && b(http).message === 'Only HTTPS return URLs are allowed.'
+        && failed(junk, 400, '1302') && good.status === 201;
+    })),
+  done('veriff.sessions.no_get_endpoint', 'sessions', 'Veriff has NO GET /v1/sessions/{id} — the twin refuses to invent one, and answers the vendor\'s 404', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // The mirror image of "unmodeled ops fail like the vendor": a twin must not serve a convenient
+      // read the vendor does not have. Veriff's API reference index lists only POST/PATCH/DELETE on
+      // /v1/sessions/{id}; state is read from the webhooks and the decision endpoint, which is why
+      // the reference consumer stores its own veriffSessionId + status.
+      const { id } = await open(h, { vendorData: 'no-get' });
+      const invented = await h({ m: 'GET', p: `/v1/sessions/${id}` });
+      // …while the sub-resources the vendor DOES document all answer for the same live session, so
+      // this is a routing fact about one path, not a dead twin.
+      const decision = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const attempts = await h({ m: 'GET', p: `/v1/sessions/${id}/attempts` });
+      const media = await h({ m: 'GET', p: `/v1/sessions/${id}/media` });
+      return failed(invented, 404, '1101')
+        && ok(decision) && b(decision).verification === null
+        && ok(attempts) && Array.isArray(b(attempts).verifications)
+        && ok(media) && Array.isArray(b(media).images);
+    })),
+  done('veriff.sessions.unknown_session_404', 'sessions', 'Every session sub-resource answers 404 "Resource not found" (1101) for an unknown session id', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const ghost = '00000000-0000-4000-8000-000000000000';
+      for (const p of [`/v1/sessions/${ghost}/decision`, `/v1/sessions/${ghost}/person`, `/v1/sessions/${ghost}/attempts`, `/v1/sessions/${ghost}/media`]) {
+        const r = await h({ m: 'GET', p });
+        if (!failed(r, 404, '1101') || b(r).message !== 'Resource not found') return false;
+      }
+      const patch = await h({ m: 'PATCH', p: `/v1/sessions/${ghost}`, b: { verification: { status: 'submitted' } } });
+      const del = await h({ m: 'DELETE', p: `/v1/sessions/${ghost}` });
+      return failed(patch, 404, '1101') && failed(del, 404, '1101');
+    })),
+
+  done('veriff.sessions.patch_submitted', 'sessions', 'PATCH /v1/sessions/{id} {verification:{status:"submitted"}} — the documented created→submitted transition', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const p = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      const g = await h({ m: 'GET', p: `/v1/_twin/sessions/${id}` });
+      return ok(p) && b(p).verification.status === 'submitted' && b(p).verification.id === id && b(g).verification.status === 'submitted';
+    })),
+  done('veriff.sessions.patch_rejects_other_statuses', 'sessions', 'PATCH /v1/sessions/{id} accepts ONLY "submitted" — any other value is 400 "Validation failed"', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const approved = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'approved' } } });
+      const empty = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: {} } });
+      const g = await h({ m: 'GET', p: `/v1/_twin/sessions/${id}` });
+      return failed(approved, 400, '1101') && failed(empty, 400, '1101') && b(g).verification.status === 'created';
+    })),
+  done('veriff.sessions.patch_already_submitted', 'sessions', 'PATCH a session that is already submitted → 400 "Session has already been submitted"', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      const again = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      return failed(again, 400, '1101') && b(again).message === 'Session has already been submitted';
+    })),
+  done('veriff.sessions.delete', 'sessions', 'DELETE /v1/sessions/{id} — id-only success body, and the session is gone afterwards', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const d = await h({ m: 'DELETE', p: `/v1/sessions/${id}` });
+      const g = await h({ m: 'GET', p: `/v1/_twin/sessions/${id}` });
+      // The published example is exactly `{status:'success', verification:{id}}` — nothing else.
+      return ok(d) && env(d) === 'success' && b(d).verification.id === id
+        && Object.keys(b(d).verification).length === 1 && failed(g, 404, '1101');
+    })),
+  done('veriff.sessions.delete_in_progress', 'sessions', 'DELETE a submitted session → 400 "Session in progress." (1306), and the session survives', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      const d = await h({ m: 'DELETE', p: `/v1/sessions/${id}` });
+      const g = await h({ m: 'GET', p: `/v1/_twin/sessions/${id}` });
+      return failed(d, 400, '1306') && b(d).message === 'Session in progress.' && ok(g) && b(g).verification.status === 'submitted';
+    })),
+  done('veriff.sessions.delete_not_completed', 'sessions', 'DELETE a session parked in review → 400 "Session is not in a completed status." (1305)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'review');
+      const d = await h({ m: 'DELETE', p: `/v1/sessions/${id}` });
+      return failed(d, 400, '1305') && b(d).message === 'Session is not in a completed status.';
+    })),
+  done('veriff.sessions.delete_after_decision', 'sessions', 'DELETE is allowed from every completed status the endpoint lists (approved/declined/expired/abandoned)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      for (const status of ['approved', 'declined', 'expired', 'abandoned']) {
+        const { id } = await open(h);
+        await decide(h, id, status);
+        const d = await h({ m: 'DELETE', p: `/v1/sessions/${id}` });
+        if (!ok(d) || b(d).verification.id !== id) return false;
+      }
+      return true;
+    })),
+
+  // ── Decisions (what an integration is actually waiting for) ───────────────
+  done('veriff.decisions.pending_is_null', 'decisions', 'GET /v1/sessions/{id}/decision before a decision → 200 with `verification: null` (the documented poll-again answer)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const before = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      const submitted = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      // Still null AFTER submission — the doc is explicit that a session can be `submitted` while
+      // the decision is still being processed.
+      return ok(before) && env(before) === 'success' && b(before).verification === null
+        && ok(submitted) && b(submitted).verification === null;
+    })),
+  done('veriff.decisions.approved', 'decisions', 'An approved decision carries status "approved", code 9001, a decisionTime and an attemptId', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h, { vendorData: 'partner_9' });
+      await decide(h, id, 'approved');
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const v = b(d).verification;
+      return ok(d) && v.id === id && v.status === 'approved' && v.code === 9001
+        && v.vendorData === 'partner_9' && typeof v.decisionTime === 'string' && typeof v.attemptId === 'string' && v.reason === null;
+    })),
+  done('veriff.decisions.declined_with_reason', 'decisions', 'A declined decision carries code 9102 plus the granular reason/reasonCode pair', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'declined', { reason: 'Suspected document tampering', reasonCode: 102 });
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const v = b(d).verification;
+      return v.status === 'declined' && v.code === 9102 && v.reason === 'Suspected document tampering' && v.reasonCode === 102;
+    })),
+  done('veriff.decisions.resubmission_requested', 'decisions', 'A resubmission decision carries code 9103 and re-opens the session for capture', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'resubmission_requested', { reason: 'Face not clearly visible', reasonCode: 202 });
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      // Re-opened: a second capture + submit is accepted, which is what "additional attempt needed"
+      // has to mean for the state machine to be usable.
+      const reupload = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG } } });
+      const resubmit = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      return b(d).verification.code === 9103 && b(d).verification.reasonCode === 202 && reupload.status === 200 && ok(resubmit);
+    })),
+  done('veriff.decisions.expired_and_abandoned_codes', 'decisions', 'expired carries 9104 and abandoned carries 9121 — the two codes the decision endpoint\'s own examples pair with those statuses', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await open(h); await decide(h, a.id, 'expired');
+      const c = await open(h); await decide(h, c.id, 'abandoned');
+      const da = await h({ m: 'GET', p: `/v1/sessions/${a.id}/decision` });
+      const dc = await h({ m: 'GET', p: `/v1/sessions/${c.id}/decision` });
+      // Distinct codes, not a shared one — the pairing an earlier revision of this pack got backwards.
+      return b(da).verification.code === 9104 && b(da).verification.status === 'expired'
+        && b(dc).verification.code === 9121 && b(dc).verification.status === 'abandoned';
+    })),
+  done('veriff.decisions.review_has_no_invented_code', 'decisions', 'A session held for manual review reports status "review" with code NULL — Veriff publishes no code for it, and the twin refuses to borrow one', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // `review` is a real, opt-in status (the decision-webhook page lists it) but it appears in
+      // NEITHER the decision schema's `status` enum NOR its `code` enum — [9001,9102,9103,9104,9121]
+      // are all spoken for. Emitting 9121 here would tell a consumer branching on `code` that a
+      // manual-review case was abandoned.
+      const { id } = await open(h);
+      await decide(h, id, 'review');
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const v = b(d).verification;
+      const taken = [9001, 9102, 9103, 9104, 9121];
+      return v.status === 'review' && v.code === null && taken.every((c) => c !== v.code)
+        && typeof v.decisionTime === 'string' && typeof v.attemptId === 'string';
+    })),
+  done('veriff.decisions.extracted_person_and_document', 'decisions', 'A decision carries the extracted `person` and `document` objects, distinct from the hints supplied at creation', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // The caller SEEDS a hint at creation; the decision must report the EXTRACTED values, not
+      // echo the hint back — a twin that conflated the two would let a caller "verify" its own input.
+      const { id } = await open(h, { person: { firstName: 'hint', lastName: 'hint' }, document: { type: 'PASSPORT', country: 'EE' } });
+      const beforeDecision = await h({ m: 'GET', p: `/v1/sessions/${id}/person` });
+      await decide(h, id, 'approved', {
+        person: { firstName: 'SARAH', lastName: 'MORGAN', dateOfBirth: '1967-03-30', nationality: 'GB', idNumber: null },
+        document: { number: 'X1234567', type: 'PASSPORT', country: 'GB' },
+      });
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const v = b(d).verification;
+      return b(beforeDecision).person === null
+        && v.person.firstName === 'SARAH' && v.person.dateOfBirth === '1967-03-30'
+        && v.document.number === 'X1234567' && v.document.country === 'GB';
+    })),
+  done('veriff.decisions.risk_labels', 'decisions', 'A decision carries riskLabels[{label,category,sessionIds}] — the crosslink signal a fraud check reads', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'approved', { riskLabels: [{ label: 'person_previously_approved', category: 'crosslinks', sessionIds: ['s1', 's2'] }] });
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const labels = b(d).verification.riskLabels;
+      return Array.isArray(labels) && labels[0].label === 'person_previously_approved' && labels[0].category === 'crosslinks' && labels[0].sessionIds.length === 2;
+    })),
+  done('veriff.decisions.transition_guard', 'decisions', 'A session cannot jump straight from created to a decision — 400 `Cannot transition to "…" status.` (1304)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const early = await h({ m: 'POST', p: `/v1/_twin/sessions/${id}/decision`, b: { status: 'approved' } });
+      const stillPending = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      return failed(early, 400, '1304') && b(stillPending).verification === null;
+    })),
+  done('veriff.decisions.no_second_decision', 'decisions', 'A decided session is terminal — a second decision is refused and the first one stands', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'approved');
+      const again = await h({ m: 'POST', p: `/v1/_twin/sessions/${id}/decision`, b: { status: 'declined' } });
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      return failed(again, 400, '1304') && b(d).verification.status === 'approved' && b(d).verification.code === 9001;
+    })),
+
+  // ── Attempts ──────────────────────────────────────────────────────────────
+  done('veriff.attempts.list', 'attempts', 'GET /v1/sessions/{id}/attempts — the `verifications[]` array with id/status/userDefinedData/createdTime', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const decided = await decide(h, id, 'resubmission_requested');
+      const a = await h({ m: 'GET', p: `/v1/sessions/${id}/attempts` });
+      const rows = b(a).verifications;
+      return ok(a) && Array.isArray(rows) && rows.length === 1
+        && rows[0].id === b(decided).verification.attemptId
+        && rows[0].status === 'resubmission_requested'
+        && Array.isArray(rows[0].userDefinedData) && typeof rows[0].createdTime === 'string';
+    })),
+  done('veriff.attempts.reverse_chronological', 'attempts', 'Attempts come back most-recent-first across a resubmission cycle', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'resubmission_requested');
+      await decide(h, id, 'approved'); // second attempt, after the session re-opened
+      const a = await h({ m: 'GET', p: `/v1/sessions/${id}/attempts` });
+      const rows = b(a).verifications;
+      return rows.length === 2 && rows[0].status === 'approved' && rows[1].status === 'resubmission_requested'
+        && String(rows[0].createdTime) > String(rows[1].createdTime);
+    })),
+  done('veriff.attempts.empty_before_decision', 'attempts', 'A session with no attempt yet returns an empty verifications array, not a 404', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const a = await h({ m: 'GET', p: `/v1/sessions/${id}/attempts` });
+      const missing = await h({ m: 'GET', p: '/v1/sessions/00000000-0000-4000-8000-000000000000/attempts' });
+      return ok(a) && Array.isArray(b(a).verifications) && b(a).verifications.length === 0 && failed(missing, 404, '1101');
+    })),
+
+  // ── Person ────────────────────────────────────────────────────────────────
+  done('veriff.person.get', 'person', 'GET /v1/sessions/{id}/person — serves the session\'s extracted person once one exists, 404 for an unknown session', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const before = await h({ m: 'GET', p: `/v1/sessions/${id}/person` });
+      await decide(h, id, 'approved', { person: { firstName: 'ANA', lastName: 'LOPEZ', nationality: 'ES' } });
+      const after = await h({ m: 'GET', p: `/v1/sessions/${id}/person` });
+      const missing = await h({ m: 'GET', p: '/v1/sessions/00000000-0000-4000-8000-000000000000/person' });
+      return b(before).person === null && b(after).person.firstName === 'ANA' && b(after).person.nationality === 'ES' && failed(missing, 404, '1101');
+    })),
+
+  // ── Media ─────────────────────────────────────────────────────────────────
+  done('veriff.media.upload', 'media', 'POST /v1/sessions/{id}/media — 200 with the documented image object (id/name/context/size/mimetype/url/sessionId)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const u = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'document-front', content: IMG } } });
+      const img = b(u).image;
+      return u.status === 200 && env(u) === 'success'
+        && typeof img.id === 'string' && img.context === 'document-front'
+        && img.sessionId === id && img.mimetype === 'image/jpeg'
+        && img.url === `https://stationapi.veriff.com/v1/media/${img.id}`;
+    })),
+  done('veriff.media.name_mirrors_context', 'media', 'The uploaded object\'s `name` mirrors its `context`, as every published example shows', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const u = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'document-back', content: IMG } } });
+      return b(u).image.name === 'document-back' && b(u).image.context === 'document-back';
+    })),
+  done('veriff.media.timestamp_always_null', 'media', 'The response `timestamp` is deprecated and always null — even when the caller supplies one', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const u = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG, timestamp: '2025-01-01T10:00:00Z' } } });
+      return u.status === 200 && 'timestamp' in b(u).image && b(u).image.timestamp === null;
+    })),
+  done('veriff.media.size_is_decoded_bytes', 'media', '`size` is the DECODED byte count, not the base64 length or the data-URI length', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const u = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG } } });
+      return b(u).image.size === 11; // "hello-world"
+    })),
+  done('veriff.media.upload_rejects_unknown_context', 'media', 'An unlisted media context → 400 (1402, "context not supported")', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const bad = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'selfie-please', content: IMG } } });
+      const list = await h({ m: 'GET', p: `/v1/sessions/${id}/media` });
+      return failed(bad, 400, '1402') && b(bad).message === 'Image context is not supported.' && b(list).images.length === 0;
+    })),
+  done('veriff.media.upload_rejects_bad_base64', 'media', 'Content that is not valid base64 → 400 (1401)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const bad = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: 'data:image/jpeg;base64,!!!not base64!!!' } } });
+      const empty = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: '' } } });
+      return failed(bad, 400, '1401') && b(bad).message === 'Image is not in valid `base64`.' && failed(empty, 400, '1401');
+    })),
+  done('veriff.media.upload_after_submit_409', 'media', 'Uploading after the session is submitted → 409 conflict, exactly as the endpoint documents', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      const late = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG } } });
+      const list = await h({ m: 'GET', p: `/v1/sessions/${id}/media` });
+      return failed(late, 409, '1101') && b(list).images.length === 0;
+    })),
+  done('veriff.media.list_by_session', 'media', 'GET /v1/sessions/{id}/media — the images/videos/nfcDocuments split, scoped to that session', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await open(h); const c = await open(h);
+      await h({ m: 'POST', p: `/v1/sessions/${a.id}/media`, b: { image: { context: 'document-front', content: IMG } } });
+      await h({ m: 'POST', p: `/v1/sessions/${c.id}/media`, b: { image: { context: 'face', content: IMG } } });
+      const la = await h({ m: 'GET', p: `/v1/sessions/${a.id}/media` });
+      const lc = await h({ m: 'GET', p: `/v1/sessions/${c.id}/media` });
+      return ok(la) && Array.isArray(b(la).videos) && Array.isArray(b(la).nfcDocuments)
+        && b(la).images.length === 1 && b(la).images[0].context === 'document-front' && b(la).images[0].sessionId === a.id
+        // …and scoped: the OTHER session's upload is not in this list, and is in its own.
+        && b(lc).images.length === 1 && b(lc).images[0].context === 'face' && b(lc).images[0].sessionId === c.id;
+    })),
+  done('veriff.media.list_by_attempt', 'media', 'GET /v1/attempts/{id}/media — per-attempt metadata, 404 for an unknown attempt', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG } } });
+      const decided = await decide(h, id, 'approved');
+      const attemptId = b(decided).verification.attemptId;
+      const m = await h({ m: 'GET', p: `/v1/attempts/${attemptId}/media` });
+      const missing = await h({ m: 'GET', p: '/v1/attempts/00000000-0000-4000-8000-000000000000/media' });
+      return ok(m) && Array.isArray(b(m).images) && failed(missing, 404, '1101');
+    })),
+  done('veriff.media.download_bytes', 'media', 'GET /v1/media/{id} returns the media BYTES under its own mimetype (not JSON), 404 for an unknown id', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const u = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG } } });
+      const g = await h({ m: 'GET', p: `/v1/media/${b(u).image.id}` });
+      const missing = await h({ m: 'GET', p: '/v1/media/00000000-0000-4000-8000-000000000000' });
+      return ok(g) && b(g).mimetype === 'image/jpeg'
+        && Buffer.from(String(b(g).content), 'base64').toString('utf8') === 'hello-world'
+        && failed(missing, 404, '1101');
+    })),
+
+  // ── Auth: X-AUTH-CLIENT + the HMAC scheme (REAL crypto, not faked) ────────
+  done('veriff.auth.requires_auth_client', 'auth', 'A request without X-AUTH-CLIENT → 401 with the vendor\'s verbatim "Mandatory X-AUTH-CLIENT header…" message', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/sessions', b: { verification: {} }, noAuth: true });
+      return failed(r, 401, '1101') && b(r).message === 'Mandatory X-AUTH-CLIENT header containing the API key is missing from the request.';
+    })),
+  done('veriff.auth.hmac_matches_published_vector', 'auth', 'The signing implementation reproduces Veriff\'s OWN published mock vector byte-for-byte', 'api', 'core', () => {
+    // devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security, "Mock data to test
+    // signature generation locally". This is the strongest possible check on the primitive: it is
+    // the vendor's number, not ours, and a wrong encoding (base64, uppercase hex, the `sha256=`
+    // prefix the vendor's own Python sample wrongly emits) fails it instantly.
+    const secret = 'abcdef12-abcd-abcd-abcd-abcdef012345';
+    const payload = '{"verification":{"callback":"https://veriff.com","person":{"firstName":"John","lastName":"Smith"},"document":{"type":"PASSPORT","country":"EE"},"vendorData":"unique id of the end-user","timestamp":"2016-05-19T08:30:25.597Z"}}';
+    const sig = veriffSignature(payload, secret);
+    return sig === '0dcab73ddd20062616d104231c7439657546a5c24e4691977da93bb854c31e25'
+      && verifyVeriffSignature(payload, sig, secret) === null
+      && verifyVeriffSignature(payload, sig.toUpperCase(), secret) === 'mismatch'
+      && verifyVeriffSignature(`${payload} `, sig, secret) === 'mismatch'
+      && verifyVeriffSignature(payload, undefined, secret) === 'missing';
+  }),
+  done('veriff.auth.hmac_required_on_reads', 'auth', 'A read with a missing or wrong X-HMAC-SIGNATURE → 401 "Invalid HMAC signature" (1812)', 'api', 'core', () =>
+    withRoot(async (h, root) => {
+      const { id } = await open(h);
+      const wrong = await h({ m: 'GET', p: `/v1/sessions/${id}/decision`, sig: veriffSignature('some-other-session', TWIN_SHARED_SECRET) });
+      // Rooted even though it 401s before touching state: no verify in this file may be capable of
+      // writing outside its temp root, however it happens to short-circuit today.
+      const absent = await handleVeriffTwinRequest({ method: 'GET', path: `/v1/sessions/${id}/decision`, headers: { [AUTH_CLIENT_HEADER]: TWIN_API_KEY }, root, occurredAt: at() });
+      const good = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      return failed(wrong, 401, '1812') && b(wrong).message === 'Invalid HMAC signature'
+        && failed(absent, 401, '1812') && ok(good);
+    })),
+  done('veriff.auth.create_session_is_signature_exempt', 'auth', 'POST /v1/sessions is the ONE endpoint that needs no signature — and every other one still does', 'api', 'core', () =>
+    withRoot(async (h, root) => {
+      // These three go around `h` because they must send NO signature header at all, which `h`
+      // always supplies. `root` and `occurredAt` are threaded BY HAND for exactly that reason: an
+      // omitted root does not error, it silently writes into the operator's real ~/.volter state
+      // dir — which is gitignored, so nothing catches it while it poisons later runs. A §9 review
+      // caught this here after measuring a `.volter/world/veriff/actions.jsonl` growing by one row
+      // per test run.
+      const bare = (method: string, path: string, body?: unknown) => handleVeriffTwinRequest({
+        method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        headers: { [AUTH_CLIENT_HEADER]: TWIN_API_KEY }, root, occurredAt: at(),
+      });
+      const created = await bare('POST', '/v1/sessions', { verification: { vendorData: 'exempt' } });
+      const id = String((created.body as Body).verification?.id ?? '');
+      const unsignedRead = await bare('GET', `/v1/sessions/${id}/decision`);
+      // …and the same read WITH a correct signature works, so this is about the signature and not
+      // about the session being unreachable. That cross-check is ALSO what pins the root-threading
+      // above: `h` reads from the temp root, so if `bare()` stopped passing `root` the session would
+      // land in the ambient dir and this line would 404 — the capability reddens BY NAME rather than
+      // leaking silently. (Verified by reverting it: the baseline reports exactly this id.)
+      const signedRead = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      return created.status === 201 && (created.body as Body).verification.vendorData === 'exempt'
+        && failed(unsignedRead, 401, '1812') && ok(signedRead) && b(signedRead).verification === null;
+    })),
+  done('veriff.auth.hmac_signs_body_on_writes', 'auth', 'POST/PATCH sign the REQUEST BODY — a signature over the session id is refused on a write', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const body = { verification: { status: 'submitted' } };
+      const wrongPayload = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: body, sig: veriffSignature(id, TWIN_SHARED_SECRET) });
+      const rightPayload = await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: body, sig: veriffSignature(JSON.stringify(body), TWIN_SHARED_SECRET) });
+      return failed(wrongPayload, 401, '1812') && ok(rightPayload) && b(rightPayload).verification.status === 'submitted';
+    })),
+  done('veriff.auth.hmac_signs_path_resource_id', 'auth', 'GET signs the resource id IN THE PATH — the attempt id for /attempts/{id}/media, the media id for /media/{id}', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const u = await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'face', content: IMG } } });
+      const mediaId = String(b(u).image.id);
+      const decided = await decide(h, id, 'approved');
+      const attemptId = String(b(decided).verification.attemptId);
+      // Signing the SESSION id (the naive reading of "sign the session ID") must be refused here.
+      const wrongMedia = await h({ m: 'GET', p: `/v1/media/${mediaId}`, sig: veriffSignature(id, TWIN_SHARED_SECRET) });
+      const rightMedia = await h({ m: 'GET', p: `/v1/media/${mediaId}` });
+      const wrongAttempt = await h({ m: 'GET', p: `/v1/attempts/${attemptId}/media`, sig: veriffSignature(id, TWIN_SHARED_SECRET) });
+      const rightAttempt = await h({ m: 'GET', p: `/v1/attempts/${attemptId}/media` });
+      return failed(wrongMedia, 401, '1812') && ok(rightMedia) && failed(wrongAttempt, 401, '1812') && ok(rightAttempt);
+    })),
+  done('veriff.auth.response_signing_headers', 'auth', 'Responses carry X-AUTH-CLIENT and an X-HMAC-SIGNATURE over the response BODY, as every endpoint documents', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'veriff-cap-srv-'));
+    const server = await createVeriffTwinServer({ root, port: 0, hostname: '127.0.0.1' }); // loopback-specific: port 0 can't land on a stranger's 127.0.0.1 listener
+    try {
+      const res = await fetch(`http://127.0.0.1:${server.port}/v1/sessions`, {
+        method: 'POST',
+        headers: { [AUTH_CLIENT_HEADER]: TWIN_API_KEY, 'content-type': 'application/json' },
+        body: JSON.stringify({ verification: { vendorData: 'signed-response' } }),
+      });
+      const text = await res.text();
+      const parsed = JSON.parse(text) as Body;
+      // Data-coupled: the signature must cover the REAL body the handler produced, and that body
+      // must carry the seeded value — a dead handler's `{}` fails the second half.
+      return res.status === 201
+        && parsed.verification?.vendorData === 'signed-response'
+        && res.headers.get(AUTH_CLIENT_HEADER) === TWIN_API_KEY
+        && res.headers.get(HMAC_SIGNATURE_HEADER) === veriffSignature(text, TWIN_SHARED_SECRET)
+        && veriffResponseHeaders(text, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET })[HMAC_SIGNATURE_HEADER] === res.headers.get(HMAC_SIGNATURE_HEADER);
+    } finally {
+      server.stop();
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  // ── Webhooks ──────────────────────────────────────────────────────────────
+  done('veriff.webhooks.decision_delivery', 'webhooks', 'A decision pushes a signed decision webhook to the session callback, carrying the same document the decision endpoint serves', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h, { callback: 'https://consumer.test/api/veriff/webhook', vendorData: 'partner_7' });
+      await decide(h, id, 'approved');
+      const d = await h({ m: 'GET', p: `/v1/_twin/deliveries?sessionId=${id}` });
+      const decision = (b(d).deliveries as Body[]).find((x) => x.kind === 'decision');
+      if (!decision) return false;
+      const payload = JSON.parse(String(decision.body)) as Body;
+      const endpoint = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      return decision.url === 'https://consumer.test/api/veriff/webhook'
+        && payload.verification.id === id && payload.verification.status === 'approved'
+        && payload.verification.code === 9001 && payload.verification.vendorData === 'partner_7'
+        && JSON.stringify(payload.verification) === JSON.stringify(b(endpoint).verification);
+    })),
+  done('veriff.webhooks.decision_signature_verifies', 'webhooks', 'A real consumer\'s verification of the delivery passes — x-auth-client matched and the HMAC taken over the RAW body', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h, { callback: 'https://consumer.test/hook' });
+      await decide(h, id, 'declined', { reason: 'Known fraud', reasonCode: 106 });
+      const d = await h({ m: 'GET', p: `/v1/_twin/deliveries?sessionId=${id}` });
+      // Two deliveries went out — the 7002 submitted EVENT and then the DECISION. Pick the decision
+      // explicitly rather than trusting an index; conflating them is how this verify first went red.
+      const delivery = (b(d).deliveries as Body[]).find((x) => x.kind === 'decision');
+      if (!delivery) return false;
+      const headers = delivery.headers as Record<string, string>;
+      const parsed = verifyWebhook(String(delivery.body), headers, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET }) as Body;
+      return (b(d).deliveries as Body[]).length === 2
+        && parsed.verification.status === 'declined' && parsed.verification.reasonCode === 106
+        && headers[AUTH_CLIENT_HEADER] === TWIN_API_KEY
+        && headers[HMAC_SIGNATURE_HEADER] === veriffSignature(String(delivery.body), TWIN_SHARED_SECRET);
+    })),
+  done('veriff.webhooks.rejects_tampering', 'webhooks', 'Verification refuses a tampered body, a wrong x-auth-client, and a missing signature — each by its own reason', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h, { callback: 'https://consumer.test/hook' });
+      await decide(h, id, 'approved');
+      const d = await h({ m: 'GET', p: `/v1/_twin/deliveries?sessionId=${id}` });
+      const delivery = (b(d).deliveries as Body[]).find((x) => x.kind === 'decision');
+      if (!delivery) return false;
+      const headers = delivery.headers as Record<string, string>;
+      const raw = String(delivery.body);
+      const reason = (fn: () => unknown): string => {
+        try { fn(); return 'NO-THROW'; } catch (e) { return e instanceof VeriffWebhookVerificationError ? e.reason : 'WRONG-ERROR'; }
+      };
+      const tampered = raw.replace('"approved"', '"declined"');
+      return tampered !== raw
+        && reason(() => verifyWebhook(tampered, headers, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET })) === 'bad-signature'
+        && reason(() => verifyWebhook(raw, { ...headers, [AUTH_CLIENT_HEADER]: 'someone-else' }, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET })) === 'bad-auth-client'
+        && reason(() => verifyWebhook(raw, { [AUTH_CLIENT_HEADER]: TWIN_API_KEY }, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET })) === 'missing-signature'
+        && reason(() => verifyWebhook(raw, {}, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET })) === 'missing-auth-client'
+        && reason(() => verifyWebhook(raw, headers, { apiKey: TWIN_API_KEY, sharedSecret: 'a-different-secret' })) === 'bad-signature';
+    })),
+  done('veriff.webhooks.event_submitted_7002', 'webhooks', 'Submitting a session pushes the 7002 `submitted` EVENT webhook — no `verification` key, which is how a consumer tells the families apart', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h, { callback: 'https://consumer.test/hook', vendorData: 'partner_3' });
+      await h({ m: 'PATCH', p: `/v1/sessions/${id}`, b: { verification: { status: 'submitted' } } });
+      const d = await h({ m: 'GET', p: `/v1/_twin/deliveries?sessionId=${id}` });
+      const rows = b(d).deliveries as Body[];
+      if (rows.length !== 1) return false;
+      const payload = JSON.parse(String(rows[0]!.body)) as Body;
+      return rows[0]!.kind === 'event' && payload.action === 'submitted' && payload.code === 7002
+        && payload.id === id && payload.vendorData === 'partner_3' && !('verification' in payload);
+    })),
+  done('veriff.webhooks.event_started_7001', 'webhooks', 'The end-user entering the flow pushes the 7001 `started` EVENT webhook and moves the session to `started`', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h, { callback: 'https://consumer.test/hook' });
+      const started = await h({ m: 'POST', p: `/v1/_twin/sessions/${id}/event`, b: { action: 'started' } });
+      const d = await h({ m: 'GET', p: `/v1/_twin/deliveries?sessionId=${id}` });
+      const payload = JSON.parse(String((b(d).deliveries as Body[])[0]!.body)) as Body;
+      return ok(started) && b(started).verification.status === 'started' && payload.action === 'started' && payload.code === 7001;
+    })),
+  done('veriff.webhooks.no_callback_no_delivery', 'webhooks', 'A session created without a callback produces no delivery at all — the twin never invents a destination', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await decide(h, id, 'approved');
+      const d = await h({ m: 'GET', p: '/v1/_twin/deliveries' });
+      const decision = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      // The decision still happened — this asserts the delivery is absent, not that nothing ran.
+      return b(decision).verification.status === 'approved' && (b(d).deliveries as Body[]).length === 0;
+    })),
+  done('veriff.webhooks.signed_delivery_is_pure', 'webhooks', 'buildSignedDelivery signs the exact bytes it emits — a re-serialized copy must not be assumed equal', 'api', 'niche', () => {
+    const payload = { status: 'success' as const, verification: { id: 'abc', status: 'approved', code: 9001 } };
+    const { body, headers } = buildSignedDelivery(payload, { apiKey: TWIN_API_KEY, sharedSecret: TWIN_SHARED_SECRET });
+    return headers[HMAC_SIGNATURE_HEADER] === veriffSignature(body, TWIN_SHARED_SECRET)
+      && headers[AUTH_CLIENT_HEADER] === TWIN_API_KEY
+      && headers['content-type'] === 'application/json'
+      && JSON.parse(body).verification.code === 9001;
+  }),
+
+  // ── Errors + platform ─────────────────────────────────────────────────────
+  done('veriff.errors.envelope_shape', 'errors', 'Every failure is `{status:"fail", code, message}` with code a STRING (the schema\'s declared type), never a number', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const notFound = await h({ m: 'GET', p: '/v1/sessions/00000000-0000-4000-8000-000000000000' });
+      const validation = await h({ m: 'POST', p: '/v1/sessions', b: {} });
+      const unauthorized = await h({ m: 'POST', p: '/v1/sessions', b: { verification: {} }, noAuth: true });
+      for (const r of [notFound, validation, unauthorized]) {
+        const body = b(r);
+        if (body.status !== 'fail' || typeof body.code !== 'string' || typeof body.message !== 'string') return false;
+        if (Object.keys(body).sort().join(',') !== 'code,message,status') return false;
+      }
+      return notFound.status === 404 && validation.status === 400 && unauthorized.status === 401;
+    })),
+  done('veriff.errors.unmodeled_route_404', 'errors', 'An endpoint this twin does not model fails like the vendor (404 "Resource not found") — never a fake success', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      const watchlist = await h({ m: 'GET', p: `/v1/sessions/${id}/watchlist-screening` });
+      const faces = await h({ m: 'POST', p: '/v1/faces/import', b: { images: [] } });
+      const invented = await h({ m: 'POST', p: `/v1/sessions/${id}/NOPE`, b: {} });
+      return failed(watchlist, 404, '1101') && failed(faces, 404, '1101') && failed(invented, 404, '1101');
+    })),
+  done('veriff.platform.read_only_405', 'platform', 'A read-only twin serves reads and refuses every write with 405', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'veriff-cap-ro-'));
+    try {
+      const call = (method: string, path: string, body?: unknown, readOnly = false) => {
+        const raw = body === undefined ? '' : JSON.stringify(body);
+        return handleVeriffTwinRequest({ method, path, ...(body === undefined ? {} : { body: raw }), headers: { [AUTH_CLIENT_HEADER]: TWIN_API_KEY, [HMAC_SIGNATURE_HEADER]: signFor(method, path, raw) }, root, readOnly, occurredAt: at() });
+      };
+      const created = await call('POST', '/v1/sessions', { verification: { vendorData: 'ro' } });
+      const id = String((created.body as Body).verification.id);
+      const blockedCreate = await call('POST', '/v1/sessions', { verification: {} }, true);
+      const blockedPatch = await call('PATCH', `/v1/sessions/${id}`, { verification: { status: 'submitted' } }, true);
+      const blockedDelete = await call('DELETE', `/v1/sessions/${id}`, undefined, true);
+      const stillReadable = await call('GET', `/v1/_twin/sessions/${id}`, undefined, true);
+      return blockedCreate.status === 405 && blockedPatch.status === 405 && blockedDelete.status === 405
+        && stillReadable.status === 200 && (stillReadable.body as Body).verification.status === 'created';
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('veriff.platform.session_ids_survive_delete_and_recreate', 'platform', 'DIRTY STATE: ids minted after deletes never collide with, or resurrect, an earlier session', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // A deliberate dirty-state verify: build history up, delete out of the middle of it, then
+      // keep minting. A count- or index-derived id would re-issue a retired id here and a later
+      // read would silently return the WRONG session.
+      const seen: string[] = [];
+      for (let i = 0; i < 4; i += 1) {
+        const { id } = await open(h, { vendorData: `round-${i}` });
+        seen.push(id);
+      }
+      await h({ m: 'DELETE', p: `/v1/sessions/${seen[1]}` });
+      await h({ m: 'DELETE', p: `/v1/sessions/${seen[2]}` });
+      const fresh: string[] = [];
+      for (let i = 0; i < 3; i += 1) {
+        const { id } = await open(h, { vendorData: `after-${i}` });
+        fresh.push(id);
+      }
+      if (new Set([...seen, ...fresh]).size !== 7) return false;             // no id ever reused
+      const revived = await h({ m: 'GET', p: `/v1/_twin/sessions/${seen[1]}` });   // deleted stays deleted
+      const survivor = await h({ m: 'GET', p: `/v1/_twin/sessions/${seen[3]}` });  // neighbours untouched
+      const newest = await h({ m: 'GET', p: `/v1/_twin/sessions/${fresh[2]}` });
+      return failed(revived, 404, '1101')
+        && b(survivor).verification.vendorData === 'round-3'
+        && b(newest).verification.vendorData === 'after-2';
+    })),
+  done('veriff.platform.decision_survives_media_churn', 'platform', 'DIRTY STATE: a decision reached after a resubmission cycle reports the LATEST attempt, not the first', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const { id } = await open(h);
+      await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'document-front', content: IMG } } });
+      const first = await decide(h, id, 'resubmission_requested', { reason: 'Poor image quality', reasonCode: 204 });
+      const firstAttempt = String(b(first).verification.attemptId);
+      await h({ m: 'POST', p: `/v1/sessions/${id}/media`, b: { image: { context: 'document-front', content: 'data:image/png;base64,c2Vjb25kLXNob3Q=' } } });
+      const second = await decide(h, id, 'approved');
+      const secondAttempt = String(b(second).verification.attemptId);
+      const d = await h({ m: 'GET', p: `/v1/sessions/${id}/decision` });
+      const attempts = await h({ m: 'GET', p: `/v1/sessions/${id}/attempts` });
+      const media = await h({ m: 'GET', p: `/v1/sessions/${id}/media` });
+      return firstAttempt !== secondAttempt
+        && b(d).verification.attemptId === secondAttempt
+        && b(d).verification.status === 'approved' && b(d).verification.reason === null
+        && (b(attempts).verifications as Body[]).length === 2
+        && (b(media).images as Body[]).length === 2;
+    })),
+
+  // ── Connector (pull / push over an INJECTED client, offline) ──────────────
+  done('veriff.connector.pull_decisions', 'connector', 'Pull decisions for known session ids over an injected client and fold them into the projection', 'connector', 'core', () =>
+    withRoot(async (h, root) => {
+      const execute = fakeExecute();
+      const pulled = await pullVeriffDecisions(execute, [REMOTE_SESSION], root, PULL_AT);
+      const g = await h({ m: 'GET', p: `/v1/sessions/${REMOTE_SESSION}/decision` });
+      const v = b(g).verification;
+      return pulled === 1 && ok(g) && v.id === REMOTE_SESSION && v.status === 'approved' && v.code === 9001
+        && v.person.firstName === 'REMOTE' && v.document.country === 'EE' && v.vendorData === 'remote-partner';
+    })),
+  done('veriff.connector.pull_is_idempotent', 'connector', 'A re-pull of identical state appends NOTHING (shadow-diff dedup): deltasAppended drops to 0', 'connector', 'core', () =>
+    withRoot(async (h, root) => {
+      const execute = fakeExecute();
+      const first = await syncVeriffFromReal(execute, { sessionIds: [REMOTE_SESSION], root, occurredAt: PULL_AT });
+      const second = await syncVeriffFromReal(execute, { sessionIds: [REMOTE_SESSION], root, occurredAt: PULL_AT });
+      const g = await h({ m: 'GET', p: `/v1/sessions/${REMOTE_SESSION}/decision` });
+      return first.observed === 3 && first.deltasAppended > 0 && second.deltasAppended === 0
+        && b(g).verification.status === 'approved';
+    })),
+  done('veriff.connector.pull_attempts_and_media', 'connector', 'Pull folds the attempt history and media metadata, readable back over the twin\'s own endpoints', 'connector', 'common', () =>
+    withRoot(async (h, root) => {
+      const execute = fakeExecute();
+      // The attempt/media endpoints are SESSION-scoped (an unknown session is a 404 before any
+      // sub-resource is considered), so the session has to be observed before its children.
+      await pullVeriffDecisions(execute, [REMOTE_SESSION], root, PULL_AT);
+      const attempts = await pullVeriffAttempts(execute, [REMOTE_SESSION], root, PULL_AT);
+      const media = await pullVeriffMedia(execute, [REMOTE_SESSION], root, PULL_AT);
+      const a = await h({ m: 'GET', p: `/v1/sessions/${REMOTE_SESSION}/attempts` });
+      const m = await h({ m: 'GET', p: `/v1/sessions/${REMOTE_SESSION}/media` });
+      return attempts === 1 && media === 1
+        && (b(a).verifications as Body[])[0]!.status === 'approved'
+        && (b(m).images as Body[])[0]!.context === 'document-front'
+        && (b(m).images as Body[])[0]!.sessionId === REMOTE_SESSION;
+    })),
+  done('veriff.connector.pull_then_local_create_never_collides', 'connector', 'A local create after a pull (and a pull after a local create) never lands on the other\'s id', 'connector', 'common', () =>
+    withRoot(async (h, root) => {
+      // Direction 1: pull first, then mint locally.
+      await syncVeriffFromReal(fakeExecute(), { sessionIds: [REMOTE_SESSION], root, occurredAt: PULL_AT });
+      const local = await open(h, { vendorData: 'local-after-pull' });
+      // Direction 2: mint locally, then pull a DIFFERENT remote id on top.
+      const local2 = await open(h, { vendorData: 'local-before-pull' });
+      await syncVeriffFromReal(fakeExecute(OTHER_REMOTE), { sessionIds: [OTHER_REMOTE], root, occurredAt: PULL_AT });
+      const pulled = await h({ m: 'GET', p: `/v1/sessions/${REMOTE_SESSION}/decision` });
+      const mine = await h({ m: 'GET', p: `/v1/_twin/sessions/${local.id}` });
+      const mine2 = await h({ m: 'GET', p: `/v1/_twin/sessions/${local2.id}` });
+      return local.id !== REMOTE_SESSION && local2.id !== OTHER_REMOTE
+        && b(pulled).verification.vendorData === 'remote-partner'
+        && b(mine).verification.vendorData === 'local-after-pull'
+        && b(mine2).verification.vendorData === 'local-before-pull';
+    })),
+  done('veriff.connector.push_create_session', 'connector', 'Push turns a pending local session into a real POST /sessions and confirms it only on `status:"success"`', 'connector', 'core', () =>
+    withRoot(async (h, root) => {
+      await open(h, { vendorData: 'to-push', callback: 'https://consumer.test/hook' });
+      const calls: { method: string; path: string; body?: Record<string, unknown> }[] = [];
+      const succeeding: VeriffExecute = async (method, path, body) => { calls.push({ method, path, ...(body ? { body } : {}) }); return { status: 'success', verification: { id: 'remote-new' } }; };
+      const pushed = await pushPendingVeriffActions(succeeding, root, PULL_AT);
+      const again = await pushPendingVeriffActions(succeeding, root, PULL_AT); // already confirmed
+      return pushed === 1 && again === 0
+        && calls[0]!.method === 'POST' && calls[0]!.path === '/sessions'
+        && (calls[0]!.body as any).verification.vendorData === 'to-push'
+        && (calls[0]!.body as any).verification.callback === 'https://consumer.test/hook';
+    })),
+  done('veriff.connector.push_does_not_confirm_on_failure', 'connector', 'A `status:"fail"` response leaves the local action PENDING — a failed push must never look confirmed', 'connector', 'core', () =>
+    withRoot(async (h, root) => {
+      await open(h, { vendorData: 'will-fail' });
+      let attempts = 0;
+      const failing: VeriffExecute = async () => { attempts += 1; return { status: 'fail', code: '1101', message: 'Validation failed' }; };
+      const pushed = await pushPendingVeriffActions(failing, root, PULL_AT);
+      const retried = await pushPendingVeriffActions(failing, root, PULL_AT);
+      return pushed === 0 && retried === 0 && attempts === 2;
+    })),
+  done('veriff.connector.request_for_action_mapping', 'connector', 'Pure action→request mapping: create → POST, submit → PATCH, delete → DELETE, vendor-authored types → null', 'connector', 'common', () => {
+    const act = (type: string, id: string, fields: Record<string, unknown>) => ({ id: 'a1', subject: { type, id }, fields } as any);
+    const create = veriffRequestForAction(act('session', 's1', { sessionId: 's1', status: 'created', vendorData: 'v', callback: 'https://x.test/h' }));
+    const submit = veriffRequestForAction(act('session', 's1', { sessionId: 's1', status: 'submitted' }));
+    const remove = veriffRequestForAction(act('session', 's1', { sessionId: 's1', deleted: true }));
+    return create?.method === 'POST' && create.path === '/sessions' && (create.body as any).verification.vendorData === 'v'
+      && submit?.method === 'PATCH' && submit.path === '/sessions/s1' && (submit.body as any).verification.status === 'submitted'
+      && remove?.method === 'DELETE' && remove.path === '/sessions/s1'
+      // Attempts, media and the twin's own delivery log are VENDOR-authored or twin-local: there is
+      // no endpoint to push them to, and inventing one would be a fake success.
+      && veriffRequestForAction(act('attempt', 'a', {})) === null
+      && veriffRequestForAction(act('media', 'm', {})) === null
+      && veriffRequestForAction(act('delivery', 'd', {})) === null
+      // A decision is authored by Veriff — a local one has no push target either.
+      && veriffRequestForAction(act('session', 's1', { sessionId: 's1', status: 'approved' })) === null;
+  }),
+  done('veriff.connector.signature_payload_rule', 'connector', 'The live executor signs the right half: body for POST/PATCH, the PATH resource id for GET/DELETE', 'connector', 'core', () => {
+    const body = '{"verification":{"status":"submitted"}}';
+    return signaturePayloadFor('POST', '/sessions', body) === body
+      && signaturePayloadFor('PATCH', '/sessions/s1', body) === body
+      && signaturePayloadFor('GET', '/sessions/s1/decision') === 's1'
+      && signaturePayloadFor('GET', '/attempts/a9/media') === 'a9'
+      && signaturePayloadFor('GET', '/media/m4') === 'm4'
+      && signaturePayloadFor('DELETE', '/sessions/s1') === 's1';
+  }),
+  done('veriff.connector.live_client_signs_and_exempts_create', 'connector', 'liveVeriffExecute stamps X-AUTH-CLIENT on every call, signs correctly, and omits the signature on POST /sessions alone', 'connector', 'core', async () => {
+    const seen: { url: string; headers: Record<string, string>; body?: string }[] = [];
+    const fetchImpl = (async (url: any, init: any) => {
+      seen.push({ url: String(url), headers: init.headers as Record<string, string>, body: init.body as string | undefined });
+      return new Response(JSON.stringify({ status: 'success' }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as unknown as typeof fetch;
+    const execute = liveVeriffExecute('key-1', 'secret-1', { fetchImpl, budgetOptions: throwawayLedger() });
+    await execute('POST', '/sessions', { verification: { vendorData: 'x' } });
+    await execute('GET', '/sessions/abc/decision');
+    const create = seen[0]!; const read = seen[1]!;
+    return seen.length === 2
+      && create.url === 'https://stationapi.veriff.com/v1/sessions'
+      && create.headers[AUTH_CLIENT_HEADER] === 'key-1' && create.headers[HMAC_SIGNATURE_HEADER] === undefined
+      && read.url === 'https://stationapi.veriff.com/v1/sessions/abc/decision'
+      && read.headers[HMAC_SIGNATURE_HEADER] === veriffSignature('abc', 'secret-1');
+  }),
+  done('veriff.connector.budget_refuses_past_ceiling', 'connector', 'The rate budget REFUSES past the ceiling with the injected fetch\'s call count UNCHANGED — nothing reached the vendor', 'connector', 'core', async () => {
+    // "It threw" is not proof. The COUNT is what shows the refused call never went out.
+    let calls = 0;
+    const fetchImpl = (async () => { calls += 1; return new Response(JSON.stringify({ status: 'success' }), { status: 200 }); }) as unknown as typeof fetch;
+    const budget = new VeriffBudget({ ...throwawayLedger(), now: fixedClock() });
+    const execute = liveVeriffExecute('key-2', 'secret-2', { fetchImpl, budget });
+    const allowed = VERIFF_BUDGET_CEILING / VERIFF_CALL_WEIGHTS.other; // 30 calls at weight 2
+    for (let i = 0; i < allowed; i += 1) await execute('POST', '/sessions', { verification: {} });
+    if (calls !== allowed) return false;
+    let refused: unknown;
+    try { await execute('POST', '/sessions', { verification: {} }); } catch (e) { refused = e; }
+    return refused instanceof VeriffBudgetError && calls === allowed;
+  }),
+  done('veriff.connector.budget_prices_delete_higher', 'connector', 'DELETE /sessions/{id} is priced up so one window admits 5, not 30 — the delete-loop backstop', 'connector', 'common', async () => {
+    let calls = 0;
+    const fetchImpl = (async () => { calls += 1; return new Response(JSON.stringify({ status: 'success' }), { status: 200 }); }) as unknown as typeof fetch;
+    const budget = new VeriffBudget({ ...throwawayLedger(), now: fixedClock() });
+    const execute = liveVeriffExecute('key-3', 'secret-3', { fetchImpl, budget });
+    const allowed = Math.floor(VERIFF_BUDGET_CEILING / VERIFF_CALL_WEIGHTS.deleteSession); // 5
+    for (let i = 0; i < allowed; i += 1) await execute('DELETE', `/sessions/s${i}`);
+    if (calls !== allowed || allowed !== 5) return false;
+    let refused: unknown;
+    try { await execute('DELETE', '/sessions/s-final'); } catch (e) { refused = e; }
+    return refused instanceof VeriffBudgetError && calls === allowed;
+  }),
+  done('veriff.connector.mappers_rename_reserved_keys', 'connector', 'Every mapper renames the vendor `id` away from the kernel\'s reserved META keys, so no field is silently dropped', 'connector', 'common', () => {
+    const RESERVED = ['type', 'id', 'updatedAt'];
+    const decision = mapSessionDecision({ id: 's1', status: 'approved', code: 9001, attemptId: 'a1', vendorData: 'v' });
+    const attempt = mapSessionAttempt('s1', { id: 'a1', status: 'approved', createdTime: PULL_AT });
+    const media = mapSessionMedia('s1', { id: 'm1', name: 'face', context: 'face', mimetype: 'image/jpeg' }, 'image');
+    for (const r of [decision, attempt, media]) {
+      for (const key of RESERVED) if (key in r.fields) return false;
+    }
+    return decision.id === 's1' && decision.fields.sessionId === 's1' && decision.fields.decisionCode === 9001
+      && attempt.fields.attemptId === 'a1' && attempt.fields.sessionId === 's1'
+      && media.fields.mediaId === 'm1' && media.fields.kind === 'image';
+  }),
+
+  // ── SDK surface ───────────────────────────────────────────────────────────
+  done('veriff.sdk.js_sdk_wire_contract', 'sdk', '@veriff/js-sdk\'s exact wire contract holds: its request body shape, its `x-auth-client`-only headers, and the 201 it hard-checks', 'api', 'core', () =>
+    withRoot(async () => {
+      // `@veriff/js-sdk` v2.0.0 creates sessions FROM THE BROWSER: it XHRs `POST {host}/v1/sessions`
+      // with `x-auth-client` + `x-origin: js-sdk` and NO signature, sends
+      // `{verification:{callback,person:{firstName,lastName,idNumber},vendorData,timestamp}}`, and
+      // treats the call as successful ONLY on `201 === xhr.status`. Its `host` is a constructor
+      // option, so pointing it at this twin is configuration, not modification. The SDK itself is a
+      // DOM/XMLHttpRequest package (it mounts a form), so the twin is driven here over the same
+      // bytes rather than through a browser shim — the contract asserted is the SDK's, verbatim.
+      const root = mkdtempSync(join(tmpdir(), 'veriff-cap-jssdk-'));
+      try {
+        const body = JSON.stringify({
+          verification: {
+            callback: 'https://consumer.test/return',
+            person: { firstName: 'John', lastName: 'Smith', idNumber: '123' },
+            vendorData: 'js-sdk-user',
+            timestamp: new Date(Date.UTC(2026, 7, 1)).toISOString(),
+          },
+        });
+        const res = await handleVeriffTwinRequest({
+          method: 'POST', path: '/v1/sessions', body, root, occurredAt: at(),
+          headers: { 'content-type': 'application/json', [AUTH_CLIENT_HEADER]: TWIN_API_KEY, 'x-origin': 'js-sdk' },
+        });
+        const v = (res.body as Body).verification;
+        return res.status === 201 && v.status === 'created' && v.vendorData === 'js-sdk-user'
+          && typeof v.sessionToken === 'string' && v.url === `${v.host}/v/${v.sessionToken}`;
+      } finally { rmSync(root, { recursive: true, force: true }); }
+    })),
+  todo('veriff.sdk.incontext_frame', 'sdk', '@veriff/incontext-sdk embeds the session URL in an iframe and reports STARTED/SUBMITTED/FINISHED/CANCELED via postMessage', 'ui', 'common'),
+  todo('veriff.sdk.react_native', 'sdk', '@veriff/react-native-sdk / the Cordova plugin launch the native capture flow', 'ui', 'niche'),
+
+  // ═══ TODO: the documented surface this twin has NOT reached yet ═══════════
+  // Every entry below is a REAL, documented Veriff capability (each traceable to a devdocs page or
+  // an embedded OpenAPI operation), enumerated so coverage is measured against the product rather
+  // than against what was convenient to build.
+
+  // Watchlist screening / AML — a whole documented API area, entirely unmodeled.
+  // A THIRD vendor doc contradiction, recorded rather than silently resolved: the attempts
+  // endpoint's published `status` enum is ["created","started","submitted","resubmission_requested"]
+  // — which omits `approved`/`declined` — while its OWN response examples show attempts with
+  // `"status": "approved"` and `"status": "resubmission_requested"`. This twin follows the EXAMPLES
+  // (an attempt carries the decision it produced), because an attempt whose status can never be
+  // `approved` cannot express the two-attempt resubmission history the same page illustrates.
+  todo('veriff.attempts.status_enum', 'attempts', 'Pin the attempt `status` enum against a live account: the published schema lists created|started|submitted|resubmission_requested while the endpoint\'s own examples show `approved`', 'api', 'niche'),
+
+  todo('veriff.watchlist.get', 'watchlist', 'GET /v1/sessions/{id}/watchlist-screening — matchStatus/reviewStatus/monitorStatus + the hits[] array', 'api', 'common'),
+  todo('veriff.watchlist.hits_shape', 'watchlist', 'A hit carries matchedName, countries, dateOfBirth, matchTypes, aka, associates and listingsRelatedToMatch', 'api', 'common'),
+  todo('veriff.watchlist.search_term', 'watchlist', 'searchTerm{name,year,lists,countries,exactMatch,matchThreshold,excludeDeceased} is reported back with the screening', 'api', 'niche'),
+  todo('veriff.watchlist.patch_hit_status', 'watchlist', 'PATCH /v1/sessions/{id}/watchlist-screening {hit:{id,matchStatus,riskLevel}} — adjudicate one hit', 'api', 'common'),
+  todo('veriff.watchlist.patch_acknowledge', 'watchlist', 'PATCH {hasUnacknowledgedChanges:false} — acknowledge monitoring changes', 'api', 'niche'),
+  todo('veriff.watchlist.patch_monitor_status', 'watchlist', 'PATCH {monitorStatus:"disabled"} — stop ongoing monitoring for a screened person', 'api', 'niche'),
+  todo('veriff.watchlist.in_progress_202', 'watchlist', 'A screening still running answers 202, not 200 — the documented poll-again signal', 'api', 'common'),
+  todo('veriff.watchlist.not_enabled_402', 'watchlist', 'An integration without the feature gets 402, the vendor\'s "not enabled for your integration" status', 'api', 'common'),
+  todo('veriff.watchlist.webhook', 'webhooks', 'The watchlist-screening webhook family (its own documented payload)', 'api', 'common'),
+  todo('veriff.watchlist.pep_sanction_match', 'person', 'person.pepSanctionMatch / pepSanctionMatches[] on the person + decision payloads, incl. the provider matchTypes/matchTypesDetails/score fields', 'api', 'common'),
+  // The person ENDPOINT has its own documented shape — `id`, `idCode` (not the decision payload's
+  // `idNumber`), `placeOfBirth`, `citizenships`, `pepSanctionMatches[]` — which this twin does not
+  // yet reproduce: it serves the decision's `person` object verbatim. Filed rather than glossed.
+  todo('veriff.person.own_field_set', 'person', 'GET /v1/sessions/{id}/person\'s OWN field set (id, idCode, placeOfBirth, citizenships, pepSanctionMatches) rather than the decision payload\'s person object', 'api', 'common'),
+  todo('veriff.person.available_after_submit', 'person', 'Person data becomes available once the session is SUBMITTED, not only once a decision exists (the endpoint documents the earlier availability point)', 'api', 'common'),
+
+  // Collected data / device intelligence.
+  todo('veriff.collected_data.post', 'collected_data', 'POST /v1/sessions/{id}/collected-data — providerName + network.ip + device.fingerprint', 'api', 'niche'),
+  todo('veriff.collected_data.technical_data', 'decisions', 'verification.technicalData.ip on the decision payload', 'api', 'niche'),
+
+  // Faces / registry / database verification.
+  todo('veriff.faces.bulk_import', 'faces', 'POST /v1/faces/import — bulk face-image import, 202 accepted', 'api', 'niche'),
+  // A FIFTH in-document divergence: Veriff spells this endpoint two ways in its own material —
+  // "POST v1/sessions/validate-registry" in the API reference index, "/v1/validate-registry" in
+  // the embedded OpenAPI document. Neither is modeled, so the twin 404s both today (the
+  // conformance sweep drives /v1/validate-registry as a negative control); both spellings are
+  // named here so whoever builds it knows there is a path question to settle first.
+  todo('veriff.registry.validate', 'registry', 'Registry validation on the Public API — spelled BOTH "POST /v1/validate-registry" (embedded OpenAPI) and "POST /v1/sessions/validate-registry" (reference index); settle which the live API serves', 'api', 'niche'),
+  todo('veriff.registry.validate_sync', 'registry', 'POST /v1/validate-registry on sync-api.veriff.me — the SYNCHRONOUS variant (a different host)', 'api', 'niche'),
+  todo('veriff.registry.ine_decision', 'registry', 'GET /v1/sessions/{id}/decision/ine-registry — the legacy Mexican INE registry decision', 'api', 'niche'),
+  todo('veriff.registry.curp_decision', 'registry', 'GET /v1/sessions/{id}/decision/curp-registry — the legacy CURP registry decision', 'api', 'niche'),
+  todo('veriff.registry.combined_ine_curp_decision', 'registry', 'GET /v1/sessions/{id}/decision/combined-ine-curp-registry — the legacy combined decision', 'api', 'niche'),
+  todo('veriff.database_verification.ine', 'database_verification', 'Mexico INE database verification (matchData MATCH/NO_MATCH/NO_INPUT/NO_DATA)', 'api', 'niche'),
+  todo('veriff.database_verification.ine_biometric', 'database_verification', 'Mexico INE BIOMETRIC database verification (registryValidations)', 'api', 'niche'),
+  todo('veriff.database_verification.curp', 'database_verification', 'Mexico CURP database verification + registryResponse', 'api', 'niche'),
+  todo('veriff.database_verification.cadastro_unico', 'database_verification', 'Brazil Cadastro Único database verification', 'api', 'niche'),
+  todo('veriff.database_verification.probet', 'database_verification', 'Brazil Pro Bet database verification', 'api', 'niche'),
+  todo('veriff.database_verification.cpf_biometric', 'database_verification', 'Brazil CPF biometric database check', 'api', 'niche'),
+  todo('veriff.database_verification.registraduria', 'database_verification', 'Colombia Registraduría database verification', 'api', 'niche'),
+  todo('veriff.database_verification.us_ssn', 'database_verification', 'US database verification — the validationResults[] array', 'api', 'niche'),
+  todo('veriff.database_verification.match', 'database_verification', 'Match database verification', 'api', 'niche'),
+  todo('veriff.database_verification.metadata', 'database_verification', 'Metadata database verification', 'api', 'niche'),
+
+  // IDV solutions — the verification products a session is configured with.
+  todo('veriff.idv.document_and_selfie', 'idv', 'Document + Selfie IDV — the flagship flow\'s decision payload fields', 'api', 'core'),
+  todo('veriff.idv.document_only', 'idv', 'Document-only IDV (no selfie) — its distinct decision shape', 'api', 'common'),
+  todo('veriff.idv.biometric_authentication', 'idv', 'Biometric Authentication — verification.biometricAuthentication{matchedSessionId, matchedSessionVendorData, details}', 'api', 'common'),
+  todo('veriff.idv.biometric_liveness', 'idv', 'Biometric Liveness — the standalone liveness solution\'s decision payload', 'api', 'common'),
+  todo('veriff.idv.selfie2selfie', 'idv', 'Selfie2Selfie — additionalVerifiedData.faceMatch', 'api', 'niche'),
+  todo('veriff.idv.age_estimation', 'idv', 'Age Estimation — its decision payload and thresholds', 'api', 'niche'),
+  todo('veriff.idv.unstructured_docs', 'idv', 'Unstructured Docs — the `udocs` object and its extraction fields', 'api', 'niche'),
+  todo('veriff.idv.nfc_epassport', 'idv', 'NFC / ePassport chip verification — document.nfcValidated and the document-nfc media context', 'api', 'niche'),
+  todo('veriff.idv.full_auto', 'idv', 'Full Auto / Essential Plan — its distinct decision and webhook behaviour', 'api', 'niche'),
+  todo('veriff.idv.uk_diatf', 'idv', 'UK DIATF-certified flow', 'api', 'niche'),
+  todo('veriff.idv.risk_score', 'decisions', 'verification.riskScore{score} and verification.highRisk', 'api', 'common'),
+  todo('veriff.idv.additional_verified_data', 'decisions', 'The full additionalVerifiedData object (proofOfAddress, officialDatabaseVerification, faceMatch, …)', 'api', 'common'),
+  todo('veriff.decisions.comments', 'decisions', 'verification.comments[] — reviewer commentary on a decision', 'api', 'niche'),
+  todo('veriff.decisions.submission_time', 'decisions', 'verification.submissionTime is reported on the decision payload distinctly from decisionTime/acceptanceTime', 'api', 'niche'),
+  todo('veriff.decisions.tag', 'decisions', 'verification.tag — the ≤64-character session tag, round-tripped from creation to decision', 'api', 'niche'),
+  todo('veriff.decisions.granular_decline_codes', 'decisions', 'The documented decline reasonCode tables (101-113, 120-128, 501-587, 643, 655, 901-906)', 'api', 'common'),
+  todo('veriff.decisions.granular_resubmission_codes', 'decisions', 'The documented resubmission reasonCode tables (201-218, 602-697)', 'api', 'common'),
+  // A FOURTH vendor doc contradiction: the decision schema declares `code` (and `reasonCode`)
+  // "type": "integer", and the decision WEBHOOK sample emits `"code": 9001` as a number — but the
+  // decision ENDPOINT's own response examples quote them ("code": "9121", "reasonCode": "102"). This
+  // twin emits numbers on both, following the declared type and the webhook sample.
+  todo('veriff.decisions.code_wire_type', 'decisions', 'Pin whether the live decision ENDPOINT serves `code`/`reasonCode` as JSON numbers or strings — the schema declares integer and the webhook sample agrees, while the endpoint\'s own examples quote them', 'api', 'niche'),
+  todo('veriff.decisions.review_code', 'decisions', 'Pin what `code` (if any) a live account sends alongside a `review` decision — the published schema\'s code enum has no entry for it, so this twin emits null', 'api', 'niche'),
+  todo('veriff.sessions.delete_refusal_codes', 'sessions', 'Pin the 1305/1306 split against a live account: the endpoint documents ONE blanket refusal (1305) yet also publishes a 1306 "Session in progress." whose stated trigger (`started`) is on the deletable list, so routing `submitted`→1306 is this twin\'s disambiguation, not a documented rule', 'api', 'niche'),
+  todo('veriff.decisions.code_numbering', 'decisions', 'Read the dedicated verification-session-status-codes table (linked from the decision endpoint but not fetched during this build) and reconcile it with the endpoint document this twin followed', 'api', 'niche'),
+  todo('veriff.decisions.person_full_field_set', 'decisions', 'The full person field set (addresses, nameComponents, parentNames, citizenship, electorNumber, eyeColor, …)', 'api', 'common'),
+  todo('veriff.decisions.document_full_field_set', 'decisions', 'The full document field set (state, placeOfIssue, issuedBy, remarks, residencePermitType, specimen, …)', 'api', 'common'),
+
+  // Proof of Address.
+  todo('veriff.proof_of_address.session', 'proof_of_address', 'A proofOfAddress session — the `address-front` capture context and its decision payload', 'api', 'common'),
+  todo('veriff.proof_of_address.address_validation', 'proof_of_address', 'additionalVerifiedData.proofOfAddress.addressValidationResult{status,…}', 'api', 'niche'),
+  todo('veriff.proof_of_address.address_matching', 'proof_of_address', 'additionalVerifiedData.proofOfAddress.addressMatching', 'api', 'niche'),
+  todo('veriff.proof_of_address.fraud_check', 'proof_of_address', 'additionalVerifiedData.proofOfAddress.fraud{reasonDescription,…}', 'api', 'niche'),
+
+  // Media — the parts of the media surface this twin does not model.
+  todo('veriff.media.pdf_upload', 'media', 'PDF proof-of-address upload (≤20MB, not enabled by default)', 'api', 'niche'),
+  todo('veriff.media.nfc_upload', 'media', 'The NFC media variant — com/sod/dg1/dg2 base64 payloads, `document-nfc` context, application/octet-stream', 'api', 'niche'),
+  todo('veriff.media.video_objects', 'media', 'Video media objects and their `duration` field (native SDK capture only)', 'api', 'niche'),
+  todo('veriff.media.size_limits', 'media', 'The documented upload limits (24MB base64 images, 20MB PDFs) enforced as the vendor enforces them', 'api', 'niche'),
+  todo('veriff.media.pre_capture_contexts', 'media', 'The `-pre` (first-capture) context family and how it pairs with the final capture', 'api', 'niche'),
+  todo('veriff.media.most_recent_attempt_only', 'media', 'GET /v1/sessions/{id}/media returns the MOST RECENT attempt\'s media only, as documented', 'api', 'common'),
+
+  // Webhooks — the families and behaviours not modeled.
+  todo('veriff.webhooks.flow_events', 'webhooks', 'The web-flow event actions and codes: waiting_continued 7008, waiting_complete 7007, flow_finished 7009, flow_cancelled 7010, document_type_other_selected 7011', 'api', 'common'),
+  todo('veriff.webhooks.event_context', 'webhooks', 'The optional event `context{reason,state}` object and its documented value tables', 'api', 'niche'),
+  todo('veriff.webhooks.user_defined_statuses', 'webhooks', 'The user-defined-statuses webhook family (custom status/statusCode/reason/reasonCode)', 'api', 'niche'),
+  todo('veriff.webhooks.full_auto', 'webhooks', 'The Full Auto webhook family', 'api', 'niche'),
+  todo('veriff.webhooks.registry_families', 'webhooks', 'The INE / CURP / combined INE+CURP webhook families', 'api', 'niche'),
+  todo('veriff.webhooks.retry_policy', 'webhooks', 'Veriff\'s delivery retry/redelivery behaviour for a failing receiver', 'api', 'common'),
+  todo('veriff.webhooks.master_signature_key', 'auth', 'Multiple shared secrets (up to 5) with ONE designated master signing key, and API responses signed with the key active when the request was made', 'api', 'niche'),
+  todo('veriff.webhooks.https_only', 'webhooks', 'Veriff calls HTTPS callback URLs only', 'api', 'niche'),
+
+  // Fraud / Feedback API — a separate host with its own VRF-* header scheme.
+  todo('veriff.fraud.report', 'fraud', 'POST /v1/feedback/fraud-reports on feedback.api.veriff.com', 'api', 'niche'),
+  todo('veriff.fraud.categories', 'fraud', 'GET /v1/feedback/fraud-categories', 'api', 'niche'),
+  todo('veriff.fraud.retrieve', 'fraud', 'POST /v1/feedback/fraud-reports/retrieve (signs the full request path only, despite being a POST)', 'api', 'niche'),
+  todo('veriff.fraud.vrf_header_scheme', 'auth', 'The Feedback API\'s VRF-AUTH-CLIENT / VRF-HMAC-SIGNATURE scheme, where a POST signs "path\\nbody"', 'api', 'niche'),
+
+  // Platform behaviours.
+  todo('veriff.platform.session_expiry', 'platform', 'Sessions expire after 7 days: `created` → expired, `started` → abandoned, without a client call', 'api', 'common'),
+  todo('veriff.platform.resubmission_limit', 'platform', 'The 9-resubmission cap: the 10th attempt auto-declines with reasonCode 539 "Resubmission limit exceeded"', 'api', 'common'),
+  todo('veriff.platform.rate_limit_429', 'platform', 'The documented 429 (`{"status":"fail","code":"1004","message":"Too many requests."}`) served by the twin against the published per-minute session ceiling', 'api', 'common'),
+  todo('veriff.platform.delete_purge_semantics', 'platform', 'DELETE\'s documented after-effects: an expired/abandoned decision webhook for a live session, and data purged within 12 hours', 'api', 'niche'),
+  todo('veriff.platform.credential_code_taxonomy', 'errors', 'The precise credential/authorization codes (1801-1804, 1812-1819) rather than the single 1812 this twin returns for every signature failure', 'api', 'common'),
+  todo('veriff.platform.troubleshooting_codes', 'errors', 'The remaining documented validation codes (1001-1003, 1102, 1104, 1201-1203, 1301, 1303, 1308-1310, 1403, 2003, 2101-2104)', 'api', 'common'),
+  todo('veriff.platform.timestamp_freshness', 'errors', 'Code 1201: "Invalid timestamp. Timestamp must not be older than one hour."', 'api', 'niche'),
+  todo('veriff.platform.account_base_url', 'platform', 'The account-specific BaseURL: this twin serves the paths and the injection map routes both stationapi.veriff.com and api.veriff.me, but the per-account host is not modeled', 'api', 'niche'),
+  todo('veriff.platform.legacy_vrf_headers', 'platform', 'The legacy `vrf-auth-client` / `vrf-hmac-sigature` (the vendor\'s own typo) / `vrf-integration-id` response headers, removed Oct 2 2025', 'api', 'niche'),
+  todo('veriff.platform.egress_allowlist', 'platform', 'The documented per-zone egress IP ranges a receiver allowlists', 'api', 'niche'),
+
+  // Connector gaps — filed against the twin's own denominator (see pull-audit.json).
+  todo('veriff.connector.pull_media_bytes', 'connector', 'Pull the media BYTES (GET /v1/media/{id}) alongside the metadata, so a pulled session\'s images are locally servable', 'connector', 'common'),
+  todo('veriff.connector.pull_watchlist', 'connector', 'Pull watchlist-screening results for a session (grounded in veriff.watchlist.get)', 'connector', 'common'),
+  todo('veriff.connector.pull_person', 'connector', 'Pull GET /v1/sessions/{id}/person as its own observed resource (grounded in veriff.person.get)', 'connector', 'niche'),
+  todo('veriff.connector.push_media', 'connector', 'Push locally captured media to a real session (grounded in veriff.media.upload)', 'connector', 'niche'),
+  // An honest limitation of push, found by reading the code rather than by a failing test: a session
+  // created AND submitted locally yields two pending actions, and the PATCH one addresses the LOCAL
+  // session id — which the real account has never seen, because the POST that preceded it minted a
+  // different id vendor-side. Push therefore converges a create, but not a create-then-submit pair,
+  // until local ids are remapped to the ids the vendor returned.
+  todo('veriff.connector.push_id_remapping', 'connector', 'Remap a locally-minted session id to the id the real account returns, so a create-then-submit pair pushes as one converging pair rather than a PATCH against an id the vendor never issued', 'connector', 'common'),
+  todo('veriff.connector.pull_backoff', 'connector', 'Honour a live 429\'s cooldown across a multi-session pull rather than refusing the whole batch', 'connector', 'niche'),
+];
+
+// ── the injected fake connector client (offline, deterministic) ──────────────
+
+const REMOTE_SESSION = '7f9a1c2e-0b3d-4e5f-8a91-2c3d4e5f6a7b';
+const OTHER_REMOTE = '1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d';
+const PULL_AT = '2026-08-01T00:00:00.000Z';
+
+/** A fake Veriff executor — the connector's injected boundary. No network, no SDK, no credential. */
+function fakeExecute(sessionId: string = REMOTE_SESSION): VeriffExecute {
+  return async (method, path) => {
+    if (method === 'GET' && path === `/sessions/${sessionId}/decision`) {
+      return {
+        status: 'success',
+        verification: {
+          id: sessionId, attemptId: `${sessionId}-att`, vendorData: 'remote-partner', endUserId: null,
+          status: 'approved', code: 9001, reason: null, reasonCode: null,
+          decisionTime: PULL_AT, acceptanceTime: PULL_AT, submissionTime: PULL_AT,
+          person: { firstName: 'REMOTE', lastName: 'PERSON', dateOfBirth: '1990-01-01' },
+          document: { number: 'AB1234', type: 'PASSPORT', country: 'EE' },
+          riskLabels: null,
+        },
+      };
+    }
+    if (method === 'GET' && path === `/sessions/${sessionId}/attempts`) {
+      return { status: 'success', verifications: [{ id: `${sessionId}-att`, status: 'approved', userDefinedData: [], createdTime: PULL_AT }] };
+    }
+    if (method === 'GET' && path === `/sessions/${sessionId}/media`) {
+      return {
+        status: 'success',
+        images: [{ id: `${sessionId}-img`, name: 'document-front', context: 'document-front', timestamp: null, size: 4242, mimetype: 'image/jpeg', url: `https://stationapi.veriff.com/v1/media/${sessionId}-img` }],
+        videos: [],
+        nfcDocuments: [],
+      };
+    }
+    return { status: 'success' };
+  };
+}
+
+/** Every budget test gets its OWN throwaway ledger file — a suite that spent against the operator's
+ *  real `~/.volter/veriff` ledger would poison every later run on the machine. */
+function throwawayLedger(): { path: string } {
+  return { path: join(mkdtempSync(join(tmpdir(), 'veriff-ledger-')), 'budget.json') };
+}
+
+/** A frozen clock, so a window can be filled without wall-clock time pruning spend mid-test. */
+function fixedClock(): () => number {
+  const t = Date.UTC(2026, 7, 1, 12, 0, 0);
+  return () => t;
+}
+
+export function veriffCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('veriff', VERIFF_CAPABILITIES);
+}