Skip to content
ContractSpec
Start here

Core guide · Start · 3 min read

Adopt ContractSpec in an existing codebase

Wrap one behavior you already own, preserve its observable behavior, and expand from evidence.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Select a small adoption seam

Choose a function or endpoint that already has a clear owner and useful tests. Prefer a contained read or a reversible local action for your first exercise. A workflow that spans several providers, jobs and billing decisions makes it difficult to tell whether a problem comes from your application or the integration.

Write down the behavior callers depend on before changing the boundary: accepted inputs, returned data, error cases, authorization and externally visible effects. This is your compatibility checklist.

1 / 4

0 points in your packet

Select a small adoption seam

Choose a function or endpoint that already has a clear owner and useful tests. Prefer a contained read or a reversible local action for your first exercise. A workflow that spans several providers, jobs and billing decisions makes it difficult to tell whether a problem comes from your application or the integration.

Write down the behavior callers depend on before changing the boundary: accepted inputs, returned data, error cases, authorization and externally visible effects. This is your compatibility checklist.

Existing concernContractSpec responsibilityApplication responsibility
Request shapeDescribe and validate the operation inputMap the existing request into that shape
Business logicBind the operation to a handlerKeep the implementation and domain invariants
Identity and permissionsCarry requirements and decision contextAuthenticate the caller and provide trusted policy decisions
HTTP behaviorProject through a chosen adapterPreserve intended routes, status semantics and clients

Wrap the implementation before replacing it

Define a contract that reflects the behavior you intend to support. Bind the existing service function through a small handler rather than moving the entire service into the contract declaration. Make input and output translations explicit.

Register the exact contract version and attach the handler to that registration. A declaration without a bound handler is discoverable information, not a runnable operation. Keep database clients and provider secrets in host-owned code.

Compare at the boundary

Run the same representative requests against the old boundary and the new one in a disposable environment. Compare meaningful values and failures rather than incidental timestamps. Include a denied or malformed request and prove it cannot invoke the protected effect.

When transport names or response envelopes change, treat the difference as an API change. Add a deliberate compatibility mapping or update consumers together; do not assume shared types preserve a wire protocol.

Expand when the first seam pays off

A useful next step is a second interface to the same registered behavior, such as a human form and an MCP tool. You can then see which rules stopped being duplicated and which responsibilities remain in the host.

Importer output can help inventory a larger system, but inferred contracts still need review. Existing code can reveal shape and routing while missing the business reason for a policy or the scope of an approval. Make those decisions explicit before expanding.

Choose an evaluation that can teach you something.

Keep the existing application. Make one operation explicit, then decide what the next useful proof would be.

Which situation sounds closest?

A CONCRETE SITUATION

Start with behavior you can compare.

An existing account lookup already returns a useful result to an API consumer.

What changes

The operation gains an explicit input, result, errors and ownership boundary.

What stays explicit

Its business implementation can remain in place.

Follow the consequence

Compare the current route with the new binding using the same valid and invalid cases. Widen the scope only after the difference is understood.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.