@volter/twin-twilio 0.1.0

package/dist/src/twilio-capabilities.js

@@ -0,0 +1,414 @@
+// 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, verifyBoundary, isInfrastructureError, harnessError } from '@volter/world-tooling';
+import { handleTwilioTwinRequest } from "./twilio-twin.js";
+import { checkTwilioConformance } from "./twilio-conformance.js";
+import { syncTwilioFromReal } from "./twilio-connector.js";
+import { verifyTwilioSignature, buildSignedStatusCallback, buildSignedInboundMessage, TwilioSignatureVerificationError, } from "./twilio-signature.js";
+import { twilioAuthToken } from "./twilio-credentials.js";
+// (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, 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 encodeForm(b) {
+    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) {
+    const root = mkdtempSync(join(tmpdir(), 'twilio-cap-'));
+    const h = (s) => 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, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const TWILIO_CAPABILITIES = [
+    // ── 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;
+        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;
+        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;
+        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;
+            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.sid;
+        const g = await h({ m: 'GET', p: `/2010-04-01/Accounts/${ACCOUNT_SID}/Messages/${sid}.json`, host: 'api.twilio.com' });
+        const b = g.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;
+        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;
+        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.sid;
+        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.status !== 'queued')
+            return false;
+        const p2 = await get();
+        if (p2.body.status !== 'sending')
+            return false;
+        const p3 = await get();
+        if (p3.body.status !== 'sent')
+            return false;
+        const p4 = await get();
+        if (p4.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.sid;
+        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.status === 'delivered' && again2.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.sid;
+        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.sid;
+        const sidB = b.body.sid;
+        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.status === 'delivered' && getB.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.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.num_segments;
+        const longSeg = long.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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        const lti = b.line_type_intelligence;
+        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;
+        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;
+        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];
+        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;
+        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;
+        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.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.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 = {
+                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.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',
+];
+export async function twilioCapabilities() {
+    return checkCapabilities('twilio', TWILIO_CAPABILITIES);
+}

package/dist/src/twilio-conformance.d.ts

@@ -0,0 +1,7 @@
+export type TwilioConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkTwilioConformance(): TwilioConformanceReport;

package/dist/src/twilio-conformance.js

@@ -0,0 +1,41 @@
+// 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.js";
+export function checkTwilioConformance() {
+    const snapshot = twilioTwinSnapshot();
+    const violations = [];
+    // 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 = {
+        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,
+    };
+}

package/dist/src/twilio-connector.d.ts

@@ -0,0 +1,60 @@
+import type { SyncResource } from '@volter/world-core';
+import { type TwilioBudgetedOptions } from './twilio-budget.js';
+export type { TwilioBudgetedOptions };
+export type TwilioRealMessage = {
+    sid: string;
+    to: string;
+    from: string;
+    body: string;
+    status: string;
+    direction?: string;
+    numSegments?: string;
+    numMedia?: string;
+    dateCreated?: string | null;
+    dateSent?: string | null;
+    errorCode?: number | null;
+    errorMessage?: string | null;
+    accountSid?: string | null;
+};
+export type TwilioRealVerification = {
+    sid: string;
+    serviceSid: string;
+    to: string;
+    channel: string;
+    status: string;
+    valid: boolean;
+    dateCreated?: string | null;
+    dateUpdated?: string | null;
+};
+export interface TwilioLikeClient {
+    messages?: {
+        list: (opts?: {
+            limit?: number;
+        }) => Promise<TwilioRealMessage[]>;
+    };
+}
+/** Pure mapper (real Message -> SyncResource) — never touches a client, so the mutation-test
+ *  connector-seam sweep (which sabotages every export matching the sync-or-push-or-pull-or-
+ *  fullSync naming convention) leaves this real, per the pack convention (replicate-connector.ts's
+ *  `mapModel` / fal-connector.ts's `mapQueueRequest`). */
+export declare function mapMessage(m: TwilioRealMessage): SyncResource;
+/** Pure mapper (real Verification -> SyncResource). Not wired into `syncTwilioFromReal` today —
+ *  see header (`twilio.connector.pull_verifications` is `todo`; Verify v2 has no list-all
+ *  endpoint to pull from without caller-supplied handles). */
+export declare function mapVerification(v: TwilioRealVerification): SyncResource;
+/** Pull real Messages via the injected client's `messages.list()` (list-driven — a genuine
+ *  Twilio REST list endpoint, unlike fal's handle-only queue). An absent `client.messages`
+ *  observes nothing. */
+export declare function pullTwilioMessages(rawClient: TwilioLikeClient, opts?: TwilioBudgetedOptions): Promise<SyncResource[]>;
+/**
+ * D7 entry point: pull the CURRENT real Messages list and fold it into the twin via ONE
+ * `syncPull` (shadow-diff dedup). Returns `{observed, deltasAppended}` — a re-pull of identical
+ * state appends ZERO deltas.
+ */
+export declare function syncTwilioFromReal(rawClient: TwilioLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+} & TwilioBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;