Markdown contract and validation
Status: open/building · Kind: subsystem · Audience: system
Summary
Section titled “Summary”- One contract per document type yields both validation (findings with path:line) and a
typed model from a single parse —
markdown-contract’s three-plane design adopted fleet-wide. - Frontmatter and the declarative surface speak the mcVersion-2 JSON-Schema-idiom vocabulary with its published meta-schema.
- Validation is a tier-1 product feature: polish surfaces findings to users; sdlc gates entities on them; CI consumes JSON/SARIF.
Statement
Section titled “Statement”A contract declares a document type’s shape on three cooperating planes: a structure
grammar over sections and block kinds (order, optionality, repeatability), content
schemas over each block’s data (frontmatter fields, table cells, list items), and named
rules for cross-cutting and cross-file constraints. All three emit one Finding shape —
namespaced id, severity as contract data, position, hint, described-but-not-applied fix.
A clean document additionally yields a typed model: the contract that checks a document
also types it. This is the fleet’s answer to “JSON Schema for markdown,” covering body
structure — which JSON Schema alone cannot express — without forking from JSON Schema
where it fits.
What it provides
Section titled “What it provides”- Programmatic contracts (TS today, Rust/WASM per M-F4RZ-wasm-ts-distribution) and a no-code declarative YAML surface over the same engine.
- Corpus-level validation: directory→contract routing, aggregated findings, CI exit codes, JSON/SARIF output.
- Typed reads: sections, table rows, list items, frontmatter as typed values.
- Contract inference from an existing corpus, with drift checking.
- The extension point (
BlockKind/LeafSpec) that C-Z7LN-embedded-peer-content builds on.
Underlying implementation
Section titled “Underlying implementation”markdown-contract (external repo, canonical): TS engine + CLI (canonical), Rust
engine at declarative-plane parity via shared fixture corpus. In-monorepo consumers:
every solutions/ontological entity schema.ts (per S-0005-entity-definition-contract),
solutions/determined/packages/vault-contracts and its app suite. determined-contracts
(Rust) converges onto the declarative engine per M-8DQW-one-contract-layer.