The contract for the ProgramIR — the serialized, language-neutral form of a DSPy program. This repo owns what an artifact is: its manifest, versions, node-set grammar and semantics, link step, placement/profile rules, and refusal codes — independent of any implementation in any language.
Status: AUTHORITY.md and spec/SCOPE.md ratified 2026-08-06; spec
contents provisional until the 1.0 freeze. Seeded from the ratified
decisions D-020..D-029 in MaximeRivest-dspy/roadmap/05-decisions.md;
MaximeRivest-dspy/roadmap/IR-program-spec.md remains the design authority
for unextracted detail, with the precedence ladders in AUTHORITY.md
governing everything fixtured here.
Read AUTHORITY.md first. It says what wins when sources disagree.
| layer | contract | owns |
|---|---|---|
| wire | lm15-contract | canonical Request/Response/StreamEvent |
| signature ⇄ messages | adapter-ir contract | rendering + parsing (presets, templates, codecs, strategies) |
| program | this repo | the artifact: manifest, pools/bindings, forward node set, placement, versions, refusal |
This contract consumes the two below it by reference: component 4 of a
manifest is a pool of adapter-ir preset entries; component 8a is the lm15
contract. Their versions appear in every artifact's versions block.
| path | what |
|---|---|
AUTHORITY.md |
the constitution: fact types, precedence ladders, evidence rules |
spec/SCOPE.md |
frozen / provisional / out-of-scope for 1.0 |
spec/invariants.md |
numbered laws PIR-NNN |
spec/manifest.md |
the artifact: components, pools, bindings, on-disk layout |
spec/versions.md |
the versions block and refusal rules |
spec/node-set.md |
forward grammar: statement whitelist, leaf rule, operational semantics |
spec/linking.md |
the link step: pools → bindings → resolved program |
spec/placement.md |
the ladder, rung-walk, declared-tier profile |
spec/errors.md |
machine-readable refusal codes |
cases/ |
fixture corpus (see cases/README.md for families + seeding plan) |
harness/PROTOCOL.md |
the language-neutral conformance shim protocol |
changes/ |
dated entries — the only mutation path for the oracle |
IMPLEMENTATIONS.md |
how an implementation claims conformance (grades, CONTRACT_PIN) |
- Grade 1 — hold. Parse, validate, version-check, link-check, diff,
explain. A pure data library; all an optimizer needs (scoring may be a
remote engine). Harness ops:
load_manifest,check_versions,link,profile_check,diff,node_compile,explain. - Grade 2 — execute. Grade 1 plus the node-set interpreter, the
adapter-ir engine, and an lm15 client. Conformance additionally requires
the two lower contracts' own harnesses. Harness ops:
node_execute,verify(capability-gated).
An implementation claims a grade plus a profile (see spec/placement.md);
it never claims completeness (PIR-011).