ZAIXOS Engineering Platform — Technical Decision Records
Document type: Technical Decision Record Index
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Purpose
Record technical architecture decisions for ZEP — distinct from platform ADRs (governance/strategy). TDRs govern implementation shape; ADRs govern why the platform exists and boundary policy.
TDR index
| TDR | Title | Status |
|---|---|---|
| TDR-001 | Single Composer package | Accepted |
| TDR-002 | .zaixos/ canonical namespace | Accepted |
| TDR-003 | Adapters bundled in platform v1 | Accepted |
| TDR-004 | Symlink default IDE mount | Accepted |
| TDR-005 | Lock file authoritative on release | Accepted |
| TDR-006 | Single extension registry file | Accepted |
| TDR-007 | Six-layer validation model | Accepted |
| TDR-008 | SHA-256 workspace checksum | Accepted |
| TDR-009 | Idempotent materialization | Accepted |
| TDR-010 | No PHP Public API for products v1 | Accepted |
| TDR-011 | Human architect gate post-validation | Accepted |
| TDR-012 | Unified asset state machine | Accepted |
TDR-001 — Single Composer package
Status: Accepted · Phase: 12-3
Decision: Ship all logical packages (LP-0–LP-11) inside one Composer artifact zaixos/engineering-platform.
Rationale: Simplifies pin, validation, and extraction; matches ADR-005 primary distribution.
Consequences: Large package; future optional adapter split requires new TDR.
TDR-002 — .zaixos/ canonical namespace
Status: Accepted · Phase: 12-3 · Implements: ADR-004
Decision: All platform materialization lives under .zaixos/; IDE paths are mounts only.
Rationale: IDE neutrality; ten-year adapter additions without namespace churn.
TDR-003 — Adapters bundled in platform v1
Status: Accepted · Phase: 12-3
Decision: cursor-adapter-v1 ships inside platform package, not separate Composer package.
Rationale: Single pin, single checksum, simpler CI for v1 GA.
TDR-004 — Symlink default mount
Status: Accepted · Phase: 12-3
Decision: Default mount.strategy: symlink with automatic copy fallback.
Rationale: Preserves single canonical workspace; satisfies Windows edge cases.
TDR-005 — Lock file authoritative on release
Status: Accepted · Phase: 12-3
Decision: Production branches treat platform.lock as exact version authority over yaml constraint.
Rationale: Reproducible builds; semver range in yaml for dev only.
TDR-006 — Single extension registry file
Status: Accepted · Phase: 12-3
Decision: All extensions declared in .zaixos/extensions/manifest.yml only.
Rationale: Validation simplicity; no orphan files.
TDR-007 — Six-layer validation model
Status: Accepted · Phase: 12-3
Decision: Layers 0–5 platform-owned; Layer 6 product architecture parallel.
Rationale: Separates platform integrity from domain module tests.
TDR-008 — SHA-256 workspace checksum
Status: Accepted · Phase: 12-3
Decision: Store SHA-256 of canonical adapter workspace in platform.lock.
Rationale: Detect drift without diffing vendor; stable across platforms.
TDR-009 — Idempotent materialization
Status: Accepted · Phase: 12-3
Decision: Re-materialization with same inputs yields identical checksum.
Rationale: Safe CI rematerialize; predictable upgrades.
TDR-010 — No PHP Public API for products v1
Status: Accepted · Phase: 12-3
Decision: Products integrate via config + files + validation — not platform PHP classes.
Rationale: File-based integration matches adapter model; reduces coupling.
TDR-011 — Human architect gate post-validation
Status: Accepted · Phase: 12-3
Decision: Green validation necessary but not sufficient for phase acceptance — RESPONSE_TEMPLATE required.
Rationale: AI runtime executes; humans accept architecture.
TDR-012 — Unified asset state machine
Status: Accepted · Phase: 12-3
Decision: All platform assets use states in PLATFORM_STATE_MACHINE.md.
Rationale: Consistent lifecycle across docs, contracts, adapters, templates.
TDR index v1.0 — Phase 12-3.