ZAIXOS Engineering Platform — Configuration Architecture

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

---

Purpose

Define the configuration hierarchy, precedence rules, schema ownership, and validation binding for all platform configuration artifacts in product repositories.

---

Configuration layers

Layer	File	Mutability	Owner	Purpose
L-C0	Platform release defaults	Immutable at pin	D-P	Bundled in package
L-C1	.zaixos/platform.yml	Product editable	D-R	Declarative intent
L-C2	.zaixos/platform.lock	Product editable (controlled)	D-R	Exact pin + checksum
L-C3	.zaixos/extensions/manifest.yml	Product editable	D-R	Extension registry
L-C4	Composer composer.json require	Product editable	D-R	Fetch mechanism
L-C5	IDE session state	Ephemeral	D-T	Not platform config

---

Configuration hierarchy diagram

┌─────────────────────────────────────┐
│ L-C0 Platform release defaults       │  (in vendor/package)
└─────────────────┬───────────────────┘
                  │ constrains
┌─────────────────▼───────────────────┐
│ L-C1 platform.yml                    │  versionConstraint, adapter id, mounts
└─────────────────┬───────────────────┘
                  │ pinned by
┌─────────────────▼───────────────────┐
│ L-C2 platform.lock                   │  exact versions + checksum (authoritative)
└─────────────────┬───────────────────┘
                  │ extended by
┌─────────────────▼───────────────────┐
│ L-C3 extensions/manifest.yml         │  registered product extensions
└─────────────────────────────────────┘

---

Precedence rules

Conflict	Resolution
lock vs yaml version	lock wins on production branches; CI warns on yaml/lock drift
extension vs platform constraint	Platform constraints A–B always win
extension vs default manifest ID	Platform default wins on ID collision — validation fails
adapter mount path vs default	yaml mount wins if certified path schema valid
composer vs lock	Must match — validation fails if diverged

---

Schema versioning

Schema	Field	Current version
Platform config	configSchema in platform.yml	1
Platform lock	lockSchemaVersion	1
Extensions	schemaVersion in manifest.yml	1
Adapter metadata	schemaVersion in manifest.json	1

Schema MAJOR bump → platform MAJOR + migration guide.

---

Configuration validation pipeline

Load platform.yml → JSON Schema validate
Load platform.lock → JSON Schema validate
Cross-validate lock satisfies yaml
Load extensions manifest → JSON Schema validate
Verify registered paths exist
Verify extension IDs unique vs platform defaults
Emit ConfigValidationReport

Bound to VALIDATION_ARCHITECTURE.md ConfigSchemaTest.

---

Environment dimensions

Dimension	Config source	Notes
Production release branch	lock exact + failClosed true	Required
Development branch	yaml constraint may float	lock warning allowed
CI	Same as target branch policy	Invokes validation suite
Local IDE	Reads materialized mount only	No platform.yml hot reload

---

Sensitive configuration

Data	Storage	Rule
API keys	Not in platform config	Product .env
Clinic IDs	Product config	Not platform
Platform checksums	platform.lock	Integrity only
Adapter paths	platform.yml	Public

---

Feature flags (Experimental)

Optional block in platform.yml:

experimental:
  gitTemplateBootstrap: false
  cliAutoMaterialize: false
  orgTeamRulesBridge: false

Experimental flags default false. Production CI must not require Experimental flags.

---

Configuration ownership boundaries

Action	Allowed actor
Create platform.yml	Product integrator
Bump platform.lock	Product integrator + validation green
Add extension entry	Product developer + architect review
Edit vendor platform files	Forbidden
Disable validation.failClosed	Forbidden on release branches

---

Relationship to materialization

Materialization reads:

1. platform.lock → versions
2. platform.yml → mount strategy, adapter id
3. extensions/manifest.yml → merge set

Output updates platform.lock.checksum and materializedAt.

---

Configuration Architecture v1.0 — Phase 12-3.