ZAIXOS Engineering Platform — Validation Architecture

Document type: Technical Specification
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Owner: D-V (definitions D-P, invocation D-R)

---

Purpose

Define validation layers, test suites, gates, failure semantics, and reporting — enforcing Contracts First and Validation First without implementing PHPUnit code.

---

Validation principles

ID	Principle
V-01	Validation depends on Contracts — not adapter internals as authority
V-02	Fail closed on release branches
V-03	Platform owns test definitions; product owns CI wiring
V-04	Products must not skip or weaken platform tests
V-05	Validation output is machine + human readable
V-06	Architecture tests (product modules) are parallel suite — not merged into platform package

---

Validation layers

Layer 0: Config schema validation     (platform.yml, lock, extensions)
Layer 1: Contract reference validation (citations, implementedContracts)
Layer 2: Manifest parity               (counts, IDs, schemas)
Layer 3: Adapter workspace validation  (files exist, paths match profile)
Layer 4: Extension validation          (limits, categories, collisions)
Layer 5: Checksum integrity            (lock vs materialized workspace)
Layer 6: Product architecture tests    (module boundaries — product repo)

Layers 0–5 ship in platform package. Layer 6 is product-owned.

---

Validation flow

Trigger (local dev | CI PR | pre-release)
    │
    ├─► Load platform.lock + paths
    │
    ├─► Layer 0: ConfigSchemaTest
    │       FAIL → stop, emit report
    │
    ├─► Layer 1: ContractComplianceTest
    │       FAIL → stop
    │
    ├─► Layer 2: ManifestParityTest
    │       FAIL → stop
    │
    ├─► Layer 3: AdapterWorkspaceTest
    │       FAIL → stop
    │
    ├─► Layer 4: ExtensionSchemaTest
    │       FAIL → stop
    │
    ├─► Layer 5: ChecksumIntegrityTest
    │       FAIL → stop
    │
    ├─► Layer 6: Product CI invokes tests/Architecture/ (optional parallel)
    │
    └─► Emit ValidationReport → pass | fail

---

Public test catalog (platform 1.0)

Test class	Layer	Validates
ConfigSchemaTest	0	YAML/JSON schemas
ContractComplianceTest	1	Contract files + adapter manifest
ManifestParityTest	2	Default counts vs workspace
AdapterWorkspaceTest	3	Required paths per adapter profile
ExtensionSchemaTest	4	manifest.yml + limits
ChecksumIntegrityTest	5	lock.checksum vs workspace

Suite name (product phpunit.xml): EngineeringRuntimePlatform

Integrity test (product): EngineeringRuntimePlatformIntegrityTest — may wrap or duplicate public entry; transitional in Dental Clinic repo.

---

Gate matrix

Gate	Local dev	PR CI	Release branch
Layer 0–5	Required	Required	Required
Layer 6	Recommended	Required	Required
failClosed	Recommended	Required	Required
Manual acceptance checklist	Phase completion	—	Platform upgrade MAJOR

---

Failure propagation

Layer fail	CI	Merge	Release
Any Layer 0–5	Red	Block	Block
Layer 6	Red	Block	Block
Warning (soft limit)	Yellow	Allow dev; block release	Block release

No partial pass on release branches when validation.failClosed: true.

---

Validation report structure

ValidationReport
├── status: pass | fail | warn
├── platformPin: { version, adapter, contractMajor }
├── layers: [
│     { id, name, status, durationMs, failures[] }
│   ]
├── failures: [
│     { layer, code, message, path, remediation }
│   ]
└── generatedAt: ISO8601

Runtime Implementation attaches report to Format A/B ERP reports.

---

Recovery procedures

Failure code	Remediation
CONFIG_DRIFT	Align lock with composer; refresh yaml
CONTRACT_MISSING	Rematerialize; verify package version
MANIFEST_COUNT	Restore adapter template; check extensions
WORKSPACE_GAP	Rematerialize adapter
EXTENSION_COLLISION	Rename product extension ID
CHECKSUM_MISMATCH	Rematerialize; revert manual .cursor/ edits
RULE_CATEGORY_AB	Remove or recategorize extension rule

---

Validation evolution

Change	Version impact
New non-breaking check	Platform MINOR
New required check	Platform MINOR + CHANGELOG
Removed check	Platform MAJOR or deprecation cycle
Stricter extension limit	Platform MINOR

See EVOLUTION_MODEL.md.

---

Relationship to execution pipeline

Validation runs:

1. After materialization (install/upgrade)
2. Before Architecture Review acceptance (phase gate)
3. On CI for every PR touching .zaixos/, .cursor/, or platform dependency

Does not replace Architect RESPONSE_TEMPLATE — human acceptance remains required.

---

Validation Architecture v1.0 — Phase 12-3.