RFC: Pact MkII — a ground-up redesign of the Pact framework

[rholshausen]

This RFC is a thought experiment made concrete: if we designed Pact from scratch today, what would we keep, change, and throw away? It proposes Pact MkII (working title), built on five pillars:

1. One core, thin SDKs — a single reference engine behind a coarse-grained, versioned protocol (WASM component / subprocess / minimal C ABI embeddings), replacing the lock-step pact-jvm + pact-reference implementations and the fine-grained C FFI.
2. Declarative interactions, compiled plans — DSLs produce declarative interaction specs; the engine compiles them to inspectable matching plans (pact explain), building on the v2 matching engine prototyped in pact-reference.
3. Everything is a component — transports, content handlers, matchers, generators and hooks all implement the same interfaces, including the built-in ones; plugins stop being a bolt-on.
4. Shapes with honest optionality — optional, oneOf, anyOf and cardinality, made safe by variant testing (every declared variation is actually exercised and replayed), plus provider-published shapes with a subsumption check to catch response variance the consumer never declared.
5. Scriptable lifecycle — named hook points (auth injection, state setup, message production) with declarative config first and scripts as the escape hatch.

The consumer-driven workflow, the pact file as artifact, and the broker/can-i-deploy workflow are all retained. v1–v4 pact files remain verifiable and a pact upgrade tool is proposed. Deterministic verification remains the foundation; AI assistance (SDK maintenance, mismatch diagnosis, agentic orchestration) is strictly optional.

Backwards compatibility is explicitly not a constraint for this exercise, though a migration path is sketched. Feedback is welcome on any part, but the unresolved questions section lists the areas where community input would help most: naming/versioning, the day-one scope of the component model, variant sampling defaults, and subsumption policy.

🤖 Generated with Claude Code

[YOU54F]

good read, will take some time to mull over. sounds really promising

[rholshausen]

good read, will take some time to mull over. sounds really promising

Even Claude agrees:

[rholshausen]

One thing to note, I have been getting Claude to run a number of spikes to test some design ideas, and one of the things that was flagged is this RFC is still very HTTP centric, and will need to be rewritten. TLDR is that HTTP becomes a more specific interaction, interaction responses become optional and polled, and a message fire and forget is just an interaction that no response defined.

The verdict: the RFC's transport interface survives async messaging — but only after restating it, and the restatement is the finding.

The problem with the RFC's wording: "start/stop a mock endpoint; drive requests at a provider" is HTTP-accented — "mock endpoint" presumes serving, "drive requests" presumes a response exists. Taken literally, both break on messaging.

The restatement that works — four role-neutral primitives:

• start(options) -> endpoint-descriptor (an open document, not a URL — host/port for HTTP, broker/topics for messages) / stop()
• send(parts, await-reply?) — outbound, with the reply half optional
• poll-inbound(timeout) -> (event-id, parts)? — arrived traffic on the transport's schedule
• reply(event-id, parts) — complete an inbound event that has a reply half