ZAIXOS Engineering Platform — Version Transition Plan
Document type: Extraction Planning Specification
Version: 1.0 · Phase: 12-4
Status: Permanent execution authority
Purpose
Define the version lineage from ERP v1 embedded baseline through ZEP v1.0.0 GA to future platform versions — without semantic breaks at cutover.
Version transition timeline
ERP v1.0 (embedded)
│ Semantic baseline: contracts@1, adapter 1.0.0-phase-11-9
│ Product tag: v5.1-engineering-runtime-platform (historical)
▼
Dual-run embedded + platform package (12-7–12-8)
│ Platform package: 1.0.0-rc.* → 1.0.0
▼
ZEP v1.0.0 GA (12-9)
│ Tag: zaixos-platform@v1.0.0
│ Consumer lock: platform 1.0.0, contractMajor 1
▼
ZEP v1.x PATCH/MINOR
│ Additive only; contracts@1 frozen
▼
ZEP v2.0.0 (future)
│ Requires contracts@2 ADR — out of extraction scopeIdentity mapping
| Historical identifier | Platform identifier | Notes |
|---|---|---|
| ERP v1.0 | ZEP 1.0.0 | Same obligations |
contracts@1 (implicit in ERP) | contracts@1 explicit in lock | Frozen |
Cursor Adapter 1.0.0-phase-11-9 | cursor-adapter-v1 @ 1.0.0 | Renormalize semver at GA (content parity) |
| EOS v1.0 methodology | Platform Core methodology | Same files, new paths |
Embedded docs/development/ | vendor/.../ + .zaixos/ | Host change only |
Adapter version normalization
| Stage | Version string |
|---|---|
| Pre-extraction (Dental Clinic) | 1.0.0-phase-11-9 |
| Platform repo during 12-6 | 1.0.0-rc.1 … 1.0.0-rc.n |
| GA (12-9) | 1.0.0 |
Rule: GA version bump is label only if workspace checksum unchanged vs rc final — documented in CHANGELOG.
Platform package versions during extraction
| Phase | Platform version | Tag type |
|---|---|---|
| 12-5 Scaffold | — | No tag |
| 12-6 Extraction | 1.0.0-rc.1+ | Pre-release tags on platform repo |
| 12-7 Consumer | 1.0.0-rc.final | Consumer pins rc until 12-8 pass |
| 12-8 Validation | 1.0.0-rc.final | Parity sign-off |
| 12-9 GA | 1.0.0 | zaixos-platform@v1.0.0 |
Product (Dental Clinic) version independence
| Artifact | Versioning |
|---|---|
| Product release tags | Unchanged — e.g. v4.x-* product phases |
| Platform pin | platform.lock @ 1.0.0 after 12-9 |
| composer.lock | Tracks platform package |
Product releases do not require platform MINOR bumps unless platform upgrade scheduled.
contractMajor transition rules
| Transition | Allowed when | Process |
|---|---|---|
contractMajor: 1 → stays 1 | All platform 1.x | Default |
contractMajor: 1 → 2 | Platform 2.0 ADR | Re-cert adapters; migration guide |
| Product stays on 1 | Platform 2 released | Supported 12 months PATCH on 1.x |
Extraction phases: contractMajor MUST remain 1.
Embedded → vendored cutover
| Milestone | Embedded state | Vendored state |
|---|---|---|
| Pre-12-7 | Authoritative | Absent |
| 12-7 dual-run | Frozen baseline | Active dev |
| 12-8 | Parity reference | Primary validation target |
| 12-9 | Removed (stub only) | Sole authority |
Future platform versions (post-GA)
Per EVOLUTION_MODEL.md:
- 1.x: Additive; Dental Clinic upgrades via lock bump + rematerialize
- 2.x: MAJOR; Architect acceptance + migration guide mandatory
Extraction planning does not schedule v2.
Version documentation deliverables
| Deliverable | Phase | Location |
|---|---|---|
| Platform CHANGELOG | 12-6+ | Platform repo root |
| Release compatibility matrix | 12-9 | docs/releases/v1.0.0.md |
| Consumer lock committed | 12-7 | .zaixos/platform.lock |
| Migration note ERP→ZEP | 12-7 | Product release doc + platform developer-guide § Migration |
Version Transition Plan v1.0 — Phase 12-4.