Specification

mediva is written down as a specification so a contract means the same thing wherever it is checked: in CI, in an agent loop, in an editor, by any implementation. The spec is draft 2. It defines what a contract can say and what a checker must report — not prose style, grammar, or spelling.

The standard in one pageCopy Anchor Link

A contract is a Markdown file whose <!-- mdv: … --> comments state what a conforming document must contain. A checker compiles the contract, checks a document against it, and reports each violation as a diagnostic with a stable code. Every rule in the language — required, content.words.min=20, items.all=checked — is a prop on a target (a section's words, a list's items, a table's rows) with one definition, so two implementations cannot disagree about what a prop means.

ModulesCopy Anchor Link

The standard is one mandatory level plus optional modules. An implementation claims "mediva Core", or "mediva Core + Grounding + …" — never a module on its own.

• Core (required) — directive grammar and block kinds, targets and the Item shape, props, diagnostics and codes, and extends. There is no partial Core.
• Grounding (optional) — claims and entities checked against external sources: vocabularies, change sets, and the path / ref entity kinds.
• Repair (optional) — normative, byte-identical fixes for shape defects (a whole-document fence, a chat preamble or postamble), and nothing that needs judgment about content.
• Protocol (optional) — the machine boundary: the JSON diagnostic shape, exit codes, and the idempotent-check and repair-loop contracts.

ConformanceCopy Anchor Link

A conformance claim is checked, not asserted. The conformance suite is a set of language-neutral cases — a contract, a document, and the exit code and diagnostics a conforming checker must produce — that any implementation can run. The reference implementation is the mediva npm package (TypeScript); a Rust implementation is planned against the same suite.

Where to startCopy Anchor Link

• Writing contracts — read Tags & rules and the rule reference first; the spec's §3 and §5 are the precise definitions behind them.
• Implementing a checker — start with §0 Conformance levels, then §2–§6 and §8 in order, and run the conformance suite as you go.
• Integrating a checker into CI or a tool — the Protocol module (§8.1, §8.5) is the contract you can depend on.

PagesCopy Anchor Link

• Core specification — the full normative text: scope and overview, conformance levels, data model, directive grammar, targets, props, sources, vocabularies, diagnostics, repair, and the spelling table.
• Conformance suite — the case format and how to run it against an implementation.