@volter/twin-twilio 0.1.0

package/dist/src/twilio-twin.js

@@ -0,0 +1,641 @@
+// Twilio API twin REQUEST HANDLER — a v1 slice of the Twilio messaging/telephony surface,
+// backed by the event/action-log kernel (@volter/world-core). Contract:
+//   handleTwilioTwinRequest({ method, path, body, host?, headers, root, readOnly }) -> { status, body, headers }
+//
+// SOURCE OF TRUTH: grounded read-only against Twilio's own published OpenAPI documents
+// (github.com/twilio/twilio-oai — twilio_api_v2010.json, twilio_verify_v2.json,
+// twilio_lookups_v2.json), the ACTUALLY-INSTALLED `twilio@6.0.2` npm SDK's own compiled source
+// (fetched via `npm pack`, read-only), and the public Twilio error-code reference pages
+// (twilio.com/docs/api/errors/<code>, fetched read-only) — see spec-sources.json for the full
+// grounding record and which facts came from which source. A doc-UNVERIFIED shape is annotated
+// inline (⚠) and NOT claimed beyond what the verify() actually proves.
+//
+// GROUNDED (live OpenAPI + live SDK source + live error-docs fetch, all during this build):
+//   - POST .../Messages.json -> 201 (twilio_api_v2010.json's own responses map: only "201" is
+//     documented for message create — NOT doc-UNVERIFIED, confirmed against the published spec).
+//   - GET .../Messages.json (list) envelope is EXACTLY {end, first_page_uri, next_page_uri, page,
+//     page_size, previous_page_uri, messages:[...]} (the real OpenAPI example, byte-for-byte —
+//     this pack models that shape, not the build spec's approximate {messages,page,page_size,uri}
+//     guess; num_segments/num_media are STRINGS on the wire, confirmed from the same example).
+//   - Message resource fields (sid/status/direction/...) confirmed against BOTH the OpenAPI
+//     schema AND the installed SDK's `MessageInstance` constructor (message.js) — no top-level
+//     `type` field exists on a Message (unlike Account/IncomingPhoneNumber below), so no kernel
+//     type/id/updatedAt collision risk there.
+//   - Verify Verifications POST -> 201, requires {To, Channel} (twilio_verify_v2.json's own
+//     `required` array). VerificationCheck POST documents BOTH "200" and "201" as valid response
+//     codes (no semantic split in the generated doc) — this twin picks 200 consistently for
+//     VerificationCheck (a "check", not a "create"), which is itself doc-legitimate, not a guess.
+//   - Lookup PhoneNumbers GET -> 200; `line_type_intelligence.type` confirmed NESTED (never a
+//     top-level field) against both the OpenAPI schema and the SDK's `LineTypeIntelligenceInfo`
+//     class — the kernel type/id/updatedAt reserved-field gotcha (actions.ts:153,219) does NOT
+//     bite here even before accounting for Lookup being a pure derivation with no kernel row.
+//   - Exact error {code,message} pairs for 21211/21604/20404/60200/60202/20003 fetched LIVE from
+//     twilio.com/docs/api/errors/<code> (read-only) — GROUNDED, not the build spec's own
+//     doc-UNVERIFIED placeholder text. HTTP status per code (400/404/401) is modeled by
+//     well-established REST convention (not independently re-confirmed byte-for-byte per code
+//     from that page, which does not expose an explicit http_status_code field) — noted honestly.
+//   - X-Twilio-Signature scheme (base64(HMAC-SHA1(AuthToken, URL + sorted-concat params))) is
+//     VERBATIM-ported from the installed SDK's OWN `lib/webhooks/webhooks.js` source — see
+//     twilio-signature.ts's header for the exact function-level citation.
+//   - THE SDK HTTPCLIENT SEAM (build spec §7.2/§13.1, HIGHEST RISK): `new Twilio(sid, token, {
+//     httpClient })` accepts an INJECTABLE httpClient (`opts.httpClient`, `lib/base/BaseTwilio.js`
+//     `setOpts`/`get httpClient()`) that receives the FULL absolute `uri` per call — verified LIVE
+//     in Node against the installed 6.0.2 package (a throwaway `Bun.serve` server + a custom
+//     httpClient forwarding every domain's request to it) BEFORE twilio-sdk.integration.test.ts
+//     was written: `client.messages.create`, `client.verify.v2.services(...).verifications.create`,
+//     and `client.lookups.v2.phoneNumbers(...).fetch()` ALL routed correctly, with the real
+//     x-www-form-urlencoded body encoding and Basic-auth header construction, and a REAL
+//     `RestException` round-tripped through our {code,message,more_info,status} envelope with the
+//     correct `.code`/`.status`/`.message`. This is a REAL rung-4 SDK test (not the fetch-fallback
+//     path).
+//
+// A THIRD KERNEL-GOTCHA APPLICATION FOUND DURING GROUNDING (beyond the build spec's own Lookup
+// callout): BOTH the real Twilio `Account` resource (`account_enum_type`: Trial|Full — confirmed
+// in twilio_api_v2010.json's `api.v2010.account` schema AND the SDK's `AccountInstance.type`) AND
+// the real `IncomingPhoneNumber` resource (`payload.type`, confirmed in the SDK's
+// `IncomingPhoneNumberInstance` constructor) carry a TOP-LEVEL `type` field that would collide
+// with the kernel's reserved id/type/updatedAt row-meta (actions.ts:153,219 — `META.has(k)`
+// silently DROPS any field literally named `type` when re-serializing a kernel resource) if either
+// were ever written through `applyTwinWrite`/read through the generic `view()` helper unchanged.
+// This build avoids the collision two different ways, chosen per resource:
+//   - `accounts.fetch` is modeled as a PURE per-root derivation (mirrors fal-webhooks.ts's JWKS/
+//     signing_key pattern) — it never calls `applyTwinWrite`, so its `type` field is a plain
+//     JSON-literal property, never touches the kernel merge/META-filter pipeline at all.
+//   - `phone_number` rows (IncomingPhoneNumbers) genuinely ARE kernel-persisted (lazily seeded on
+//     first list, per root — the fal signing_key "fold on first touch" idiom), so THIS one takes
+//     the build spec's prescribed rename-and-remap: stored as `number_type` internally, renamed
+//     back to `type` only in `phoneNumberView()`'s output — never a bare top-level `type` field in
+//     a `fields` write.
+//
+// State lives ENTIRELY in the kernel action log: writes go through `applyTwinWrite`, reads are
+// the projection (`projectResources`). There is NO Map/array side-store (D1). No real Twilio is
+// ever contacted.
+//
+// KERNEL GOTCHA — field-MERGE null-erasure (actions.ts:202, `overlay()`'s `{...existing.fields,
+// ...fields}` shallow merge NEVER removes a field): `handleMessageCreate` writes EXPLICIT nulls
+// for `date_sent`/`error_code`/`error_message` at creation (so the real API's always-present-but-
+// initially-null fields show up from the start, matching the OpenAPI example's shape) and the
+// poll-fold ONLY ever sets NEW values on top (never needs to re-null anything in this pack's
+// deterministic non-failing lifecycle, but the discipline — write intended nulls explicitly,
+// never rely on omission to clear a field — is applied throughout, mirroring fal-twin.ts's own
+// `request.create` write).
+//
+// Honesty (D2): an unmodeled route / unknown resource returns Twilio's OWN documented error
+// envelope `{code, message, more_info, status}` (grounded — twilio.com/docs/api/errors), never a
+// fabricated success. readOnly rejects writes with 405.
+//
+// Kernel SUBJECT ids are type-prefixed (`message:<sid>`, `verification:<sid>`,
+// `phone_number:<sid>`) — the PUBLIC sid emitted to clients is the bare Twilio-shaped sid
+// (SM…/VE…/PN…). `kid()` builds the subject id; `rows()` strips the prefix back off.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { presentedTwilioCredentials, storedTwilioCredentials, twilioCredentials } from "./twilio-credentials.js";
+const SERVICE = 'twilio';
+const API_VERSION = '2010-04-01';
+// Resource types the twin actually PROJECTS in the kernel — the honest v1 subset. `signing_key`
+// is the world's OWN AccountSid/AuthToken pair (never itself REST-addressable — see fal's
+// `signing_key` precedent): a kernel-persisted singleton established exactly once per root,
+// entropy-born or seeded from the Basic pair a caller presents (twilio-credentials.ts), and the
+// credential `accounts.fetch` serves and every `X-Twilio-Signature` is computed with. It was a
+// declaration with nothing behind it while the pair was derived from the world's directory path.
+export const TWILIO_RESOURCE_TYPES = ['message', 'verification', 'phone_number', 'signing_key'];
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+export function routeTwilioSurface(req) {
+    const headers = lowerHeaders(req.headers);
+    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    const explicitHost = req.host ?? headers['host'];
+    if (explicitHost === 'api.twilio.com')
+        return 'api';
+    if (explicitHost === 'verify.twilio.com')
+        return 'verify';
+    if (explicitHost === 'lookups.twilio.com')
+        return 'lookup';
+    if (path.includes('/Services/'))
+        return 'verify';
+    if (path.includes('/PhoneNumbers/'))
+        return 'lookup';
+    if (path.includes('/Accounts/'))
+        return 'api';
+    return 'api'; // default (documented above)
+}
+// ── error envelope (Twilio's OWN documented shape — NOT fal's {detail}) ──────────────────────
+// {code, message, more_info, status} — grounded verbatim from twilio.com/docs/api/errors/<code>
+// (live fetch) AND the installed SDK's own `RestException` constructor (`body.message`/
+// `body.code`/`body.more_info` — this envelope round-trips through it unchanged, confirmed live).
+function twilioError(code, message, httpStatus) {
+    return { status: httpStatus, body: { code, message, more_info: `https://www.twilio.com/docs/errors/${code}`, status: httpStatus } };
+}
+function notFound() {
+    return twilioError(20404, 'The requested resource was not found', 404);
+}
+// ── form-urlencoded body parsing (build spec §1 divergence 2 / §13.9) — NOT JSON.parse ────────
+// A JSON-shaped body (starts with `{`/`[` after trimming) is rejected vendor-shaped 400 — a real
+// Twilio endpoint fed a JSON content body would fail to parse its expected form fields the same
+// way (this twin makes that failure explicit and typed rather than silently misparsing).
+function parseFormBody(body) {
+    if (body === undefined || body === '')
+        return { ok: true, value: {} };
+    const trimmed = body.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('['))
+        return { ok: false };
+    const params = new URLSearchParams(body);
+    const value = {};
+    for (const [k, v] of params)
+        value[k] = v;
+    return { ok: true, value };
+}
+function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+/** Twilio's own message/account timestamp wire format (RFC 2822-ish, e.g. "Fri, 24 May 2019
+ *  17:44:46 +0000") — grounded from the twilio_api_v2010.json Messages-list example AND the
+ *  SDK's own `deserialize.rfc2822DateTime` parse target. */
+function rfc2822(occurredAt) {
+    return new Date(nowIso(occurredAt)).toUTCString().replace('GMT', '+0000');
+}
+function kid(type, id) {
+    return `${type}:${id}`;
+}
+// ── projection helpers ──────────────────────────────────────────────────────────────
+function rows(type, root) {
+    const prefix = `${type}:`;
+    return projectResources(SERVICE, root)
+        .filter((r) => r.type === type && r.id.startsWith(prefix) && r._deleted !== true)
+        .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
+}
+function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+function view(r) {
+    const { type: _t, updatedAt: _u, ...rest } = r;
+    const out = {};
+    for (const [k, v] of Object.entries(rest))
+        if (!k.startsWith('_'))
+            out[k] = v;
+    return out;
+}
+/** EVERY Twilio resource this pack serves is public-addressed by `sid` (SM…/VE…/PN…), never the
+ *  kernel's generic `id` field name — `rows()`/`getRow()` strip the kernel's type-prefix off the
+ *  subject id into `.id` (an internal convention shared with every sibling pack), but Twilio's
+ *  OWN wire shape has no bare `id` field at all. This renames it on the way out — the one place a
+ *  kernel-internal field name touches an HTTP response body. */
+function sidView(r) {
+    const v = view(r);
+    const { id, ...rest } = v;
+    return { sid: id, ...rest };
+}
+/** phone_number rows rename the reserved `type` field to `number_type` on write (kernel gotcha —
+ *  see header) — this remaps it BACK to `type` on read, the only place the real vendor field name
+ *  is restored (and, like `sidView`, renames `id` -> `sid`). */
+function phoneNumberView(r) {
+    const base = sidView(r);
+    const { number_type, ...rest } = base;
+    return { ...rest, type: number_type ?? null };
+}
+async function write(type, id, fields, op, req) {
+    const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: kid(type, id), fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
+    return sidView({ ...resource, id });
+}
+// ── ids ────────────────────────────────────────────────────────────────────────────
+// DETERMINISTIC (R9, resource level): every SID's 32 hex characters are a stable hash of
+// `${type}:${occurredAt}:${ordinal}` — the world instant the write happened at plus the count of
+// rows the type ALREADY holds, read BEFORE the insert. It used to be a sha256 of a fresh
+// per-call UUID, so two identical worlds served different SIDs and no replay of this pack could
+// ever be byte-identical. Two identical sends at ONE instant still land as two messages with
+// distinct SIDs: the ordinal moved between them. The SHAPE is unchanged (the vendor's
+// `SM`/`VE`/`VL` + 32 lowercase hex).
+function stableSid(prefix, seed) {
+    return `${prefix}${createHash('sha256').update(seed).digest('hex').slice(0, 32)}`;
+}
+function newMessageSid(req) {
+    return stableSid('SM', `message:${req.occurredAt ?? ''}:${rows('message', req.root).length}`);
+}
+function newVerificationSid(req) {
+    return stableSid('VE', `verification:${req.occurredAt ?? ''}:${rows('verification', req.root).length}`);
+}
+function newPhoneNumberSid(seed) {
+    return `PN${createHash('sha256').update(seed).digest('hex').slice(0, 32)}`;
+}
+// ── MESSAGES ──────────────────────────────────────────────────────────────────────────────────
+const E164_RE = /^\+[1-9]\d{6,14}$/;
+/** num_segments is computed once at send time from the body's length (GSM-7 single-segment
+ *  threshold 160 chars, concatenated-segment threshold 153 — a well-established, if not
+ *  byte-for-byte SDK-confirmed, SMS-encoding convention; the field is a STRING on the wire,
+ *  confirmed from the live OpenAPI example). */
+function computeNumSegments(body) {
+    if (body.length === 0)
+        return '1';
+    if (body.length <= 160)
+        return '1';
+    return String(Math.ceil(body.length / 153));
+}
+function messageUrls(accountSid, sid) {
+    const base = `/${API_VERSION}/Accounts/${accountSid}/Messages/${sid}`;
+    return { uri: `${base}.json`, subresource_uris: { media: `${base}/Media.json`, feedback: `${base}/Feedback.json` } };
+}
+async function handleMessageCreate(accountSid, form, req) {
+    const to = form.To;
+    const from = form.From ?? '';
+    const body = form.Body ?? '';
+    if (!to)
+        return twilioError(21604, "The destination 'To' phone number is required to send an SMS", 400);
+    if (!E164_RE.test(to))
+        return twilioError(21211, "Invalid 'To' Phone Number", 400);
+    const sid = newMessageSid(req);
+    const createdAt = nowIso(req.occurredAt);
+    await write('message', sid, {
+        account_sid: accountSid,
+        api_version: API_VERSION,
+        body,
+        to,
+        from,
+        direction: 'outbound-api',
+        status: 'queued',
+        num_segments: computeNumSegments(body),
+        num_media: '0',
+        messaging_service_sid: form.MessagingServiceSid ?? null,
+        date_created: rfc2822(createdAt),
+        date_updated: rfc2822(createdAt),
+        date_sent: null,
+        error_code: null,
+        error_message: null,
+        price: null,
+        price_unit: null,
+        poll_count: 0,
+        _status_callback: form.StatusCallback ?? null, // internal bookkeeping (not a real Message response field) -> stripped by view()
+    }, 'message.create', req);
+    const row = getRow('message', sid, req.root);
+    return { status: 201, body: { ...sidView(row), ...messageUrls(accountSid, sid) } };
+}
+/**
+ * Deterministic, kernel-folded poll-count progression (mirrors fal-twin.ts's `progressOnce`,
+ * ported to Twilio's 4-step delivery lifecycle, build spec §2/§6): the FIRST status poll after
+ * send is a `queued` echo, the SECOND transitions to `sending`, the THIRD to `sent` (stamping
+ * `date_sent`), the FOURTH (and every poll thereafter) to `delivered` — terminal, idempotent. No
+ * wall clock, no timers.
+ */
+async function progressMessageOnce(sid, req) {
+    const row = getRow('message', sid, req.root);
+    if (!row)
+        return;
+    const pollCount = row.poll_count ?? 0;
+    const status = row.status;
+    if (status === 'queued') {
+        if (pollCount === 0) {
+            await write('message', sid, { poll_count: pollCount + 1 }, 'message.poll', req);
+            return;
+        }
+        await write('message', sid, { status: 'sending', poll_count: pollCount + 1 }, 'message.progress', req);
+        return;
+    }
+    if (status === 'sending') {
+        await write('message', sid, { status: 'sent', date_sent: rfc2822(nowIso(req.occurredAt)), date_updated: rfc2822(nowIso(req.occurredAt)), poll_count: pollCount + 1 }, 'message.progress', req);
+        return;
+    }
+    if (status === 'sent') {
+        await write('message', sid, { status: 'delivered', date_updated: rfc2822(nowIso(req.occurredAt)), poll_count: pollCount + 1 }, 'message.complete', req);
+        return;
+    }
+    // delivered / undelivered / failed: terminal — idempotent no-op.
+}
+async function handleMessageGet(accountSid, sid, req) {
+    const existing = getRow('message', sid, req.root);
+    if (!existing)
+        return notFound();
+    await progressMessageOnce(sid, req);
+    const row = getRow('message', sid, req.root);
+    return { status: 200, body: { ...sidView(row), ...messageUrls(accountSid, sid) } };
+}
+function handleMessageList(accountSid, req) {
+    const messages = rows('message', req.root)
+        .filter((r) => r.account_sid === accountSid)
+        .map((r) => ({ ...sidView(r), ...messageUrls(accountSid, r.id) }));
+    const listUri = `/${API_VERSION}/Accounts/${accountSid}/Messages.json`;
+    return {
+        status: 200,
+        body: {
+            end: Math.max(messages.length - 1, 0),
+            first_page_uri: `${listUri}?PageSize=50&Page=0`,
+            next_page_uri: null,
+            page: 0,
+            page_size: 50,
+            previous_page_uri: null,
+            messages,
+            uri: listUri,
+        },
+    };
+}
+// ── ACCOUNTS (the world's OWN credential, established once and persisted — see header note) ───
+// The `type` field is still a plain JSON literal on the way out, never a `fields` write, so the
+// kernel's reserved-row-meta collision the build spec found stays avoided; what changed is WHERE
+// `auth_token` comes from — the root's persisted `signing_key` row (twilio-credentials.ts), not a
+// hash of the world's directory. Async because reading a virgin root's credential establishes it.
+async function handleAccountFetch(sid, req) {
+    const at = rfc2822(nowIso(req.occurredAt));
+    const uri = `/${API_VERSION}/Accounts/${sid}.json`;
+    // A read-only world cannot be written to, so it reports what it already holds and otherwise an
+    // empty token — never a fresh one it would forget the moment the response is sent.
+    const creds = req.readOnly ? storedTwilioCredentials(req.root) : await twilioCredentials(req.root);
+    return {
+        status: 200,
+        body: {
+            sid,
+            auth_token: creds?.authToken ?? '',
+            friendly_name: 'Twin Account',
+            status: 'active',
+            type: 'Full',
+            owner_account_sid: sid,
+            date_created: at,
+            date_updated: at,
+            uri,
+            subresource_uris: {
+                messages: `/${API_VERSION}/Accounts/${sid}/Messages.json`,
+                incoming_phone_numbers: `/${API_VERSION}/Accounts/${sid}/IncomingPhoneNumbers.json`,
+            },
+        },
+    };
+}
+// ── INCOMING PHONE NUMBERS (lazily-seeded, kernel-persisted — "fold on first touch") ──────────
+const SEED_PHONE_NUMBERS = [
+    { phone_number: '+15550001111', friendly_name: 'Twin Local Number', numberType: 'local' },
+    { phone_number: '+18005550100', friendly_name: 'Twin Toll-Free Number', numberType: 'toll-free' },
+];
+async function ensureSeedPhoneNumbers(accountSid, req) {
+    const existing = rows('phone_number', req.root);
+    if (existing.length > 0)
+        return;
+    const at = rfc2822(nowIso(req.occurredAt));
+    for (const seed of SEED_PHONE_NUMBERS) {
+        const sid = newPhoneNumberSid(seed.phone_number);
+        await write('phone_number', sid, {
+            account_sid: accountSid,
+            phone_number: seed.phone_number,
+            friendly_name: seed.friendly_name,
+            number_type: seed.numberType, // renamed from Twilio's real top-level `type` — kernel gotcha (see header)
+            capabilities: { voice: true, sms: true, mms: true, fax: false },
+            sms_url: null,
+            voice_url: null,
+            status_callback: null,
+            date_created: at,
+            date_updated: at,
+            uri: `/${API_VERSION}/Accounts/${accountSid}/IncomingPhoneNumbers/${sid}.json`,
+        }, 'phone_number.seed', req);
+    }
+}
+async function handleIncomingPhoneNumbersList(accountSid, req) {
+    await ensureSeedPhoneNumbers(accountSid, req);
+    const listUri = `/${API_VERSION}/Accounts/${accountSid}/IncomingPhoneNumbers.json`;
+    const numbers = rows('phone_number', req.root).filter((r) => r.account_sid === accountSid).map(phoneNumberView);
+    return {
+        status: 200,
+        body: {
+            end: Math.max(numbers.length - 1, 0),
+            first_page_uri: `${listUri}?PageSize=50&Page=0`,
+            next_page_uri: null,
+            page: 0,
+            page_size: 50,
+            previous_page_uri: null,
+            incoming_phone_numbers: numbers,
+            uri: listUri,
+        },
+    };
+}
+// ── VERIFY (start/check, twin-internal deterministic expected code) ───────────────────────────
+// The real OTP is never sent (D2 honesty — README/`## Coverage` disclose this): the expected code
+// is a PURE, deterministic function of (serviceSid, to) so both this handler and a verify()/test
+// can independently RE-DERIVE the same 6-digit code without any shared mutable state, exactly the
+// build spec's own formula (§3/§6).
+function expectedVerificationCode(serviceSid, to) {
+    const hex = createHash('sha256').update(`${serviceSid}:${to}`).digest('hex').slice(0, 6);
+    return String(parseInt(hex, 16) % 1_000_000).padStart(6, '0');
+}
+function verificationLookupKey(serviceSid, to) {
+    return `${serviceSid}::${to}`;
+}
+function findVerificationByLookup(serviceSid, to, root) {
+    return rows('verification', root).find((r) => r._lookup_key === verificationLookupKey(serviceSid, to));
+}
+async function handleVerificationStart(serviceSid, form, req) {
+    const to = form.To;
+    const channel = form.Channel;
+    if (!to || !channel)
+        return twilioError(60200, 'Invalid parameter', 400);
+    const sid = newVerificationSid(req);
+    const at = nowIso(req.occurredAt);
+    await write('verification', sid, {
+        service_sid: serviceSid,
+        account_sid: (await twilioCredentials(req.root)).accountSid,
+        to,
+        channel,
+        status: 'pending',
+        valid: false,
+        lookup: {},
+        amount: null,
+        payee: null,
+        send_code_attempts: [{ time: at, channel, attempt_sid: stableSid('VL', `${sid}:attempt:0`) }],
+        sna: null,
+        date_created: at,
+        date_updated: at,
+        _lookup_key: verificationLookupKey(serviceSid, to), // internal index -> stripped by view() (never leaked to a caller)
+        _expected_code: expectedVerificationCode(serviceSid, to), // underscore-prefixed -> stripped by view() (never leaked to a caller)
+    }, 'verification.create', req);
+    const row = getRow('verification', sid, req.root);
+    return { status: 201, body: { ...sidView(row), url: `https://verify.twilio.com/v2/Services/${serviceSid}/Verifications/${sid}` } };
+}
+async function handleVerificationCheck(serviceSid, form, req) {
+    const code = form.Code ?? '';
+    const to = form.To;
+    const verificationSid = form.VerificationSid;
+    let row = verificationSid ? getRow('verification', verificationSid, req.root) : undefined;
+    if (!row && to)
+        row = findVerificationByLookup(serviceSid, to, req.root);
+    if (!row)
+        return notFound();
+    const sid = row.id;
+    const currentStatus = row.status;
+    if (currentStatus === 'approved') {
+        return { status: 200, body: { ...sidView(row), url: `https://verify.twilio.com/v2/Services/${serviceSid}/Verifications/${sid}` } };
+    }
+    const expected = row._expected_code;
+    const approves = code.length > 0 && code === expected;
+    if (approves) {
+        await write('verification', sid, { status: 'approved', valid: true, date_updated: nowIso(req.occurredAt) }, 'verification.check', req);
+    }
+    const updated = getRow('verification', sid, req.root);
+    return { status: 200, body: { ...sidView(updated), url: `https://verify.twilio.com/v2/Services/${serviceSid}/Verifications/${sid}` } };
+}
+// ── LOOKUP (PURE deterministic derivation — no kernel row, build spec §3) ─────────────────────
+function deriveLineType(digits) {
+    const h = parseInt(createHash('sha256').update(digits).digest('hex').slice(0, 4), 16);
+    const kinds = ['mobile', 'landline', 'voip'];
+    return kinds[h % kinds.length];
+}
+function handleLookup(e164, fields, req) {
+    if (!E164_RE.test(e164))
+        return notFound();
+    const digits = e164.slice(1);
+    const countryCode = digits.startsWith('1') && digits.length === 11 ? 'US' : 'XX';
+    const nationalFormat = countryCode === 'US'
+        ? `(${digits.slice(1, 4)}) ${digits.slice(4, 7)}-${digits.slice(7)}`
+        : digits;
+    const body = {
+        calling_country_code: digits.startsWith('1') ? '1' : digits.slice(0, 2),
+        country_code: countryCode,
+        phone_number: e164,
+        national_format: nationalFormat,
+        valid: true,
+        validation_errors: null,
+        caller_name: null,
+        sim_swap: null,
+        call_forwarding: null,
+        live_activity: null,
+        line_type_intelligence: null,
+        identity_match: null,
+        reassigned_number: null,
+        sms_pumping_risk: null,
+        phone_number_quality_score: null,
+        pre_fill: null,
+        url: `https://lookups.twilio.com/v2/PhoneNumbers/${encodeURIComponent(e164)}`,
+    };
+    const requested = fields.split(',').map((f) => f.trim()).filter(Boolean);
+    if (requested.includes('line_type_intelligence')) {
+        body.line_type_intelligence = {
+            // `type` is NESTED here (never a top-level kernel field) — see header. Lookup has no kernel
+            // row at all, so the reserved-field gotcha is moot for this route regardless.
+            type: deriveLineType(digits),
+            mobile_country_code: countryCode === 'US' ? '310' : null,
+            mobile_network_code: countryCode === 'US' ? '150' : null,
+            carrier_name: `Twin Carrier ${digits.slice(-3)}`,
+            error_code: null,
+        };
+    }
+    return { status: 200, body };
+}
+// ── route handler ────────────────────────────────────────────────────────────────────
+export async function handleTwilioTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const [rawPath, rawQuery] = req.path.split('?');
+    const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+    const surface = routeTwilioSurface({ host: req.host, headers: req.headers, path });
+    const query = new URLSearchParams(rawQuery ?? '');
+    if (req.readOnly && method !== 'GET' && method !== 'HEAD') {
+        return { status: 405, body: { code: 20005, message: 'twin is read-only; omit readOnly to accept writes', more_info: 'https://www.twilio.com/docs/errors/20005', status: 405 } };
+    }
+    // TRUST ON FIRST USE — the behavioral contract's (adding-a-twin.md, "Keep the three kinds of credential apart") "fake vendor creds an app presents are twin STATE,
+    // seeded via the wire". The real Twilio SDK authenticates every call with
+    // `Authorization: Basic base64(AccountSid:AuthToken)`, so an app wired at this twin already
+    // presents its pair without being asked to do anything special: on a VIRGIN world that pair
+    // becomes the world's own (persisted as the declared `signing_key` resource), which is what
+    // makes `GET Accounts/{Sid}.json` hand the app back its OWN AuthToken and what makes every
+    // `X-Twilio-Signature` this world signs verify against the key the app already holds. It happens
+    // exactly once: `twilioCredentials` short-circuits on a stored pair, and a world that has one is
+    // never re-seeded. A read-only world cannot be written to, so it is never seeded at all.
+    if (!req.readOnly) {
+        const presented = presentedTwilioCredentials(req.headers);
+        if (presented)
+            await twilioCredentials(req.root, presented);
+    }
+    let form = {};
+    if (method === 'POST' || method === 'PUT') {
+        const parsed = parseFormBody(req.body);
+        if (!parsed.ok)
+            return twilioError(60200, 'Invalid parameter: request body must be application/x-www-form-urlencoded, not JSON', 400);
+        form = parsed.value;
+    }
+    if (path === '/' || path === '') {
+        return { status: 200, body: { service: 'twilio', object: 'twin' } };
+    }
+    const seg = path.replace(/^\/+/, '').split('/').filter(Boolean);
+    // ── api.twilio.com: /2010-04-01/Accounts/{AccountSid}/... ──
+    if (surface === 'api') {
+        if (seg[0] !== API_VERSION || seg[1] !== 'Accounts' || !seg[2])
+            return notFound();
+        const third = decodeURIComponent(seg[2]);
+        // Accounts/{Sid}.json — the ACCOUNT ITSELF: exactly 3 segments, the 3rd IS "{Sid}.json"
+        // (no further nesting — distinct from the {AccountSid}/{Resource...} shape below, where the
+        // 3rd segment is the bare AccountSid with NO .json suffix).
+        if (seg.length === 3 && third.endsWith('.json') && method === 'GET') {
+            return await handleAccountFetch(third.slice(0, -'.json'.length), req);
+        }
+        const accountSid = third;
+        const rest = seg.slice(3);
+        if (rest.length === 1 && rest[0] === 'Messages.json' && method === 'POST') {
+            return handleMessageCreate(accountSid, form, req);
+        }
+        if (rest.length === 1 && rest[0] === 'Messages.json' && method === 'GET') {
+            return handleMessageList(accountSid, req);
+        }
+        if (rest.length === 2 && rest[0] === 'Messages' && rest[1].endsWith('.json') && method === 'GET') {
+            const sid = rest[1].slice(0, -'.json'.length);
+            return handleMessageGet(accountSid, sid, req);
+        }
+        if (rest.length === 1 && rest[0] === 'IncomingPhoneNumbers.json' && method === 'GET') {
+            return handleIncomingPhoneNumbersList(accountSid, req);
+        }
+        return notFound();
+    }
+    // ── verify.twilio.com: /v2/Services/{ServiceSid}/Verifications[Check] ──
+    if (surface === 'verify') {
+        // seg: ['v2','Services',serviceSid, 'Verifications' | 'VerificationCheck' | ...]
+        if (seg[0] !== 'v2' || seg[1] !== 'Services' || !seg[2])
+            return notFound();
+        const serviceSid = decodeURIComponent(seg[2]);
+        const rest = seg.slice(3);
+        if (rest.length === 1 && rest[0] === 'Verifications' && method === 'POST') {
+            return handleVerificationStart(serviceSid, form, req);
+        }
+        if (rest.length === 1 && rest[0] === 'VerificationCheck' && method === 'POST') {
+            return handleVerificationCheck(serviceSid, form, req);
+        }
+        // NIT: GET fetch-by-sid — an unmodeled-but-present convenience route (not a claimed capability;
+        // harmless superset over the start/check surface actually tracked in capability-manifests.ts).
+        if (rest.length === 2 && rest[0] === 'Verifications' && method === 'GET') {
+            const row = getRow('verification', decodeURIComponent(rest[1]), req.root);
+            if (!row)
+                return notFound();
+            return { status: 200, body: { ...sidView(row), url: `https://verify.twilio.com/v2/Services/${serviceSid}/Verifications/${row.id}` } };
+        }
+        return notFound();
+    }
+    // ── lookups.twilio.com: /v2/PhoneNumbers/{E164} ──
+    if (surface === 'lookup') {
+        if (seg[0] !== 'v2' || seg[1] !== 'PhoneNumbers' || !seg[2])
+            return notFound();
+        if (method !== 'GET')
+            return notFound();
+        const e164 = decodeURIComponent(seg.slice(2).join('/'));
+        return handleLookup(e164, query.get('Fields') ?? '', req);
+    }
+    return notFound();
+}
+// Endpoint inventory used by the conformance snapshot (self-referential — see
+// twilio-conformance.ts header note and docs/contributing/conformance.md's "2 spec" discussion, shared with fal/
+// replicate/elevenlabs/polar).
+export function twilioTwinSnapshot() {
+    return {
+        resourceTypes: TWILIO_RESOURCE_TYPES,
+        implementedEndpoints: [
+            'POST api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json (send, 201)',
+            'POST api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json (400 21604 missing To)',
+            'POST api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json (400 21211 invalid To)',
+            'GET api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json (status poll-progression)',
+            'GET api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json (404 unknown sid)',
+            'GET api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json (list envelope)',
+            'GET api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json (seeded list)',
+            'GET api.twilio.com/2010-04-01/Accounts/{Sid}.json (accounts fetch, pure derivation)',
+            'POST verify.twilio.com/v2/Services/{ServiceSid}/Verifications (start, 201)',
+            'POST verify.twilio.com/v2/Services/{ServiceSid}/Verifications (400 60200 missing param)',
+            'POST verify.twilio.com/v2/Services/{ServiceSid}/VerificationCheck (correct code -> approved)',
+            'POST verify.twilio.com/v2/Services/{ServiceSid}/VerificationCheck (wrong code -> pending)',
+            'POST verify.twilio.com/v2/Services/{ServiceSid}/VerificationCheck (404 unknown)',
+            'GET lookups.twilio.com/v2/PhoneNumbers/{E164} (basic)',
+            'GET lookups.twilio.com/v2/PhoneNumbers/{E164}?Fields=line_type_intelligence',
+            'GET lookups.twilio.com/v2/PhoneNumbers/{E164} (404 invalid number)',
+        ],
+    };
+}