ZAIXOS Engineering Platform — Installation Architecture

Document type: Technical Specification
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Related: PACKAGE_ARCHITECTURE.md · RUNTIME_MATERIALIZATION.md · CONFIGURATION_ARCHITECTURE.md

---

Purpose

Define how platform artifacts enter a product repository — install modes, bootstrap sequence, version resolution, and post-install verification — without prescribing Composer script implementation (Phase 12-5+).

---

Install modes

Mode ID	Name	Priority	Mechanism
IM-1	Composer dependency	Primary	composer require zaixos/engineering-platform:^1.0
IM-2	Git submodule	Secondary (transitional)	Submodule at tag SHA + lock
IM-3	Snapshot tarball	Edge / air-gap	Verified checksum vs lock
IM-4	Git template bootstrap	Experimental	One-time scaffold; ongoing updates via IM-1

Production release branches must use IM-1 with committed platform.lock.

---

Installation phases (logical)

P1  Preconditions
P2  Fetch
P3  Layout
P4  Configure
P5  Materialize
P6  Validate
P7  Record

---

P1 — Preconditions

Check	Requirement
Product repo	Has composer.json, PHP ^8.2
Architect approval	Platform version + adapter ID chosen
Clean tree	No uncommitted edits under .zaixos/ (recommended)
Network / VCS	Access to Packagist or platform repo

---

P2 — Fetch

Composer (IM-1):

composer require zaixos/engineering-platform:{constraint}

Records version in composer.lock.

Submodule (IM-2):

git submodule add {platform-repo-url} .zaixos/platform-source
git checkout {tag from platform.lock}

---

P3 — Layout

Establish product namespace:

Path	Action
.zaixos/platform.yml	Create if absent (from template in package schemas/config/examples/)
.zaixos/platform/	Symlink or copy from vendor/zaixos/engineering-platform
.zaixos/extensions/manifest.yml	Create empty registry if absent
.zaixos/adapters/	Created at materialization

Rule: Platform files live under .zaixos/platform/ or vendor — never duplicated as authoritative copies in docs/development/ after Phase 12-7.

---

P4 — Configure

Populate platform.yml:

configSchema: 1
productId: dental-clinic-ros
platform:
  versionConstraint: "^1.0"
  adapter:
    id: cursor-adapter-v1
    mount:
      canonical: .zaixos/adapters/cursor-adapter-v1/workspace
      ide: .cursor
      strategy: symlink   # symlink | copy
extensions:
  manifest: .zaixos/extensions/manifest.yml
validation:
  suite: EngineeringRuntimePlatform
  failClosed: true

See PLATFORM_CONFIGURATION_REFERENCE.md.

---

P5 — Materialize

Invoke materialization (future CLI or documented manual sequence):

1. Copy adapter template → .zaixos/adapters/cursor-adapter-v1/workspace/
2. Merge extensions per EXTENSION_ARCHITECTURE.md
3. Create .cursor/ mount per mount.strategy
4. Compute workspace checksum

Details: RUNTIME_MATERIALIZATION.md.

---

P6 — Validate

Run platform validation suite. Installation incomplete until green.

Minimum gates:

• ConfigSchemaTest
• ContractComplianceTest
• ManifestParityTest
• AdapterWorkspaceTest

---

P7 — Record

Write platform.lock:

lockSchemaVersion: 1
platform:
  version: 1.0.0
  contractMajor: 1
  package: zaixos/engineering-platform
adapter:
  id: cursor-adapter-v1
  version: 1.0.0
materializedAt: "2026-06-28T12:00:00Z"
checksum:
  algorithm: sha256
  adapterWorkspace: "abc123..."
installMode: composer

Commit: platform.yml, platform.lock, .zaixos/ tree (or vendor-only + lock per team policy), mount.

---

Bootstrap flow (developer first session)

1. git clone {product}
2. composer install
3. Verify .zaixos/platform.lock exists
4. Verify .zaixos/platform/ or vendor path
5. Verify .cursor/ mount (cursor-adapter-v1)
6. Run validation command (documented entrypoint)
7. Read docs/developer-guide.md (platform) or ERP_DEVELOPER_GUIDE (transitional)
8. Open IDE — native session uses .cursor/

Target KPI: ≤ 60 minutes install-to-green (SUCCESS_METRICS.md).

---

Version resolution flow

Input: platform.yml versionConstraint
       platform.lock platform.version (if exists)
       composer.lock package version

Algorithm:
  IF production branch:
    REQUIRE lock.version == composer.version
    REQUIRE semver.satisfies(lock.version, yaml.versionConstraint)
  ELSE development:
    ALLOW composer update within constraint
    WARN on lock drift

  RESOLVE adapter:
    yaml.platform.adapter.id MUST match lock.adapter.id
    adapter.version from lock (exact)

  RESOLVE contractMajor:
    FROM package extra.zaixos.contractMajor
    MUST match lock.platform.contractMajor

Output: ResolvedPlatformPin { platform, adapter, contractMajor, checksum }

---

Upgrade installation (in-place)

Distinct from first install — see EVOLUTION_MODEL.md.

1. Read CHANGELOG for target version
2. Update composer constraint if needed
3. composer update zaixos/engineering-platform
4. Apply migration guide steps (MAJOR)
5. Rematerialize adapter
6. Update platform.lock + checksum
7. Full validation
8. Architect acceptance for MAJOR

---

Rollback installation

1. git revert platform.lock + composer.lock to last green
2. composer install
3. Rematerialize from reverted adapter version
4. Validation green before resume development

---

Failure handling

Failure	Behavior
Composer resolve fail	Stop; do not partial install
Checksum mismatch	Stop; rematerialize or re-fetch package
Validation fail	Stop; installation not recorded in lock
Symlink unsupported	Auto-fallback to copy strategy (document in lock)
Extension invalid	Stop; fix manifest before record

---

Installer interface (future — specification only)

// Conceptual — not implemented in Phase 12-3
interface PlatformInstallerInterface
{
    public function install(ResolvedPlatformPin $pin, InstallContext $ctx): InstallResult;
    public function materialize(ResolvedPlatformPin $pin): MaterializationResult;
    public function validate(InstallContext $ctx): ValidationResult;
    public function upgrade(ResolvedPlatformPin $from, ResolvedPlatformPin $to): UpgradeResult;
}

Products consume installer; they do not implement it.

---

Out of scope (this document)

• Composer script PHP code
• CLI binary
• CI YAML
• Git operations automation

---

Installation Architecture v1.0 — Phase 12-3.