ZAIXOS Engineering Platform — Dependency Model

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

---

Purpose

Define allowed dependencies between platform layers, products, adapters, validation, and knowledge — enforcing acyclic, downward-only coupling.

---

Dependency classes

Class	Symbol	Meaning
Depends	→	Requires presence or correctness of target
Implements	⊢	Fulfills obligations of target
Consumes	⇢	Reads Public surface only; no mutation
Invokes	↪	Runs tests or materialization
Forbidden	✕	Must never exist

---

Platform internal dependency graph

Governance (L0)     [no runtime deps]
    ↓ referenced by
Methodology (L1)    → Governance
    ↓
Contracts (L2)      → Methodology (citations only)
    ↓
Runtime Spec (L3)   → Contracts
Manifests (L3)      → Contracts + Runtime Spec
    ↓
Adapters (L4)       ⊢ Contracts
    ↓
Templates (L1/L7)   → Methodology + Contracts (citation)
Knowledge (L8)      → Methodology (optional cross-links)
    ↓
Validation (L6)     → Contracts + Adapter metadata + Config schemas
Materialization (L5)→ Core packages + Adapter + Extension schemas

Invariant: No edge from Adapter → Platform Core mutation. No edge from Validation → Adapter implementation internals (hooks source readable for parity only).

---

Product dependency graph

Product Application (app/, docs/architecture/)
    ⇢ Platform Public API
    → platform.lock (exact)
    → .zaixos/extensions/ (owned)
    ↪ Validation suite (platform-owned tests)
    ✕ Platform Core edit
    ✕ Contract text edit
    ✕ Adapter certification bypass

---

External dependencies (platform package)

Dependency	Allowed	Notes
PHP ^8.2	Yes	Validation suite runtime
PHPUnit	dev / bundled	Validation execution
Laravel	No	Platform is not application framework
Cursor	No	IDE is D-T; adapter only
Product modules	No	AR-01

---

Contract dependency rules

From	To	Rule
Contract	Adapter	Forbidden — contracts never reference adapter paths
Contract	Product	Forbidden
Adapter	Contract	Required — implementedContracts in manifest.json
Validation	Contract	Required — obligation checks
Installer	Contract	Required — materialization must satisfy counts
Extension	Contract	Required — each artifact cites contract section

---

Configuration dependencies

platform.yml
    → platform package (semver constraint)
    → adapter ID (must exist in package)
    → configSchema version (must match)

platform.lock
    → exact platform version
    → exact adapter version
    → contractMajor
    → checksum (adapter workspace)

extensions/manifest.yml
    → extension schema version
    → productId (informational)
    → registered artifact paths only

Lock depends on yaml: lock must satisfy yaml constraints. Yaml does not override lock in production branches.

---

Validation dependencies

Test suite	Depends on
ContractComplianceTest	contracts/, adapter manifest.json
ManifestParityTest	runtime/manifests/defaults/, materialized workspace
AdapterWorkspaceTest	adapters/{id}/workspace/
ExtensionSchemaTest	schemas/config/, .zaixos/extensions/
ConfigSchemaTest	platform.yml, platform.lock

Product architecture tests (tests/Architecture/) depend on product constitution — parallel suite, not platform package dependency.

---

Materialization dependencies

Materialization Engine
    → Platform core snapshot @ lock.version
    → Adapter template @ lock.adapter.version
    → Extension manifest (product)
    → Merge precedence (EXTENSION_ARCHITECTURE)
    → Filesystem (.zaixos/, mount)

Materialization does not depend on IDE session state.

---

Circular dependency prohibition

Cycle	Status
Platform → Product → Platform	Forbidden
Contract → Adapter → Contract definition	Forbidden (adapter implements, not defines)
Validation → Product code → Validation weaken	Forbidden
Extension → Core patch → Extension	Forbidden — use registry

Detection (implementation): Dependency graph lint in platform CI (Internal) — acyclic check on documented edges.

---

Version dependency resolution

platform.yml:  versionConstraint ^1.0
platform.lock: version 1.0.3 (exact)
composer.lock: zaixos/engineering-platform 1.0.3

Resolution order:
1. lock.platform.version (authoritative)
2. composer.lock must match lock
3. yaml constraint must accept lock version
4. adapter.version must satisfy adapter manifest platformCompatibility
5. contractMajor must equal package extra.zaixos.contractMajor

Mismatch → validation fail closed.

---

Submodule dependency (transitional)

.gitmodules → platform repo @ SHA
platform.lock → records same SHA as version identity
.zaixos/platform → submodule checkout

Submodule path deprecated after Composer GA + one release cycle (PLATFORM_PUBLIC_API.md).

---

Dependency matrix (summary)

Source	Target	Relationship
Product	Platform Public	Consumes
Product	Platform Core files	Read-only via vendor
Platform	Product	None
Adapter	Contract	Implements
Validation	Contract	Depends
Knowledge	Runtime native	None
Templates	Product	None
Installer	Contract + Config schema	Depends
Extensions	Extension schema	Depends
Extensions	Platform Core	No direct edit

---

Dependency Model v1.0 — Phase 12-3.