Contract Testing Is the Breaking Change Your Agent Pipeline Ships Blind

Every agent pipeline has the same fragile assumption: the skills it depends on will keep their API contracts stable. No field will disappear. No type will narrow. No required property will materialize without warning. And when that assumption breaks — it breaks at runtime, in production, with no clear error message and no obvious rollback path.

The skill publisher added a required field. Or renamed an enum value. Or changed a nested object structure. The pipeline that worked yesterday now fails silently, returns partial data, or throws cryptic JSON parsing errors four steps deep.

This is a solved problem in traditional API development. Contract testing catches breaking changes before they ship. The gap is that no agent marketplace has ever offered it as a primitive.

Until now.

The Three Contract Testing Primitives

1. Breaking Change Detector ($0.002/call)

Compare any two API schema versions and get a classified list of every difference:

• Breaking: removed fields, narrowed types, tightened enums, new required properties, changed response status codes, removed endpoints
• Non-breaking: new optional fields, widened types, expanded enums, added endpoints
• Informational: description changes, example updates, metadata modifications

Each breaking change comes with a severity score, estimated consumer impact, and a suggested deprecation-first migration path. The detector runs in under 100ms and supports OpenAPI 3.x, JSON Schema draft-2020-12, and raw input/output schema pairs.

The CI gate use case: wire the detector into your release pipeline. If a version bump introduces breaking changes without a major version increment, the build fails. No human review needed for the obvious cases.

POST /api/v1/invoke/breaking-change-detector
{
  "baseSchema": { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "required": ["name"] },
  "headSchema": { "type": "object", "properties": { "fullName": { "type": "string" }, "age": { "type": "string" } }, "required": ["fullName", "age"] },
  "strictMode": true
}

// Returns:
// verdict: "breaking"
// breakingChanges: [
//   { path: "$.properties.name", changeType: "removed-field", severity: "critical" },
//   { path: "$.properties.age", changeType: "narrowed-type", severity: "high" },
//   { path: "$.required", changeType: "new-required", severity: "high" }
// ]
// summary: { suggestedVersionBump: "major" }

2. Backward Compatibility Verifier ($0.003/call)

Static diffing catches structural breaks. But not every structural change actually breaks consumers — and some structurally-compatible changes break specific callers who depend on undocumented behavior.

The verifier goes deeper:

• Structural subtyping: validates covariant outputs (new version can return more, not less) and contravariant inputs (new version can accept more, not less)
• Consumer profiles: named sets of fields and behaviors a specific caller depends on, so you verify compatibility per consumer instead of globally
• Synthetic request replay: generates requests from the base schema and validates they produce valid responses under the head schema

One pipeline depends on a field that another ignores. The verifier tells you which consumers break and which are safe — so you can upgrade the safe ones immediately and plan migration for the rest.

3. Contract Migration Planner ($0.004/call)

When breaking changes are intentional — a necessary schema redesign, a deprecated field removal, a response format overhaul — the planner generates a structured upgrade path:

• Per-consumer adapter code in TypeScript, Python, JSONata, or JMESPath that translates between old and new schemas
• Ordered migration steps with rollback checkpoints at each stage
• Parallel-run verification criteria for validating old and new versions produce equivalent results
• Deprecation timeline with announcement, migration, and sunset milestones

The planner analyzes BluePages composition records to map affected downstream pipelines, so the migration plan covers consumers you might not know about.

What This Costs

For a team managing 5 agent pipelines with weekly skill updates:

Total: ~$0.20/month for full contract safety across 5 pipelines. Compare that to a single production incident from an undetected breaking change.

Where Contract Testing Fits in the Pipeline Lifecycle

Contract testing sits between publishing and deployment — the verification layer that ensures schema evolution doesn't cascade into pipeline failures:

1. Publish: publisher bumps a skill version (uses BluePages PUT /api/v1/skills/:slug with new version)
2. Detect: breaking change detector runs against the version history (GET /api/v1/skills/:slug/versions)
3. Verify: backward compatibility verifier checks each known consumer profile
4. Plan: if breaks are intentional, migration planner generates per-consumer upgrade paths
5. Deploy: consumers adopt the new version with generated adapters

This composes naturally with existing BluePages primitives:

• SyntaxGuard.dev validates input schemas at runtime; contract testing validates schema evolution at release time
• PipelineGuard.dev runs pre-flight health checks; contract testing prevents the health checks from passing against a silently incompatible version
• APIHealthScore.dev grades endpoint quality; contract testing ensures that quality grade doesn't regress across versions
• WorkflowTemplate.dev generates pipeline compositions; contract testing verifies those compositions survive upstream version bumps

The Composability Loop

Contract testing creates a feedback loop with version management:

1. Publisher updates a skill with PUT /api/v1/skills/:slug and bumps the version
2. The version is recorded in SkillVersionHistory with a schema snapshot
3. Breaking change detector compares the new schema against the previous version
4. If breaking changes exist, the version history records them and consumers are notified
5. Migration planner generates adapters that consumers can apply without modifying their pipeline logic

This is the missing piece between BluePages' existing version pinning (freeze a known-good version) and version tracking (see what changed) — the automated verification that the change is safe before any consumer adopts it.

ContractTest.dev

ContractTest.dev is the newest publisher on BluePages, focused on API contract testing and backward compatibility verification for agent pipelines. Three skills, all designed to compose with existing pipeline infrastructure:

• Breaking Change Detector — schema diff with classified breaking changes ($0.002/call)
• Backward Compatibility Verifier — consumer-driven compatibility verification ($0.003/call)
• Contract Migration Planner — automated upgrade paths with adapter generation ($0.004/call)

Browse the Contract Testing & Compatibility collection to see all three skills in context.