Conformance & versioning
Two artifacts declaring the same contract major and suite version decide identically; the CI suite, semver rules and release pins below make that true.
The cross-language conformance suite
CI enforces "every SDK behaves identically": a release that fails the cross-language suite does not ship. The suite is a committed set of JSON vectors derived deterministically from the reference implementation, each holding a canonical challenge, a holder envelope, a declarative description of the proven on-chain state ("world") and the frozen expected decision. Coverage is total by construction and CI-asserted:
- one accepted case (plus policy-nuance positives),
- at least one rejection for each of the nine acceptance conditions,
- every producible reason code in the vocabulary.
Every SDK must pass the suite before release:
- the Python SDK replays every vector through the library and through the service HTTP surface;
- the TypeScript client replays every vector through real HTTP against the reference service running with test doubles;
- the committed vectors are byte-compared against regeneration on every CI run — the suite cannot drift from the reference implementation silently.
A release declares the suite version it passed (also readable at runtime via build_info().conformance_suite_version).
Version numbers and what they promise
Everything follows semver with one shared rule: decision semantics are major.
| Artifact | Major means | Minor means |
|---|---|---|
mintid-verifier-sdk (Python) | public surface or accepted-behavior change | additive surface |
OpenAPI contract verifier-service.v1 | a change of decision semantics, or removing, renaming or changing the meaning of a reason code | additive wire surface, and adding a reason code that no request the deployment issued before can produce |
| Conformance suite | a change to any case’s expected decision | new cases |
@mintid-net/verifier-client | tracks the contract major | — |
Release pins (what an artifact tells you about itself)
Every SDK artifact records, programmatically readable:
engine_pin— the exact proof engine compiled into the package, and the fact about a build that no release note can override: two deployments that disagree on this string are not interchangeable, and a non-verifying build can never masquerade as a verifying one. Read it from the instance you integrate against, not from a page.state_vectors_versionandstate_vectors_sha256— the chain store-layout vectors this build was release-gated against; a mismatch with the target chain blocks the release outright.- Engine pin bumps are reviewed release changes — never automatic, not overridable by dependency resolution, not substitutable through any supported install path.
What this buys you as an integrator
You can treat any two artifacts declaring the same contract major and the same suite version as decision-equivalent: same inputs, same accept/reject, same reason code, in any language. CI re-proves that equivalence on every change.