ZAIXOS Engineering Platform — Packaging Strategy

Document type: Product Definition
Version: 1.0 · Phase: 12-2
Status: Permanent product authority
Constraint: Specification only — no implementation choice executed in this phase

---

Purpose

Define how ZEP may be distributed to products, selection criteria, and strategic ordering — without building packages, CLIs, or installers.

Aligns with ADR-005 decisions recorded in 12-1A.

---

Distribution Models Evaluated

Model	Description	Fit for ZEP
Composer package	zaixos/engineering-platform in product composer.json	High for PHP/Laravel products
Git submodule	Platform repo linked as submodule	Medium — transitional
Git template	GitHub template generates new repo snapshot	Low — bootstrap only
CLI installer	Binary downloads and lays down .zaixos/	Medium — future convenience
Git submodule + symlink	Submodule + link .zaixos	Low — ops friction
Standalone repository (consume via tag)	Manual copy from releases	Low — drift risk
SaaS generator	Hosted scaffold	Future candidate — not packaging for v1
npm package	For TS tooling / SDK	Future if SDK is JS-first

---

Primary Distribution Strategy

Composer package for PHP/Laravel products.

Attribute	Definition
Intent	Products declare platform as dependency; vendor path or custom installer places .zaixos/
Pin mechanism	composer.lock + .zaixos/platform.lock
Upgrade path	composer update + platform migration guide
Why primary	Dental Clinic and near-term ZAIXOS products are Laravel; Composer is native; semver familiar

Status: Strategic decision from ADR-005 — not implemented in Phase 12-2.

---

Secondary Distribution Strategy

Git submodule (transitional).

Attribute	Definition
Intent	Bridge period while Composer package matures or for contributors working on platform + product simultaneously
Pin mechanism	Submodule commit SHA recorded in .zaixos/platform.lock
When used	Platform repo extraction phases; dual maintenance
Exit criteria	Composer GA + migration guide published; submodule deprecated classification

---

Future Distribution Strategy

Strategy	Trigger	Role
Platform CLI	Post-v1 GA; Experimental → Public	Unified validate, materialize, doctor across install methods
Git template	New product bootstrap automation	Secondary one-time scaffold — not ongoing updates
Standalone tarball release	Air-gapped or non-Composer CI	Edge cases; not primary
npm / multi-ecosystem packages	Non-PHP product ADR accepted	Parallel primary for that ecosystem

---

Selection Criteria (Decision Matrix)

When choosing distribution for a given product or phase, apply in order:

Criterion	Weight	Question
Drift resistance	Critical	Does the model prevent authoritative copies in product repos?
Semver alignment	Critical	Can products pin and upgrade with explicit migration notes?
PHP/Laravel fit	High (ZAIXOS v1)	Is product Composer-based?
IDE materialization	High	Can adapter workspace be regenerated deterministically?
Contributor ergonomics	Medium	Does platform team need simultaneous platform+product edits? → submodule OK temporarily
Onboarding friction	Medium	Steps until first green validation
Air-gap / offline	Low (until enterprise ADR)	Tarball fallback
Non-PHP products	Deferred	Requires separate primary strategy ADR

Winner for ZAIXOS v1 PHP products: Composer primary; submodule secondary.

---

Packaging Contents (What Gets Delivered — Conceptual)

Regardless of distribution channel, the logical package contains:

core/           # Constitution, methodology, templates
contracts/      # contracts@1
runtime/        # Specs, manifest schemas
adapters/       # Certified adapter templates
validation/     # Integrity tests
docs/           # Developer guide, product specs

Product repo retains:

.zaixos/        # Materialized or symlinked from package
.zaixos/platform.lock
.zaixos/extensions/manifest.yml   # product-owned entries
.cursor/        # Adapter materialization (Cursor v1)
app/            # product domain
docs/architecture/  # product constitution

---

Explicit Non-Decisions (This Phase)

The following are not chosen for implementation in Phase 12-2:

• Exact Composer package name beyond ADR provisional zaixos/engineering-platform
• Post-install script behavior
• CLI command names
• Whether .zaixos/ is copied or symlinked from vendor/
• Repository name for platform host

These belong to Phase 12-4 (Repository Extraction Planning) and later implementation phases (12-5 through 12-9).

---

Compatibility Philosophy (Packaging)

Rule	Statement
Lock file authority	.zaixos/platform.lock is source of truth for platform version identity
Composer lock	Must agree with platform lock for PHP products
Adapter pin	Lock records adapter ID + compatible version range
Contract pin	Lock records contracts@1 until new contract major ADR

---

Packaging Strategy v1.0 — Phase 12-2.