@volter/twin-twilio 0.1.0

package/src/twilio-capabilities.ts

@@ -0,0 +1,436 @@
+// Twilio capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from what the Twilio API actually does — GROUNDED read-only (2026-07-09) against the published
+// twilio-oai 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
+// source (fetched via `npm pack`), and the public Twilio error-code reference pages
+// (twilio.com/docs/api/errors/<code>, fetched read-only) — see spec-sources.json — NOT from what
+// this twin has built. This is the honest denominator: many entries start as `todo` and coverage
+// reads LOW until the twin truly reaches 100% of the API. `verify()` (required to count as done)
+// is ground truth and drives the KERNEL-BACKED handler on a FRESH temp root — never a spawned
+// mock. `expected:'done'` only on capabilities we genuinely claim, so a broken one shows as a
+// regression.
+//
+// v1 SLICE (honesty, per the build spec): Messages send + async delivery-status lifecycle
+// (queued->sending->sent->delivered, kernel-folded poll-progression, no wall clock) + Verify
+// start/check (twin-internal deterministic expected code — no real OTP is ever sent) + Lookup
+// (pure deterministic derivation) + IncomingPhoneNumbers list (lazily-seeded) + Accounts fetch
+// (pure per-root derivation) + X-Twilio-Signature-signed status-callback/inbound webhooks are
+// modeled `done`. MMS media, Messaging Services/Copilot, TwiML/voice, Conversations,
+// and sub-accounts are left `todo` — a deliberate v1 scope cut, not an oversight; see README
+// `## Coverage`.
+//
+// THE DETERMINISTIC VERIFY CODE: Verify never sends a real OTP (no SMS/voice/email provider is
+// contacted) — the "expected code" is a pure, deterministic function of (serviceSid, to) both
+// this twin and a caller can independently re-derive. The lifecycle SEMANTICS (right code
+// approves, wrong code stays pending) are faithful.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary, isInfrastructureError, harnessError } from '@volter/world-tooling';
+import { handleTwilioTwinRequest, type TwilioResponse } from './twilio-twin.ts';
+import { checkTwilioConformance } from './twilio-conformance.ts';
+import { syncTwilioFromReal, type TwilioLikeClient } from './twilio-connector.ts';
+import {
+  verifyTwilioSignature,
+  buildSignedStatusCallback,
+  buildSignedInboundMessage,
+  TwilioSignatureVerificationError,
+} from './twilio-signature.ts';
+import { twilioAuthToken } from './twilio-credentials.ts';
+
+// (Twilio is an API-first vendor for this pack's surface — docs/contributing/architecture.md C1b — so this pack
+// ships no mirror; the Console is a config/analytics dashboard, not an agent navigation target —
+// see README `## Coverage` and ui-scope.json needsUi:false.)
+
+const OCCURRED_AT = '2026-01-01T00:00:00.000Z';
+const ACCOUNT_SID = 'ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+// The pair the three PURE-CRYPTO webhook verifies sign and verify with. They assert the ALGORITHM
+// — that a built delivery verifies and a tampered one does not — so they take an explicit,
+// vendor-shaped pair rather than reaching for a world's: twilio-signature.ts holds no credential
+// and reads no state, which is exactly why it is legitimately mutation-test ALLOW-listed. A
+// world's own pair (`twilioAuthToken(root)`) is what `twilio.accounts.fetch` below asserts.
+const SIGNING_PAIR = { accountSid: ACCOUNT_SID, authToken: 'b'.repeat(32) };
+const SERVICE_SID = 'VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+
+/** Pure re-derivation of the twin's expected Verify code, SAME formula as twilio-twin.ts's
+ *  (private, unexported) `expectedVerificationCode` — build spec §6: "Test recomputes
+ *  sha256(serviceSid+':'+to)-derived 6-digit SAME as handler." Recomputed independently here
+ *  (not imported) so this capability's teeth run through `handleTwilioTwinRequest` for the actual
+ *  approve/pending assertion — only the EXPECTED VALUE is precomputed locally. */
+function expectedCodeFor(serviceSid: string, to: string): string {
+  const hex = createHash('sha256').update(`${serviceSid}:${to}`).digest('hex').slice(0, 6);
+  return String(parseInt(hex, 16) % 1_000_000).padStart(6, '0');
+}
+
+// ── API verify: drive REAL requests against a fresh temp root, then assert status/shape ──
+type Step = { m: string; p: string; b?: Record<string, string>; host?: string };
+type Body = Record<string, any>;
+
+function encodeForm(b?: Record<string, string>): string | undefined {
+  if (b === undefined) return undefined;
+  return new URLSearchParams(b).toString();
+}
+
+/** Run a sequence of real Twilio-twin requests against an isolated root; return all responses.
+ *  The callback also receives `root` itself (some verifies build signed artifacts against the
+ *  SAME root the handler used — the signing-key-match discipline fal-capabilities.ts's `withRoot`
+ *  established). Threads `host` per step (api.twilio.com/verify.twilio.com/lookups.twilio.com). */
+async function withRoot(steps: (h: (s: Step) => Promise<TwilioResponse>, root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'twilio-cap-'));
+  const h = (s: Step) =>
+    handleTwilioTwinRequest({
+      method: s.m,
+      path: s.p,
+      body: encodeForm(s.b),
+      root,
+      occurredAt: OCCURRED_AT,
+      ...(s.host ? { host: s.host } : {}),
+    });
+  try {
+    return await verifyBoundary('twilio.withRoot', () => steps(h, root));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+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' });
+
+export const TWILIO_CAPABILITIES: CapabilitySpec[] = [
+  // ── MESSAGES (send -> status progression -> get/list) ────────────────────────────────────────
+  done('twilio.messages.send', 'messages', "POST Messages.json (form-urlencoded) -> 201 (GROUNDED — twilio_api_v2010.json's own responses map documents ONLY 201 for message create) with sid/status/to/from echoed", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'hi' }, host: 'api.twilio.com' });
+      if (r.status !== 201) return false;
+      const b = r.body as Body;
+      return typeof b.sid === 'string' && /^SM[0-9a-f]{32}$/.test(b.sid) && b.status === 'queued'
+        && b.to === '+15551234567' && b.from === '+15557654321' && b.body === 'hi';
+    })),
+  done('twilio.messages.send_requires_to', 'messages', "POST Messages.json without To -> 400 {code:21604} (GROUNDED live from twilio.com/docs/api/errors/21604)", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { From: '+15557654321', Body: 'hi' }, host: 'api.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 400 && b.code === 21604;
+    })),
+  done('twilio.messages.send_invalid_to_e164', 'messages', "POST Messages.json with a non-E.164 To -> 400 {code:21211} (GROUNDED live from twilio.com/docs/api/errors/21211)", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: 'not-a-number', From: '+15557654321', Body: 'hi' }, host: 'api.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 400 && b.code === 21211;
+    })),
+  done('twilio.messages.send_rejects_non_urlencoded', 'messages', 'a JSON request body (not form-urlencoded) -> 400 vendor-shaped, never silently misparsed', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'twilio-cap-'));
+    try {
+      const r = await handleTwilioTwinRequest({ method: 'POST', path: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, body: JSON.stringify({ To: '+15551234567', From: '+15557654321', Body: 'hi' }), root, host: 'api.twilio.com', occurredAt: OCCURRED_AT });
+      const b = r.body as Body;
+      return r.status === 400 && typeof b.code === 'number' && typeof b.message === 'string';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('twilio.messages.get', 'messages', 'GET Messages/{Sid}.json round-trips the created message (sid/to/from/body match)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'roundtrip' }, host: 'api.twilio.com' });
+      const sid = (c.body as Body).sid as string;
+      const g = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sid}.json`, host: 'api.twilio.com' });
+      const b = g.body as Body;
+      return g.status === 200 && b.sid === sid && b.to === '+15551234567' && b.body === 'roundtrip';
+    })),
+  done('twilio.messages.get_unknown_404', 'messages', "GET Messages/{unknown}.json -> 404 {code:20404} (GROUNDED live from twilio.com/docs/api/errors/20404)", 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/SMdoesnotexist00000000000000000.json`, host: 'api.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 404 && b.code === 20404;
+    })),
+  done('twilio.messages.list', 'messages', "GET Messages.json list envelope is EXACTLY {end,first_page_uri,next_page_uri,page,page_size,previous_page_uri,messages} (GROUNDED byte-for-byte from twilio_api_v2010.json's own list example, not the build spec's approximate guess)", 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'a' }, host: 'api.twilio.com' });
+      await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234568', From: '+15557654321', Body: 'b' }, host: 'api.twilio.com' });
+      const l = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, host: 'api.twilio.com' });
+      const b = l.body as Body;
+      return l.status === 200 && Array.isArray(b.messages) && b.messages.length === 2
+        && typeof b.page === 'number' && typeof b.page_size === 'number' && 'first_page_uri' in b && 'next_page_uri' in b && 'previous_page_uri' in b;
+    })),
+  done('twilio.messages.status_lifecycle', 'messages', 'status polls progress EXACTLY queued(echo)->sending->sent->delivered — kernel-folded poll-count, no wall clock (dies under httpEmpty: no exact sequence to assert)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'x' }, host: 'api.twilio.com' });
+      const sid = (c.body as Body).sid as string;
+      const get = () => h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sid}.json`, host: 'api.twilio.com' });
+      const p1 = await get(); if ((p1.body as Body).status !== 'queued') return false;
+      const p2 = await get(); if ((p2.body as Body).status !== 'sending') return false;
+      const p3 = await get(); if ((p3.body as Body).status !== 'sent') return false;
+      const p4 = await get(); if ((p4.body as Body).status !== 'delivered') return false;
+      return true;
+    })),
+  done('twilio.messages.status_terminal_delivered', 'messages', 'delivered is terminal — repeated polls stay delivered, idempotent', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'x' }, host: 'api.twilio.com' });
+      const sid = (c.body as Body).sid as string;
+      const get = () => h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sid}.json`, host: 'api.twilio.com' });
+      await get(); await get(); await get(); await get(); // -> delivered
+      const again1 = await get();
+      const again2 = await get();
+      return (again1.body as Body).status === 'delivered' && (again2.body as Body).status === 'delivered';
+    })),
+  done('twilio.messages.sid_format', 'messages', 'message sid matches the real Twilio SM + 32-hex-char shape exactly', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'x' }, host: 'api.twilio.com' });
+      const sid = (c.body as Body).sid as string;
+      return typeof sid === 'string' && sid.length === 34 && /^SM[0-9a-f]{32}$/.test(sid);
+    })),
+  done('twilio.messages.isolation', 'messages', 'two independent messages: progressing one to delivered leaves the other at queued', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'a' }, host: 'api.twilio.com' });
+      const b = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'b' }, host: 'api.twilio.com' });
+      const sidA = (a.body as Body).sid as string;
+      const sidB = (b.body as Body).sid as string;
+      const getA = () => h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sidA}.json`, host: 'api.twilio.com' });
+      await getA(); await getA(); await getA(); const finalA = await getA();
+      const getB = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sidB}.json`, host: 'api.twilio.com' });
+      return (finalA.body as Body).status === 'delivered' && (getB.body as Body).status === 'queued';
+    })),
+  done('twilio.messages.direction_outbound', 'messages', "every twin-created message has direction:'outbound-api' (the real enum member a twin-originated send uses — twilio_api_v2010.json message_enum_direction)", 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'x' }, host: 'api.twilio.com' });
+      return (c.body as Body).direction === 'outbound-api';
+    })),
+  done('twilio.messages.num_segments', 'messages', 'num_segments is a STRING (GROUNDED from the live OpenAPI list example) — "1" for a short body, >1 for a body over 160 chars', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const short = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'short' }, host: 'api.twilio.com' });
+      const longBody = 'x'.repeat(200);
+      const long = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: longBody }, host: 'api.twilio.com' });
+      const shortSeg = (short.body as Body).num_segments;
+      const longSeg = (long.body as Body).num_segments;
+      return shortSeg === '1' && typeof longSeg === 'string' && Number(longSeg) > 1;
+    })),
+
+  // ── ACCOUNTS (pure per-root derivation — build spec's kernel-gotcha finding, see twilio-twin.ts header) ──
+  done('twilio.accounts.fetch', 'auth', "GET Accounts/{Sid}.json -> {sid,status:'active',auth_token,friendly_name,type} — auth_token matches the SAME deterministic per-root derivation twilio-signature.ts's signing uses (⚠ REST-home-for-signing_key modeling choice, not independently vendor-confirmed beyond the OpenAPI schema shape)", 'api', 'common', () =>
+    withRoot(async (h, root) => {
+      const r = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}.json`, host: 'api.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 200 && b.sid === ACCOUNT_SID && b.status === 'active' && typeof b.friendly_name === 'string'
+        && b.type === 'Full' && b.auth_token === await twilioAuthToken(root);
+    })),
+
+  // ── VERIFY (start -> check, twin-internal deterministic expected code) ───────────────────────
+  done('twilio.verify.start', 'verify', "POST Verifications (form-urlencoded) -> 201 (GROUNDED — twilio_verify_v2.json documents 201) with sid VE+32hex, status:'pending', valid:false", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/Verifications`, b: { To: '+15551234567', Channel: 'sms' }, host: 'verify.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 201 && typeof b.sid === 'string' && /^VE[0-9a-f]{32}$/.test(b.sid) && b.status === 'pending' && b.valid === false;
+    })),
+  done('twilio.verify.start_requires_to', 'verify', "POST Verifications without To -> 400 {code:60200} (GROUNDED live from twilio.com/docs/api/errors/60200)", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/Verifications`, b: { Channel: 'sms' }, host: 'verify.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 400 && b.code === 60200;
+    })),
+  done('twilio.verify.check_correct_approves', 'verify', 'VerificationCheck with the RIGHT (independently re-derived) code -> approved,valid:true — dies under httpEmpty (no approval to assert)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const to = '+15551234567';
+      await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/Verifications`, b: { To: to, Channel: 'sms' }, host: 'verify.twilio.com' });
+      const code = expectedCodeFor(SERVICE_SID, to);
+      const check = await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/VerificationCheck`, b: { To: to, Code: code }, host: 'verify.twilio.com' });
+      const b = check.body as Body;
+      return check.status === 200 && b.status === 'approved' && b.valid === true;
+    })),
+  done('twilio.verify.check_wrong_pending', 'verify', "VerificationCheck with a WRONG code -> {status:'pending',valid:false} (⚠ exact HTTP status modeled as 200, doc lists both 200/201 generically for this route — build spec §13.3)", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const to = '+15551234568';
+      await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/Verifications`, b: { To: to, Channel: 'sms' }, host: 'verify.twilio.com' });
+      const check = await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/VerificationCheck`, b: { To: to, Code: '000000' }, host: 'verify.twilio.com' });
+      const b = check.body as Body;
+      return check.status === 200 && b.status === 'pending' && b.valid === false;
+    })),
+  done('twilio.verify.check_unknown_404', 'verify', "VerificationCheck for a To with no pending verification -> 404 {code:20404}", 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/v2/Services/${SERVICE_SID}/VerificationCheck`, b: { To: '+19999999999', Code: '123456' }, host: 'verify.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 404 && b.code === 20404;
+    })),
+
+  // ── LOOKUP (pure deterministic derivation, no kernel row) ─────────────────────────────────────
+  done('twilio.lookup.phone_number', 'lookup', 'GET PhoneNumbers/{E164} -> {phone_number,national_format,country_code,valid:true}', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v2/PhoneNumbers/+15551234567', host: 'lookups.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 200 && b.phone_number === '+15551234567' && typeof b.national_format === 'string' && b.country_code === 'US' && b.valid === true;
+    })),
+  done('twilio.lookup.line_type_intelligence', 'lookup', '?Fields=line_type_intelligence -> {line_type_intelligence:{type,carrier_name}} — type is NESTED (kernel type/id/updatedAt gotcha does not bite; Lookup has no kernel row at all)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v2/PhoneNumbers/+15551234567?Fields=line_type_intelligence', host: 'lookups.twilio.com' });
+      const b = r.body as Body;
+      const lti = b.line_type_intelligence as Body;
+      return r.status === 200 && lti && typeof lti.type === 'string' && typeof lti.carrier_name === 'string';
+    })),
+  done('twilio.lookup.invalid_404', 'lookup', "GET PhoneNumbers/{malformed} -> 404 {code:20404} (⚠ this pack's own generic not-found envelope; the real vendor's malformed-number-specific error taxonomy was not independently confirmed beyond the generic REST 404 shape)", 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v2/PhoneNumbers/not-a-real-number', host: 'lookups.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 404 && b.code === 20404;
+    })),
+
+  // ── INCOMING PHONE NUMBERS (lazily-seeded, kernel-persisted) ──────────────────────────────────
+  done('twilio.incoming_phone_numbers.list', 'phone_numbers', 'GET IncomingPhoneNumbers.json returns the lazily-seeded numbers, each with a `type` field (kernel gotcha: renamed number_type internally, remapped to type on read — see twilio-twin.ts header)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/IncomingPhoneNumbers.json`, host: 'api.twilio.com' });
+      const b = r.body as Body;
+      if (r.status !== 200 || !Array.isArray(b.incoming_phone_numbers) || b.incoming_phone_numbers.length < 2) return false;
+      const first = b.incoming_phone_numbers[0] as Body;
+      return typeof first.phone_number === 'string' && typeof first.type === 'string' && first.number_type === undefined;
+    })),
+
+  // ── WEBHOOKS (X-Twilio-Signature: FRESH HMAC-SHA1, sign/verify/tamper + inbound builder) ─────
+  done('twilio.webhooks.status_callback_signature', 'webhooks', 'a built status-callback delivery verifies against the SAME AuthToken (pure local HMAC-SHA1 in twilio-signature.ts — ALLOW crypto, never calls the handler and never reads state)', 'api', 'core', () => {
+    const url = 'https://example.com/status-callback';
+    const built = buildSignedStatusCallback({ url, messageSid: 'SMabc', messageStatus: 'delivered', to: '+15551234567', from: '+15557654321', ...SIGNING_PAIR });
+    try {
+      verifyTwilioSignature(url, built.params, built.headers['x-twilio-signature']!, SIGNING_PAIR.authToken);
+      return true;
+    } catch (err) {
+      if (isInfrastructureError(err)) throw harnessError('twilio.webhooks.status_callback_signature', err);
+      return false;
+    }
+  }),
+  done('twilio.webhooks.signature_tamper', 'webhooks', 'flipping one signed param (or the signature itself) is REJECTED by verifyTwilioSignature (pure crypto tamper-reject — ALLOW, never calls the handler)', 'api', 'core', () => {
+    const url = 'https://example.com/status-callback';
+    const built = buildSignedStatusCallback({ url, messageSid: 'SMabc', messageStatus: 'delivered', to: '+15551234567', from: '+15557654321', ...SIGNING_PAIR });
+    const tamperedParams = { ...built.params, To: '+19999999999' };
+    try {
+      verifyTwilioSignature(url, tamperedParams, built.headers['x-twilio-signature']!, SIGNING_PAIR.authToken);
+      return false; // must have thrown
+    } catch (err) {
+      return err instanceof TwilioSignatureVerificationError;
+    }
+  }),
+  done('twilio.webhooks.inbound_message_shape', 'webhooks', 'buildSignedInboundMessage produces a signed {MessageSid,From,To,Body} delivery whose signature verifies (pure builder — ALLOW, never calls the handler)', 'api', 'common', () => {
+    const url = 'https://example.com/sms-inbound';
+    const built = buildSignedInboundMessage({ url, from: '+15551234567', to: '+15557654321', body: 'inbound hi', ...SIGNING_PAIR });
+    if (built.params.From !== '+15551234567' || built.params.To !== '+15557654321' || built.params.Body !== 'inbound hi' || typeof built.params.MessageSid !== 'string') return false;
+    try {
+      verifyTwilioSignature(url, built.params, built.headers['x-twilio-signature']!, SIGNING_PAIR.authToken);
+      return true;
+    } catch (err) {
+      if (isInfrastructureError(err)) throw harnessError('twilio.webhooks.inbound_message_shape', err);
+      return false;
+    }
+  }),
+
+  // ── ERRORS ────────────────────────────────────────────────────────────────────────────────
+  done('twilio.errors.envelope_shape', 'errors', "every error response is EXACTLY {code,message,more_info,status} (Twilio's own documented envelope — NOT fal's {detail})", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { From: '+15557654321', Body: 'x' }, host: 'api.twilio.com' });
+      const b = r.body as Body;
+      const keys = Object.keys(b).sort();
+      return JSON.stringify(keys) === JSON.stringify(['code', 'message', 'more_info', 'status']) && b.status === 400;
+    })),
+
+  // ── SAFETY / HONESTY ─────────────────────────────────────────────────────────────────────
+  done('twilio.read_only.rejects_writes', 'safety', 'readOnly mode rejects writes with 405 but allows GET', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'twilio-ro-'));
+    try {
+      const w = await handleTwilioTwinRequest({ method: 'POST', path: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, body: 'To=%2B15551234567&From=%2B15557654321&Body=x', root, readOnly: true, host: 'api.twilio.com', occurredAt: OCCURRED_AT });
+      const g = await handleTwilioTwinRequest({ method: 'GET', path: `/2010-04-01/Accounts/${ACCOUNT_SID}.json`, root, readOnly: true, host: 'api.twilio.com', occurredAt: OCCURRED_AT });
+      return w.status === 405 && g.status === 200;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('twilio.unmodeled_route.404', 'safety', "an unmodeled route returns Twilio's own {code,message,more_info,status} 404 envelope (never a fabricated success)", 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/some/totally/unknown/route', host: 'api.twilio.com' });
+      const b = r.body as Body;
+      return r.status === 404 && typeof b.code === 'number' && typeof b.message === 'string';
+    })),
+  done('twilio.state.kernel_persisted', 'state', 'state is kernel-folded — a message created in one call is visible (by sid) in the next', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`, b: { To: '+15551234567', From: '+15557654321', Body: 'x' }, host: 'api.twilio.com' });
+      const sid = (c.body as Body).sid;
+      if (typeof sid !== 'string' || sid.length === 0) return false;
+      const g = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sid}.json`, host: 'api.twilio.com' });
+      return g.status === 200 && (g.body as Body).sid === sid;
+    })),
+
+  // ── CONFORMANCE / CONNECTOR ──────────────────────────────────────────────────────────────
+  done('twilio.conformance.snapshot', 'conformance', 'conformance snapshot covers all 4 resource types + the core messages/verify/lookup contracts (ALLOW static — reads twilioTwinSnapshot(), never calls the handler)', 'api', 'common', () => {
+    const report = checkTwilioConformance();
+    return report.ok && report.endpointsChecked >= 10 && report.resourceTypesChecked === 4;
+  }),
+  done('twilio.connector.sync.entrypoint', 'connector', 'syncTwilioFromReal LIST-pulls real Messages (client.messages.list() — a genuine vendor list endpoint, unlike fal); idempotent re-pull; read-through-handler', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'twilio-conn-'));
+    try {
+      const client: TwilioLikeClient = {
+        messages: {
+          list: async () => [{ sid: 'SM' + '1'.repeat(32), to: '+15551234567', from: '+15557654321', body: 'real pulled message', status: 'delivered', direction: 'outbound-api', numSegments: '1', numMedia: '0' }],
+        },
+      };
+      const first = await syncTwilioFromReal(client, { root, occurredAt: OCCURRED_AT, budgetOptions: { root } });
+      if (first.observed !== 1 || first.deltasAppended < 1) return false;
+      const second = await syncTwilioFromReal(client, { root, occurredAt: OCCURRED_AT, budgetOptions: { root } });
+      if (second.deltasAppended !== 0) return false;
+      const r = await handleTwilioTwinRequest({ method: 'GET', path: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/SM${'1'.repeat(32)}.json`, root, host: 'api.twilio.com', occurredAt: OCCURRED_AT });
+      return r.status === 200 && (r.body as Body).body === 'real pulled message';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('twilio.connector.empty_client', 'connector', 'syncTwilioFromReal with no client.messages observes nothing', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'twilio-conn-empty-'));
+    try {
+      const result = await syncTwilioFromReal({}, { root, occurredAt: OCCURRED_AT, budgetOptions: { root } });
+      return result.observed === 0 && result.deltasAppended === 0;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  // ── TODO: the rest of the Twilio v1 surface (honest denominator) ────────────────────────────
+  todo('twilio.messages.mms_media', 'messages', 'MMS MediaUrl attachments (send + Media subresource fetch)', 'api', 'common'),
+  todo('twilio.messages.messaging_service_sid', 'messages', 'sending via a MessagingServiceSid (sender-pool routing) instead of an explicit From', 'api', 'common'),
+  todo('twilio.messages.scheduled_send', 'messages', 'SendAt / schedule_type:fixed scheduled sends + the scheduled status', 'api', 'niche'),
+  todo('twilio.messages.delete', 'messages', 'DELETE Messages/{Sid}.json', 'api', 'common'),
+  todo('twilio.messages.redact', 'messages', 'POST Messages/{Sid}.json Body="" redaction', 'api', 'niche'),
+  todo('twilio.messages.pagination_cursor', 'pagination', 'real cursor-based pagination (PageToken / next_page_uri actually fetchable) beyond a single-page list', 'api', 'common'),
+  todo('twilio.messages.status_callback_delivery', 'messages', 'an injected offline deliverer actually POSTs the signed status-callback to the registered StatusCallback URL on each status transition (⚠ delivery timing/retry policy unconfirmed)', 'api', 'common'),
+  todo('twilio.messaging.services', 'messaging', 'Messaging Services (sender pools, sticky sender) CRUD', 'api', 'common'),
+  todo('twilio.messaging.copilot', 'messaging', 'Messaging Copilot / Advanced Opt-Out features', 'api', 'niche'),
+  todo('twilio.messaging.short_codes', 'messaging', 'short code provisioning/management', 'api', 'niche'),
+  todo('twilio.messaging.senders', 'messaging', 'sender (phone number / short code / alphanumeric) pool management', 'api', 'niche'),
+  todo('twilio.voice.calls', 'voice', 'Calls resource (voice call create/status)', 'api', 'common'),
+  todo('twilio.voice.twiml', 'voice', 'TwiML document generation/execution', 'api', 'common'),
+  todo('twilio.conversations.create', 'messaging', 'Conversations API (multi-channel conversation threads)', 'api', 'niche'),
+  todo('twilio.verify.channel_email', 'verify', "Verify email channel (Channel:'email')", 'api', 'common'),
+  todo('twilio.verify.channel_whatsapp', 'verify', "Verify WhatsApp channel (Channel:'whatsapp')", 'api', 'common'),
+  todo('twilio.verify.channel_call', 'verify', "Verify voice-call channel (Channel:'call')", 'api', 'niche'),
+  todo('twilio.verify.max_attempts', 'verify', "the real max-check-attempts 404 {code:60202} path (⚠ GROUNDED message text 'Max check attempts reached' from twilio.com/docs/api/errors/60202, but the attempt-count trigger itself is unmodeled)", 'api', 'common'),
+  todo('twilio.verify.rate_limit', 'verify', 'Verify RateLimits resource / 429 rate-limiting', 'api', 'niche'),
+  todo('twilio.verify.fraud_guard', 'verify', 'Verify Fraud Guard / RiskCheck', 'api', 'niche'),
+  todo('twilio.lookup.carrier_live', 'lookup', 'a LIVE (non-deterministic-derivation) carrier lookup against a real carrier database', 'api', 'niche'),
+  todo('twilio.lookup.caller_name', 'lookup', 'CNAM caller-name lookup (?Fields=caller_name)', 'api', 'common'),
+  todo('twilio.lookup.sim_swap', 'lookup', 'SIM swap detection (?Fields=sim_swap)', 'api', 'niche'),
+  todo('twilio.lookup.reassigned_number', 'lookup', 'reassigned number detection (?Fields=reassigned_number)', 'api', 'niche'),
+  todo('twilio.incoming_phone_numbers.provision', 'phone_numbers', 'POST IncomingPhoneNumbers.json (real provisioning of a new number)', 'api', 'common'),
+  todo('twilio.incoming_phone_numbers.update', 'phone_numbers', 'POST IncomingPhoneNumbers/{Sid}.json (update SmsUrl/VoiceUrl/etc.)', 'api', 'common'),
+  todo('twilio.accounts.subaccounts', 'auth', 'sub-account creation/management', 'api', 'niche'),
+  todo('twilio.usage.records', 'auth', 'Usage Records (billing/usage-tracking resource)', 'api', 'niche'),
+  todo('twilio.regulatory.bundles', 'phone_numbers', 'Regulatory Compliance Bundles (number provisioning compliance)', 'api', 'niche'),
+  todo('twilio.errors.code_catalog', 'errors', 'the full Twilio error-code catalog (this pack grounds 6 codes live; ~thousands exist)', 'api', 'niche'),
+  todo('twilio.webhooks.status_callback_retry', 'webhooks', 'status-callback delivery retry policy on a non-2xx response', 'api', 'niche'),
+  todo('twilio.webhooks.fallback_url', 'webhooks', 'SmsFallbackUrl / StatusCallback fallback-on-error routing', 'api', 'niche'),
+  todo('twilio.auth.basic_401_parity', 'auth', 'missing/invalid HTTP Basic (AccountSid:AuthToken) -> 401 parity (⚠ GROUNDED message text "Permission Denied", code 20003, from twilio.com/docs/api/errors/20003 — not yet enforced by the handler)', 'api', 'common'),
+  todo('twilio.auth.api_key_auth', 'auth', 'API Key/Secret (SK.../secret) auth as an alternative to AccountSid/AuthToken', 'api', 'niche'),
+  todo('twilio.connector.push', 'connector', 'push a locally-created message/verification against a real Twilio account', 'connector', 'common'),
+  todo('twilio.connector.pull_verifications', 'connector', 'pull verifications from a real account (⚠ Verify v2 has NO bulk list-verifications endpoint per the live-fetched OpenAPI document — would need caller-supplied handles, mirroring fal\'s handle-driven pull; mapVerification exists and is ready)', 'connector', 'common'),
+  todo('twilio.fixtures.seed', 'connector', 'seed a small library of realistic message/verification fixtures beyond the 2 lazily-seeded phone numbers', 'connector', 'niche'),
+];
+
+export const TWILIO_AREAS = [
+  'messages', 'verify', 'lookup', 'phone_numbers', 'messaging', 'voice', 'webhooks', 'auth',
+  'pagination', 'errors', 'connector', 'conformance', 'safety', 'state',
+] as const;
+
+export async function twilioCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('twilio', TWILIO_CAPABILITIES);
+}

package/src/twilio-conformance.ts

@@ -0,0 +1,45 @@
+// Twilio conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+// Checks the twin's endpoint/resource inventory against itself — SELF-REFERENTIAL, the same
+// pattern fal/replicate/elevenlabs/polar use (docs/contributing/conformance.md's "2 spec" discussion): it does not
+// diff against a captured vendor document, it asserts the pack's own declared snapshot is
+// internally consistent (every resource type has a route, the core surface routes exist).
+import { twilioTwinSnapshot, TWILIO_RESOURCE_TYPES } from './twilio-twin.ts';
+
+export type TwilioConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+export function checkTwilioConformance(): TwilioConformanceReport {
+  const snapshot = twilioTwinSnapshot();
+  const violations: string[] = [];
+  // Every declared resource type must have at least one implemented endpoint touching it.
+  // `signing_key` has no REST path of its own — it's served (purely derived, per-root) at the
+  // Accounts fetch endpoint, so it maps to the 'Accounts' stem instead of its own name (build
+  // spec §4).
+  const stemFor: Record<string, string> = {
+    message: '/Messages',
+    verification: '/Verifications',
+    phone_number: '/IncomingPhoneNumbers',
+    signing_key: '/Accounts',
+  };
+  for (const type of TWILIO_RESOURCE_TYPES) {
+    const stem = stemFor[type];
+    if (!stem || !snapshot.implementedEndpoints.some((e) => e.includes(stem))) {
+      violations.push(`resource type '${type}' has no implemented endpoint`);
+    }
+  }
+  // The core messaging/verify/lookup endpoints must be present in the protocol surface.
+  if (!snapshot.implementedEndpoints.some((e) => e.startsWith('POST api.twilio.com') && e.includes('Messages.json'))) violations.push('missing message send endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e.startsWith('POST verify.twilio.com') && e.includes('Verifications'))) violations.push('missing verify start endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e.includes('VerificationCheck'))) violations.push('missing verify check endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e.startsWith('GET lookups.twilio.com'))) violations.push('missing lookup endpoint');
+  return {
+    ok: violations.length === 0,
+    endpointsChecked: snapshot.implementedEndpoints.length,
+    resourceTypesChecked: snapshot.resourceTypes.length,
+    violations,
+  };
+}