Contract authoring and runtime ownership
Status: open/proposed
Summary
Section titled “Summary”- The contract vocabulary (mcVersion-2 meta-schema) and the
FindingDTO are cross-language normative now; which engine runs them is decided per surface, not globally. - The TS programmatic API (combinators + Zod) stays canonical until an explicit replacement decision for transforms, refinements, and custom rules exists.
- Flip bars differ by surface: the declarative plane may flip on fixture + DTO parity; the programmatic surface flips only on demonstrated source-compatibility.
Context
Section titled “Context”The Rust engine covers the declarative validation plane, not the full TS
combinator/Zod surface. SDLC runs both a Zod registry and a Contract registry for
related but non-identical jobs (_registry.ts, _contracts.ts). Treating “the
engine” as one thing conflates vocabulary, authoring APIs, runtimes, and generated
artifacts — each with its own compatibility promise.
Decision
Section titled “Decision”| Surface | Normative now | Runtime ownership | Flip bar |
|---|---|---|---|
| Declarative YAML contracts | mcVersion-2 vocabulary + published meta-schema | Replaceable (TS or Rust/WASM engine) | Shared fixture corpus + Finding DTO parity |
| Programmatic contracts (combinators, Zod content plane) | TS API is canonical | TS engine | Source-compatibility demonstrated, plus an explicit replacement decision for Zod transforms/refinements/custom rules — never fixture parity alone |
Finding DTO | Frozen interchange shape: id, severity, path, span, hint | All engines emit it | Field changes require a contract-version bump per Q-5 |
| Generated artifacts (JSON Schema projections, typed models) | Derived, never hand-edited | Regenerated from the normative surface | n/a |
Open questions
Section titled “Open questions”- Q-4: the long-term authoring surface — TS/Zod, declarative YAML, Rust builders, or generated artifacts — and which parts are normative versus adapters.
- Q-5: exactly which
Findingfields are stable API (ids, severity, spans) versus changeable without a version bump (message text, hints).
References
Section titled “References”D-7VMX-markdown-ecosystem-strategy review-discussion.md (R-2, Q-4, Q-5);
ext-markdown-contract.md §7 on declarative-plane-only Rust coverage.