---
title: "The Contract · Agentic Atlas"
description: "The Contract: expectations at a seam, from informal prose to enforced structure."
canonical: "https://agentic-atlas.dev/nodes/contract-documentation"
last-updated: "2026-08-19"
---

# The Contract · Agentic Atlas

[← the survey](https://agentic-atlas.dev/atlas)

1. concept
   The Contract
   Hook
   expectations at a seam, from informal prose to enforced structure
   Thesis
   Every crossing is the same primitive, a contract: a two-tier agreement between sender and receiver, documented in proportion to what the seam's conditions demand, that suggests structures and never mandates fields.
   Laws & fences
  - Tier 1 is the standing agreement on shape and how to consume, authored at design time and holding across all crossings of the seam; tier 2 is what each individual crossing must carry, such as provenance, freshness, and the SHA+datetime stamp, which tier 1 obligates but cannot contain.
  - Four dials read any seam's conditions, cost-of-asking, write-to-read gap, receiver type, and sender type, and each scales exactly one piece of contract machinery, which is what makes the derived checklists mechanical and recomputable.
  - Delivery is the sender's obligation: the sender pushes the payload or a pointer to it, there is no pull, and where no delivery channel exists the seam does not exist yet.
  - An uncontracted seam cannot be checked, so it cannot be safely re-dispatched; the price is specification rigor per seam, the sync discipline to keep tier 1 true as the behavior it describes drifts, and the designer work of deriving each seam's checklist from the dials.
   When to reach
  - Reach for it when a system's handoffs are each treated as an ad-hoc problem with its own ad-hoc rigor: dispatch, return, config file, state artifact, envelope, workspace file, human gate, and session handoff are all crossings of the same seam.
  - Skip it for why a seam was created; it is a primitive that says how a seam works, and the seam-creating moves such as dispatching a subagent, deferring context, persisting state, or packing an envelope supply the motive.
   Provenance
   [contract-documentation/definition](https://agentic-atlas.dev/nodes/contract-documentation#definition) · v1.0.2
   Addresses
   atlas_cards contract-documentation
2. [
   Foundations
   ](https://agentic-atlas.dev/nodes/foundations)
3. [
   The Contract Keystone
   ](https://agentic-atlas.dev/nodes/the-contract-keystone)
4. [
   Effect Discipline
   ](https://agentic-atlas.dev/nodes/effect-discipline)
5. [
   Baseline Skill
   ](https://agentic-atlas.dev/nodes/baseline-skill)
6. [
   The Shared Shape
   ](https://agentic-atlas.dev/nodes/shared-shape)
7. [
   The Docs Expert
   ](https://agentic-atlas.dev/nodes/docs-expert-agent)
8. [
   LLM Dispatch
   ](https://agentic-atlas.dev/nodes/llm-dispatch)
9. [
   Subagent Offload
   ](https://agentic-atlas.dev/nodes/subagent-offload)
10. field notes
  - “validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied”
  - “episodic skills with persisted, context-specific behavior — incl. the *free idempotent setup* optimization”
  - “accumulated memory, a **separate concern from config**”
  - “one fixture PR reviewed five ways — a respectable one-shot climbs to a composed three-reviewer architecture, one priced pattern decision per rung”

LLM DispatchSubagent Offload +2 more unfold the map fold the map

The card, in place · its connections drawn edges from atlas_links contract-documentation

On this plate

[definition](https://agentic-atlas.dev#definition)[why-it-matters](https://agentic-atlas.dev#why-it-matters)[model-and-claims](https://agentic-atlas.dev#model-and-claims)[scope-and-boundaries](https://agentic-atlas.dev#scope-and-boundaries)[implications-the-consequence-map-and-tradeoff](https://agentic-atlas.dev#implications-the-consequence-map-and-tradeoff)[evidence-the-derived-readings](https://agentic-atlas.dev#evidence-the-derived-readings)[relationships](https://agentic-atlas.dev#relationships)[lineage](https://agentic-atlas.dev#lineage)[examples](https://agentic-atlas.dev#examples)[open-questions-todo](https://agentic-atlas.dev#open-questions-todo) [relationships](https://agentic-atlas.dev#relationships)

Every section is addressable on its own. Read only the ground you need.

## Definition

[](https://agentic-atlas.dev#definition)

definition.md

**Treat every crossing as the same [primitive](https://agentic-atlas.dev/glossary/primitive): a contract** — a two-tier agreement between sender and receiver, documented in proportion to what the seam's conditions demand. The primitive *suggests structures, never mandates fields*: it supplies a definition, four dials that read any seam's conditions, and the obligations each dial turns on. What the contract *says* is always seam-specific.

## Why it matters

[](https://agentic-atlas.dev#why-it-matters)

why-it-matters.md

In traditional programming you document function parameters, type signatures, invariants. That discipline gets *lost* the moment you move into agentic systems: data gets passed around unstructured and you hope the LLM figures it out. Hand a probabilistic reader unstructured data and it burns reasoning cycles on "what am I seeing, how do I use this" — or worse, guesses confidently and proceeds.

The deeper failure is fragmentation. An agentic system is riddled with handoffs — [dispatch](https://agentic-atlas.dev/glossary/dispatch), return, [config](https://agentic-atlas.dev/glossary/config) file, [state](https://agentic-atlas.dev/glossary/state) artifact, packed [envelope](https://agentic-atlas.dev/glossary/context-envelope), [workspace](https://agentic-atlas.dev/glossary/workspace) file, human [gate](https://agentic-atlas.dev/glossary/gate), session handoff — and each tends to get treated as its own ad-hoc problem with its own ad-hoc rigor, when they are all crossings of the same seam.

## Model and claims

[](https://agentic-atlas.dev#model-and-claims)

model-and-claims.md

### Anatomy — two tiers, non-normative

- **Tier 1 — the standing agreement.** The shared expectation of shape and how-to-consume, authored at design time, holding across all crossings of the seam. USB analogy: the published spec both sides implement before any device plugs in. This *is* the contract's definition — a handshake between stages, whatever the party types (LLM↔LLM, LLM↔deterministic, deterministic↔LLM, human on either end).
- **Tier 2 — per-instance obligations.** What each individual crossing must carry: provenance, freshness, the SHA+datetime stamp. USB analogy: enumeration — every device still self-declares its descriptors at plug-in. Tier 1 *obligates* tier 2 but cannot contain it: stamps are minted per crossing.

**Posture: suggest structures, never mandate fields.** There is no universal field list at this altitude; the two-tier *structure* is the universal part, and seam-specific content fills it. The primitive stamps no standard on the tree.

### The census — one primitive, many seams, four dials

The seams of an agentic system — dispatch, return, config, state artifact, envelope, workspace handoff, human gate, session handoff — are all this one primitive under different conditions. Four dials read any seam's conditions; each dial scales **exactly one** piece of contract machinery, which is what makes the derived checklists mechanical (recomputable, so they can't drift):

| Dial | Scales | Machinery it turns on |
| --- | --- | --- |
| **Cost-of-asking** (free → expensive → impossible; continuous) | completeness | tier-2 assumptions/provenance — everything in the artifact |
| **Write→read gap** (zero → long) | freshness | tier-2 stamps, supersession rules |
| **Receiver type** (LLM / deterministic code / human) | precision | tier-1 strictness — schema exactness |
| **Sender type** (LLM / deterministic code / human) | verification weight | assertion role → [The Contract Keystone](https://agentic-atlas.dev/nodes/the-contract-keystone), *validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied* |

There is no topology or time dial: "the sender is gone by read time" was always the back-channel variable, already priced as **cost-of-asking** by the envelope's lifetime-overlap spectrum (full overlap = free; partial = expensive, re-dispatch; zero = impossible). *Causes* of a dead back-channel (sender gone vs. one-way by design) are explanation, not columns — author to the channel as designed.

**Reading verification weight.** The dial reads **two** things: sender type supplies *how likely* a bad crossing is; what the receiver will *do* with the artifact supplies *how much a bad one costs*, with [Effect Discipline](https://agentic-atlas.dev/nodes/effect-discipline)'s licensing classes (pure / idempotent / isolated; reversible-at-a-cost → irreversible) as the coarse guide — the irreversible end hands off to the human gate. **No fifth dial**: the fine structure (rerunability, time sensitivity, re-run cost, blast radius) is designer judgment, deliberately unpriced — the same posture as cost-of-asking, which also collapses many factors into one qualitative read. When the resulting weight is high enough, the assertion *reifies into a checker stage* — see *validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied*.

**Mid-spectrum rigor relaxation is legitimate.** Where re-dispatch exists, a lighter contract is *lazy contract negotiation priced at re-dispatch cost*, not sloppiness — licensed when catching a starved crossing downstream is cheaper than fully specifying it upfront.

### Delivery — the sender's obligation; there is no pull

The sender pushes either the **payload** or a **[pointer](https://agentic-atlas.dev/glossary/pointer)** to it; "pull" is push-of-a-pointer seen from the wrong end. Three consequences:

1. **Pointer resolvability at read time is a tier-2 obligation**: the path exists, access is granted, and a one-line "what this is" annotation rides with it.
2. **The pointer chain bottoms out** in a harness-guaranteed delivery surface, whose selection is the bootstrap seam's job (*episodic skills with persisted, context-specific behavior — incl. the *free idempotent setup* optimization*) — a cross-reference, not an anatomy element.
3. **No delivery channel → the seam does not exist yet.** Name the precondition before contracting the crossing.

**Return-by-reference's one home is here** — it is the pointer variant of delivery. The dispatch's packing anatomy (`../llm-dispatch/llm-dispatch.md` → *Anatomy of a dispatch*) and the workspace channel below both point back to this clause.

### The workspace seam — a census entry worth naming

Any workspace location one [actor](https://agentic-atlas.dev/glossary/actor) writes and another reads is a seam whose **write→read gap is nonzero** — the dials already price it, and no dispatch relationship is required. The envelope's zero-lifetime-overlap case is this same seam at the impossible end of cost-of-asking. Two rules land here:

- **Writer-owns-the-boundary** — one writer per location, or a designed seam (*accumulated memory, a **separate concern from config***'s rule, generalized) — a dial-conditioned obligation, not an anatomy element.
- The *channel* itself — actors sharing a filesystem — is dispatch-side Structure (`../llm-dispatch/llm-dispatch.md`); this node owns only the contract on what crosses it.

## Scope and boundaries

[](https://agentic-atlas.dev#scope-and-boundaries)

scope-and-boundaries.md

This is a **primitive**, not a strategy: it says *how* a seam works, not *why* you created one. The seam-creating moves — dispatching a [subagent](https://agentic-atlas.dev/glossary/subagent), deferring context, persisting state, packing an envelope — supply the motive; each pays off only when its seam is contracted.

### Admission — the achievable-without test

Content enters this spec only if the seam **cannot function without it**; everything else is admitted only as a **dial-conditioned obligation** — appearing as conditions harden, invisible otherwise. Applied:

- The **shared expectation** (tier 1) survives — without it there is no contract at all.
- Stamps, completeness, schema exactness, pointer rules are all **conditional** — turned on by the four dials.
- **Goal-source fails the test** and stays envelope-side (`../../context-engineering/mechanisms/distillation/context-envelope.md`): a seam functions without knowing whose goal minted the payload.

The spec's architecture follows: **definition + four dials + the obligations each dial turns on** — descriptive, never normative.

## Implicationsthe consequence map and tradeoff

[](https://agentic-atlas.dev#implications-the-consequence-map-and-tradeoff)

implications-the-consequence-map-and-tradeoff.md

Authoring effort and **sync discipline**: a contract drifts under the behavior it describes, and tier 1 is only worth having while it stays true — you pay in specification rigor per seam and keep paying to keep it honest. The non-normative posture has its own price: the primitive hands you dials, not a finished checklist — deriving each seam's checklist is designer work (deliberately, so derived checklists stay recomputable rather than drifting copies). You buy back preprocessing, composability, and the very possibility of verification: an uncontracted seam cannot be checked, so it cannot be safely re-dispatched.

## Evidencethe derived readings

[](https://agentic-atlas.dev#evidence-the-derived-readings)

evidence-the-derived-readings.md

A non-normative primitive is evidenced by what can be **recomputed from it**, and by what its admission test refuses.

- **One derivation on record.** The dispatch's *packing checklist* is authored in `../llm-dispatch/llm-dispatch.md` → *Anatomy of a dispatch* as an explicitly derived reading of the four dials (done 2026-07-05, dispatch-packing fold) — a checklist recomputed from the dials rather than a copy kept in sync.
- **Two refusals on record.** Goal-source failed the achievable-without test and stays envelope-side; the topology/time dial was collapsed into cost-of-asking once the envelope's lifetime-overlap spectrum was found to price it already.
- **What would revise it.** A seam whose machinery no dial scales — one needing a fifth column rather than designer judgment — breaks the census's claim that these are one primitive under four conditions.

## Relationships

[](https://agentic-atlas.dev#relationships)

relationships.md

- **Substrate, like the dispatch.** Sits in Foundations beside `../llm-dispatch/llm-dispatch.md` — the tree's two primitives: the dispatch is the actor boundary, the contract is the seam. Strategies *wield* both rather than apply them.
- **Generalized by [The Contract Keystone](https://agentic-atlas.dev/nodes/the-contract-keystone)** (contract ↔ verification ↔ re-dispatch): the contract is the possibility condition of checking; the sender-type dial's verification weight hands off there and to *validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied*.
- **The return contract ties contract → heavy agent.** A heavy agent (`../../context-engineering/mechanisms/cost-relocation/subagent-offload/heavy-agent/heavy-agent.md`) only pays off if what it hands back is itself distilled and structured; otherwise the context cost is relocated to the orchestrator, not eliminated.
- **[Effect Discipline](https://agentic-atlas.dev/nodes/effect-discipline)** supplies the licensing classes that the verification-weight dial's cost read is coarse-guided by.
- ***episodic skills with persisted, context-specific behavior — incl. the *free idempotent setup* optimization*** owns the bottom of the pointer chain — the harness-guaranteed delivery surface.
- **The envelope** (`../../context-engineering/mechanisms/distillation/context-envelope.md`) is the census's far-end seam: its lifetime-overlap spectrum is what priced the old time leg into cost-of-asking, and goal-source lives there, not here.

## Lineage

[](https://agentic-atlas.dev#lineage)

lineage.md

Design by Contract (Meyer), and interface documentation as specification (Parnas, "On the Criteria To Be Used in Decomposing Systems into Modules", 1972): the documented parameter, type signature, and invariant, carried across a seam where nothing enforces them.

## Examples

[](https://agentic-atlas.dev#examples)

examples.md

- **[The Shared Shape](https://agentic-atlas.dev/nodes/shared-shape)** — a caller and a research step import one seam-owned module containing both request and return shapes. The agreement changes once; both sides encounter the same change.
- ***one fixture PR reviewed five ways — a respectable one-shot climbs to a composed three-reviewer architecture, one priced pattern decision per rung*** (drafting) — the review ladder's data-package seam is contracted shared-shape style inside rung (c): the ladder has no standalone contract rung, because the contract is how the seam is built.

## Open questions / TODO

[](https://agentic-atlas.dev#open-questions-todo)

open-questions-todo.md

- **Cleanup/lifecycle of workspace handoff artifacts** — who deletes a handoff artifact, and when? The contract dials price freshness and lifecycle but do not yet assign deletion authority for this artifact class.

The relationships ledger

Evidence-bearing references

## Relationships

Every connection keeps the section where it was found. The map above orients; this ledger carries the evidence.

### Outbound references 12

1. in-slice · occurrence 1
   [The Contract Keystone](https://agentic-atlas.dev/nodes/the-contract-keystone)
   contract ↔ verification ↔ re-dispatch
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/contract-documentation#model-and-claims) · occurrence 1
2. undisclosed · occurrence 2
   Undisclosed relationship
   validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/contract-documentation#model-and-claims) · occurrence 2
3. in-slice · occurrence 3
   [Effect Discipline](https://agentic-atlas.dev/nodes/effect-discipline)
   the precondition under "discard is cheaper than repairing"
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/contract-documentation#model-and-claims) · occurrence 3
4. undisclosed · occurrence 4
   Undisclosed relationship
   validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/contract-documentation#model-and-claims) · occurrence 4
5. undisclosed · occurrence 5
   Undisclosed relationship
   episodic skills with persisted, context-specific behavior — incl. the *free idempotent setup* optimization
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/contract-documentation#model-and-claims) · occurrence 5
6. undisclosed · occurrence 6
   Undisclosed relationship
   accumulated memory, a **separate concern from config**
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/contract-documentation#model-and-claims) · occurrence 6
7. in-slice · occurrence 1
   [The Contract Keystone](https://agentic-atlas.dev/nodes/the-contract-keystone)
   contract ↔ verification ↔ re-dispatch
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/contract-documentation#relationships) · occurrence 1
8. undisclosed · occurrence 2
   Undisclosed relationship
   validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/contract-documentation#relationships) · occurrence 2
9. in-slice · occurrence 3
   [Effect Discipline](https://agentic-atlas.dev/nodes/effect-discipline)
   the precondition under "discard is cheaper than repairing"
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/contract-documentation#relationships) · occurrence 3
10. undisclosed · occurrence 4
    Undisclosed relationship
    episodic skills with persisted, context-specific behavior — incl. the *free idempotent setup* optimization
    Evidence: [Relationships](https://agentic-atlas.dev/nodes/contract-documentation#relationships) · occurrence 4
11. in-slice · occurrence 1
    [The Shared Shape](https://agentic-atlas.dev/nodes/shared-shape)
    both sides of a seam import one shared request-and-return shape
    Evidence: [Examples](https://agentic-atlas.dev/nodes/contract-documentation#examples) · occurrence 1
12. undisclosed · occurrence 2
    Undisclosed relationship
    one fixture PR reviewed five ways — a respectable one-shot climbs to a composed three-reviewer architecture, one priced pattern decision per rung
    Evidence: [Examples](https://agentic-atlas.dev/nodes/contract-documentation#examples) · occurrence 2

### Inbound references 9

1. in-slice · occurrence 1
   [Baseline Skill](https://agentic-atlas.dev/nodes/baseline-skill#definition)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Definition](https://agentic-atlas.dev/nodes/baseline-skill#definition) · occurrence 1
2. in-slice · occurrence 2
   [Baseline Skill](https://agentic-atlas.dev/nodes/baseline-skill#relationships)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/baseline-skill#relationships) · occurrence 2
3. in-slice · occurrence 1
   [The Docs Expert](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Verification](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · occurrence 1
4. in-slice · occurrence 2
   [Foundations](https://agentic-atlas.dev/nodes/foundations#definition)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Definition](https://agentic-atlas.dev/nodes/foundations#definition) · occurrence 2
5. in-slice · occurrence 5
   [Foundations](https://agentic-atlas.dev/nodes/foundations#model-and-claims)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Model and claims](https://agentic-atlas.dev/nodes/foundations#model-and-claims) · occurrence 5
6. in-slice · occurrence 2
   [Foundations](https://agentic-atlas.dev/nodes/foundations#evidence-the-test-s-track-record)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Evidence](https://agentic-atlas.dev/nodes/foundations#evidence-the-test-s-track-record) · occurrence 2
7. in-slice · occurrence 2
   [Foundations](https://agentic-atlas.dev/nodes/foundations#relationships)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/foundations#relationships) · occurrence 2
8. in-slice · occurrence 1
   [LLM Dispatch](https://agentic-atlas.dev/nodes/llm-dispatch#relationships)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/llm-dispatch#relationships) · occurrence 1
9. in-slice · occurrence 5
   [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload#relationships)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/subagent-offload#relationships) · occurrence 5

[↑ back to the top](https://agentic-atlas.dev#content) [← the survey](https://agentic-atlas.dev/atlas)

Node contract-documentation · corpus 31de4cb · Catalog revision 35263c4c415da742953d0462804fb14424e2244dae4c63efd27e468988de70ab