ZAIXOS Engineering Platform — Package Architecture

Document type: Technical Specification
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Related: DEPENDENCY_MODEL.md · INSTALLATION_ARCHITECTURE.md

---

Purpose

Define the logical and physical package structure of ZEP — what ships inside the platform distribution, how paths map to ownership domains, and how products consume packages without forking.

---

Distribution model

Attribute	Decision
Primary distribution	Single Composer package: zaixos/engineering-platform
Package type	Library + resource files (no Laravel service provider required for v1)
Versioning	Platform semver on package tag
Secondary distribution	Git submodule pointing at platform repository tag (transitional)
Consumer mount	.zaixos/platform/ in product repo (copy or symlink from vendor)

---

Logical packages (internal modules)

All logical packages ship inside one Composer artifact. They are not separate Composer packages in v1.

Logical ID	Path (platform repo)	Owner	Contents
LP-0	core/constitution/	D-P	Pointers to governance docs (or embedded copies at release)
LP-1	core/methodology/	D-P	DEVELOPMENT_WORKFLOW, RESPONSE_TEMPLATE, freeze, context policy
LP-2	contracts/	D-P	runtime-contracts.md, JSON schemas, contracts@1
LP-3	runtime/specification/	D-P	ERP/runtime abstract spec
LP-4	runtime/components/	D-P	Eight component prose specs
LP-5	runtime/manifests/	D-P	Schemas + default inventories
LP-6	adapters/{adapter-id}/	D-A	profile, workspace template, manifest.json
LP-7	templates/	D-P	Format A/B, phase prompts
LP-8	knowledge/	D-P	Platform knowledge packs (non-runtime)
LP-9	validation/	D-P	PHPUnit suite + support constants
LP-10	docs/	D-P	developer-guide, acceptance, runtime-validation
LP-11	schemas/config/	D-P	platform.yml, platform.lock, extensions JSON schemas

---

Physical layout (platform repository — normative target)

zaixos-engineering-platform/
├── composer.json                    # name: zaixos/engineering-platform
├── CHANGELOG.md
├── core/
│   ├── constitution/                # LP-0
│   ├── methodology/                 # LP-1
│   └── boundaries/                  # symlink or copy of governance
├── contracts/                       # LP-2
│   ├── runtime-contracts.md
│   └── schemas/
├── runtime/
│   ├── specification/               # LP-3
│   ├── components/                  # LP-4
│   └── manifests/                   # LP-5
│       ├── schemas/
│       └── defaults/
├── adapters/
│   └── cursor-adapter-v1/           # LP-6
│       ├── profile.md
│       ├── manifest.json
│       └── workspace/
├── templates/                       # LP-7
├── knowledge/                       # LP-8
├── validation/                      # LP-9
│   ├── tests/
│   └── src/Support/
├── docs/                            # LP-10
└── schemas/config/                  # LP-11

---

Product-side layout (after installation)

product-repo/
├── composer.json                    # requires zaixos/engineering-platform
├── vendor/zaixos/engineering-platform/   # Composer install source
├── .zaixos/
│   ├── platform.yml                 # D-R declarative config
│   ├── platform.lock                # D-R exact pin
│   ├── platform/                    # Materialized snapshot OR symlink → vendor
│   ├── extensions/
│   │   ├── manifest.yml
│   │   ├── procedures/
│   │   ├── workflows/
│   │   ├── agents/
│   │   ├── rules/
│   │   └── knowledge/
│   └── adapters/
│       └── cursor-adapter-v1/
│           └── workspace/           # Canonical adapter tree
├── .cursor/                         # Mount → .zaixos/adapters/cursor-adapter-v1/workspace
└── app/                             # D-R product domain (unchanged)

---

Materialization strategy (TDR-002)

Mode	When	.zaixos/platform/ source
Vendor reference	Default (PHP/Composer)	Symlink vendor/zaixos/engineering-platform → .zaixos/platform
Snapshot copy	CI without symlinks; air-gap	Copy at install + checksum in lock
Submodule	Transitional dual dev	Submodule at lock SHA → .zaixos/platform

Products MUST NOT edit files under .zaixos/platform/ except via platform upgrade.

---

Adapter package coupling

Adapters are bundled inside zaixos/engineering-platform for v1 — not separate Composer packages.

Attribute	Value
Adapter selection	platform.yml → adapter.id
Adapter files	adapters/{id}/ inside platform package
Future	Optional zaixos/adapter-cursor-v1 package — Experimental; requires TDR amendment

---

Validation package

Attribute	Value
Location	validation/ inside platform package
Entry	vendor/bin/phpunit with config path documented in developer guide
Public command	php artisan test --testsuite=EngineeringRuntimePlatform (product wires) or documented PHPUnit path
Autoload	PSR-4 Zaixos\Platform\Validation\ → validation/src/

Validation ships with platform; products invoke, never fork.

---

Templates and knowledge packages

Package	Runtime coupling	Merge
Templates	Referenced by methodology; not IDE-native	Copied to product docs path on request only
Knowledge	Documentation only; no auto-constraint	Optional copy to .zaixos/extensions/knowledge/

Templates never import product modules. Knowledge never depends on adapter hook scripts.

---

Composer package manifest (normative fields)

{
  "name": "zaixos/engineering-platform",
  "type": "library",
  "version": "1.0.0",
  "description": "ZAIXOS Engineering Platform — methodology, contracts, adapters, validation",
  "license": "proprietary",
  "require": {
    "php": "^8.2"
  },
  "autoload": {
    "psr-4": {
      "Zaixos\\Platform\\Validation\\": "validation/src/"
    }
  },
  "extra": {
    "zaixos": {
      "platformVersion": "1.0.0",
      "contractMajor": 1,
      "adapters": ["cursor-adapter-v1"],
      "configSchemas": {
        "platformYml": 1,
        "platformLock": 1,
        "extensionsManifest": 1
      }
    }
  }
}

---

Package release artifact

Every platform release ships:

Artifact	Format
Git tag	zaixos-platform@vX.Y.Z
Composer dist	Packagist or VCS dist
Checksum manifest	SHA-256 of adapter workspace + default manifests
Compatibility matrix	Markdown in docs/releases/vX.Y.Z.md

---

Forbidden package contents

Forbidden	Reason
app/Modules/	Product domain (AR-01)
Product PHPUnit tests	Product CI
Uncertified adapter IDs	Certification gate
Modified contract obligations without contracts@N+1	Contract freeze

---

Package Architecture v1.0 — Phase 12-3.