What compatibility-as-discipline looks like under a merge gate

What we did

We cloned github.com/twilio/twilio-oai and extracted spec/json/twilio_api_v2010.json at two points: the most recent regeneration at the time of analysis (commit d50069b4, 2026-04-14) and a baseline 55 days earlier (commit 67e9f3aa, 2026-02-18). Two intermediate regenerations landed in the window on 2026-03-10 and 2026-03-24; the gate compares endpoints, not the path through them, so the reported diff is the cumulative delta against the baseline. Each spec is roughly 1.8 MB of JSON and declares 121 paths, 197 operations, and 148 component schemas. We ran delimit lint in its standard configuration, with no policy overrides. The diff engine classified each change against its 27-type taxonomy. The semver classifier walked the breaking-vs-non-breaking partition and produced a bump recommendation. Everything below is mechanical output, annotated.

This is the smallest change set in the cadence so far. Twilio v2010 is the canonical Voice / SMS / Messaging surface, the reference for telephony API stability, and a public spec held tightly enough that 55 days and three regenerations produced four additive enum values and nothing else on the wire. The story is in what did not change.

Headline numbers

The path count is identical: 121 on both ends. The operation count is identical: 197 on both ends. The component schema count is identical: 148 on both ends. The change volume is four additive enum values on a single field, all variants of an existing capture-type vocabulary, all gated in client code by a separate opt-in option. The gate's independent semver classification is minor. The advertised info.version did not change because Twilio v2010 carries its real version in the path prefix. There is no asymmetry to flag here, which is its own kind of finding: an active public surface ran 55 days under a two-week regeneration cadence with zero breaking changes, and the attestation is the proof.

Findings

0 breaking, 2 additive, 1 flagged as spec hygiene. Each finding cites the exact change-type from the 27-type taxonomy, the surface affected, and the consumer impact. The hygiene finding here is a description-text shift the engine does not gate on; we surface it so the reader sees the full delta, not just the wire-shape delta.

1. additivefinding F1
   change type: enum_value_added (4 values, single field)
   surface: #/components/schemas/payments_enum_capture (used by /2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{Sid}.json)

   Four new string values landed on the payments_enum_capture field: payment-card-number-matcher, expiration-date-matcher, security-code-matcher, and postal-code-matcher. The field controls which piece of payment information the Pay TwiML verb prompts the caller to enter during a PCI-compliant capture flow. The new -matcher variants pair with the existing RequireMatchingInputs option to support input-confirmation prompts (caller enters a value twice, the IVR confirms the two readings agree before submission). The original six values payment-card-number, expiration-date, security-code, postal-code, bank-routing-number, and bank-account-number are all preserved exactly. This is the textbook shape of a compatible enum extension: existing clients keep working, new clients can opt into the new values, no field semantics shift underneath.

2. additivefinding F2
   change type: no schema changes outside the enum extension above
   surface: spec-wide (paths, operations, components.schemas)

   The path count is 121 on both ends. The operation count is 197 on both ends (every method on every path preserved). The component schema count is 148 on both ends. Three intermediate librarian regenerations landed in the window (2026-03-10, 2026-03-24, and the 2026-04-14 HEAD), and the cumulative diff against the 2026-02-18 baseline is the four enum values above and nothing else. The advertised info.version field is 1.0.0 on both ends, which is Twilio v2010 convention and not a versioning failure: the real Twilio API version is the path prefix /2010-04-01, frozen since 2010, and individual surface evolution rides additive enum and field expansion within that prefix.

3. spec hygienefinding C1
   change type: description_changed (documentation drift, not flagged by lint)
   surface: #/components/schemas/payments_enum_capture.description

   The description text on the same enum field expanded from a flat list of the six original values to a list plus a clause referencing the new -matcher variants and the RequireMatchingInputs option. The change-type taxonomy treats description text as out of scope for breaking-change classification because description is a documentation surface, not a wire-shape surface. We surface this as a hygiene observation so a careful reader can see the documentation moved with the enum, not lag it. The point of an attestation is making the full delta legible, including the parts the engine deliberately does not gate on.

What this report is not

Not a defect claim. Not a security advisory. Not a judgment of the Twilio team's release process. Twilio v2010 is the long-running reference for telephony API stability; the four enum values added in this window are a textbook compatible extension of an existing capture-type vocabulary on the Pay TwiML verb. The merge gate shipped a clean pass and a minor-class semver recommendation, and both reflect the actual shape of the diff.

The findings above do not say Twilio did anything wrong, and they do not say Twilio did anything special either. They say: here is exactly which four enum values landed in 55 days, here is the field and the calling endpoint they ride on, here is the opt-in option that gates their effect on existing flows, and here is what stayed identical (197 operations, 148 schemas, every existing enum value on the field preserved). That visibility is the artifact. A downstream consumer who reads this attestation knows their pinned client will keep working without re-running the analysis, and an auditor knows exactly what shipped without taking anyone's word for it.

The attestation artifact

A Delimit attestation is a bounded evidence record at a single commit pair. The same Delimit version run against the same two commits produces the same bytes; that is the replayable property. The attestation does not opine on whether a change should have shipped, only on what shipped and how the change-type taxonomy classifies it. A pass is as much an artifact as a fail; both are evidence that survives the moment.

For the precise list of checks, the explicit out-of-scope list, and the reproducibility guarantee, see the attestation methodology v1. This report is the OpenAPI-diff surface of the same primitive that powers the merge gate for AI-written code.

Reproduce locally

Anyone can re-run the analysis above against the same two commits and verify the same diff comes out. The full command sequence:

# Install the CLI
npm install -g delimit-cli

# Clone the repo (full history; we walk back ~55 days)
git clone https://github.com/twilio/twilio-oai
cd twilio-oai

# Extract the two specs at the cited commits
git show 67e9f3aa:spec/json/twilio_api_v2010.json > /tmp/old.json
git show d50069b4:spec/json/twilio_api_v2010.json > /tmp/new.json

# Run the merge gate
delimit lint /tmp/old.json /tmp/new.json

If the bytes you get differ from the bytes in this report, that is itself a finding worth reporting; raise it on the Delimit repo and we will look. Each spec is roughly 1.8 MB; the lint pass completes in well under one second on a standard laptop.