Core and contract versioning

This site is the sole architecture canon. Versioning keeps adopters aligned when rules or contracts change.

Version surfaces

Surface	Current	Meaning
Core badge	`1.0.0-draft`	Normative Modular Hexagonal DDD rules on this site
Docs URL	`/v1/...`	Major docs generation; breaking IA/rule sets may open `/v2`
Optional assistant pack	Same as Core badge when used	Convenience slice only — not a Core MUST
Published contracts	Per event / façade	`schemaVersion` on events; additive methods on façades

SemVer for Core (when leaving draft)

Bump	When
MAJOR	Normative MUST rules change in a breaking way (e.g. forbidding a previously allowed bridge)
MINOR	New pages, new recommended practices, new MUST that does not invalidate correct existing modules
PATCH	Clarifications, typos, diagram fixes, non-normative examples

While the badge ends in -draft, treat all normative pages as evolving; adopters should pin a git commit or tag of this docs repo, not only the badge string.

Contract evolution (modules)

Change	Approach
Add optional event field	MINOR / additive — bump `schemaVersion` if consumers must notice
Remove or rename event field	New event type or major `schemaVersion` + dual-publish window
Add façade method	Additive — OK
Change façade method meaning	New method; deprecate old
Replace in-process façade with HTTP	Consumer ACL adapter only — Application/Domain unchanged

Adopter checklist

Link architecture docs to this site (or a pinned mirror).
Version your own Domain Events with schemaVersion + eventId.
Record host adapter version separately (adapter pages may advance without a Core major).
Optionally keep an assistant pack in sync if your team uses AI tools — never required for compliance.

Compatibility promise (draft)

Until 1.0.0 (non-draft):

Greenfield example names stay Ordering, Warehouse, Directory, Identity.
Core remains framework-agnostic (no host ORM / admin UI as Core MUST).
Breaking clarifications are logged in this repo’s ROADMAP.md decision log.

Next: Portable requirements · Adopt.