On this page

Composition contracts

A contract block declares atoms that must (or must not) be loaded together. It guarantees a complete-by-construction set when the agent loads a parent atom.

Why contracts

Agents are free to compose atoms — but not every combination is safe. A method might require a specific term to be in context for its instructions to make sense, or it might be nonsense to load alongside an antagonistic anti-pattern. Contracts make those constraints declarative.

Three contract clauses

Clause	Meaning	Runtime behaviour
`must-include`	Loading the parent loads these atoms.	Inserted into the agent's atom set automatically.
`must-avoid`	These atoms cannot be loaded with the parent.	Filtered from candidates; warning if forced.
`conditionally-required`	If condition, must include atoms.	Evaluated at L3 against the IntentObject.

Where contracts attach

Contracts can be declared on these kinds:

method — most common. Every step needs supporting terms / facts / sources.
persona — defines the voice + companion atoms a posture brings.
scope — declares an exclusive subset (e.g. "regulated-fintech-mode").
collection — implicit: all members are must-include.

Example

method PanSauce {
  id: "@recipes/method-pan-sauce"
  version: "1.0.0"
  description: "Build a pan sauce from fond after searing."
  domain: cooking

  steps: [
    @recipes/step-deglaze,
    @recipes/step-reduce,
    @recipes/step-mount-with-butter,
  ]

  contract: {
    must-include: [
      @recipes/term-fond,
      @recipes/term-deglazing,
      @recipes/fact-water-evaporation-temp,
    ]
    must-avoid: [
      @recipes/anti-pattern-microwave-reduce,
    ]
    conditionally-required: [
      { when: "vegetarian:true", include: [@recipes/value-stock-vegetable] },
    ]
  }
}

Resolution at runtime

When the retriever picks method-pan-sauce as a hit, the runtime walks the contract and ensures the agent's atom set includes term-fond, term-deglazing, and fact-water-evaporation-temp. It also flags anti-pattern-microwave-reduce as not-loadable for this turn.

The agent never gets a half-resolved set. Missing must-includes are surfaced as L3 errors at compile time, so the agent at runtime sees only validated contracts.

Contracts vs explicit edges

A contract is a stronger commitment than a requires edge. The verb requires says "if you load A you should also load B." A contract's must-include says "the protocol guarantees B is loaded whenever A is." Use the contract when correctness depends on the bundling.