Skip to content
ContractSpec
Start here

Core ContractSpec

Learn the common model.

These guides explain the foundation shared by the packages and capabilities across the system.

Start with one shared behavior

Choose a small operation, understand its boundaries, and decide what to adopt next.

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

Choose a behavior that already matters

Start with an action or query that more than one part of your product needs: submitting a request from a form, fetching the same account data through an API, or letting an agent request a reviewed export. A useful first operation has a clear input, an observable result and an existing owner.

The first milestone is modest: one definition that you can inspect, one implementation you understand, and one boundary you can test. You can keep your application, database and deployment process while evaluating that seam.

  • Pick an operation small enough to explain in a few sentences.
  • Write down one successful request and one request that must fail.
  • Identify the existing business handler and the source of identity.
  • Choose one interface first; add a second when the first is understood.

1 / 4

0 points in your packet

Choose a behavior that already matters

Start with an action or query that more than one part of your product needs: submitting a request from a form, fetching the same account data through an API, or letting an agent request a reviewed export. A useful first operation has a clear input, an observable result and an existing owner.

The first milestone is modest: one definition that you can inspect, one implementation you understand, and one boundary you can test. You can keep your application, database and deployment process while evaluating that seam.

  • Pick an operation small enough to explain in a few sentences.
  • Write down one successful request and one request that must fail.
  • Identify the existing business handler and the source of identity.
  • Choose one interface first; add a second when the first is understood.

Choose your learning path

These docs separate learning the model from operating a complete system. You do not need to learn every package or install a managed application before understanding an operation.

Your goalRead nextWhat you should leave with
Understand the modelFirst operationThe ability to identify a contract, handler and runtime boundary
Adopt incrementallyExisting codebaseA plan for wrapping one existing implementation
Expose an agent toolAPI and MCPA shared registry with transport-specific context
Review consequential actionsApproval and policyAn explicit decision and receipt boundary
Look up a symbolReference mapThe declaration and version behind an API

Understand what is shared

A contract describes an operation's identity, data and requirements. A handler performs the business work. A registry binds them, and adapters expose that registered operation to particular interfaces. The host provides identity, policy decisions, provider clients and persistence.

Sharing the definition reduces the number of places that describe the same behavior. It does not remove the need to implement the behavior or decide who may invoke it. Keep that separation visible as you add a second interface.

Finish the first pass

You are ready to expand when you can point to the contract used by both callers, explain where the implementation lives, and demonstrate that an invalid or unapproved request does not reach the effect you intended to protect.

The source-guided pages in this preview are tied to an inspected integration snapshot. Use Installation and release channels before copying package commands into a new project; a source example and an externally verified install are different forms of evidence.

Start

Start with one shared behavior

Choose a small operation, understand its boundaries, and decide what to adopt next.

3 min read · Source-guided

Installation and release channels

Match documentation to the code you actually consume, then verify a small external project.

3 min read · Registry verification pending

Read your first operation

Trace a maintained contract from its input schema to its deliberately small handler.

3 min read · Source reading walkthrough

Adopt ContractSpec in an existing codebase

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

3 min read · Source-guided

Concepts

Contracts, handlers and adapters

Understand the separate responsibilities that let one operation serve several interfaces.

3 min read · Source-guided

What the runtime checks

Follow a call from transport context to handler execution, then understand the limits of each guard.

3 min read · Source-guided

Authentication, policy and scoped approval

Give each decision a clear owner and prove that denied requests never reach the protected handler.

3 min read · Source-guided

Model inputs, outcomes and failures

Make the data boundary explicit while keeping business meaning in the operation and handler.

3 min read · Source-guided

Guides

Expose one operation through API and MCP

Share the registered behavior while keeping authentication, transport formats and evidence explicit.

3 min read · Source-guided

Build interfaces around roles and intent

Resolve appropriate surfaces for people and agents while keeping authority on the execution side.

3 min read · Source-guided

Compose features with explicit dependencies

Connect capabilities, operations and provider ports without hiding what a feature needs to execute.

3 min read · Source-guided

Generation and drift: what changes, what does not

Use derived artifacts deliberately and understand the current boundary of generation plans and apply.

3 min read · Source-guided

Bind external services deliberately

Keep a feature's requirements separate from credentials, tenant connections and provider behavior.

3 min read · Source-guided

Reference

Find the right reference

Navigate portable models, runtime execution, adapters and generated contract records by responsibility.

3 min read · Source-guided

Use the docs with coding agents

Give an agent a small, versioned source set and keep documentation lookup separate from action authority.

4 min read · Source-guided

Operations

Test the promise at the boundary

Choose checks that establish meaningful behavior, including denied effects and real consumer imports.

3 min read · Source-guided

Version contracts and documentation together

Keep operation identity, package releases and deployment revisions distinct when reviewing a change.

3 min read · Source-guided

Find the boundary that failed

Diagnose package, schema, execution and transport failures without changing several layers at once.

3 min read · Source-guided

Contribute a reviewable change

Change the owning source, update the public explanation and bring evidence for the behavior you touched.

3 min read · Source-guided

Observe a call without confusing it with approval

Use traces and outcomes to diagnose execution, and keep durable evidence requirements explicit.

3 min read · Source-guided