ZAIXOS Engineering Platform — Runtime Materialization

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

---

Purpose

Define the materialization engine — how platform core, adapter templates, and product extensions become the effective IDE workspace — including mount strategies, checksums, and idempotent re-runs.

---

Materialization inputs

Input	Source	Required
Platform pin	platform.lock	Yes
Adapter ID	platform.yml + lock	Yes
Adapter template	adapters/{id}/workspace/ in package	Yes
Adapter metadata	adapters/{id}/manifest.json	Yes
Extension manifest	.zaixos/extensions/manifest.yml	Yes (may be empty)
Extension files	Paths in manifest	Per entry
Mount config	platform.yml platform.adapter.mount	Yes

---

Materialization outputs

Output	Path	Purpose
Canonical workspace	.zaixos/adapters/{id}/workspace/	Source of truth for adapter files
IDE mount	.cursor/ (cursor-adapter-v1)	IDE-native read path
Lock update	platform.lock.checksum, materializedAt	Integrity + audit
Report	MaterializationResult (future CLI)	Human + CI log

---

Materialization flow (detailed)

START
  │
  ├─► Load ResolvedPlatformPin from lock + yaml
  │
  ├─► Verify package version == lock.platform.version
  │
  ├─► Extract adapter template to staging/
  │
  ├─► Apply extension merge (EXTENSION_ARCHITECTURE algorithm)
  │
  ├─► Write staging/ → .zaixos/adapters/{id}/workspace/
  │
  ├─► Apply mount strategy:
  │     symlink: .cursor → .zaixos/adapters/cursor-adapter-v1/workspace
  │     copy:    recursive copy to .cursor/
  │
  ├─► Compute SHA-256 of canonical workspace (sorted file list, normalized line endings)
  │
  ├─► Compare to lock.checksum (if re-run) — warn on unexpected drift
  │
  ├─► Update platform.lock materializedAt + checksum
  │
END → MaterializationResult { success, checksum, fileCount, mountStrategy }

---

Mount strategies

Strategy	Value	When	IDE behavior
symlink	Default on Unix/macOS	Developer local	.cursor/ → canonical
copy	Windows without symlink rights; CI	Immutable CI checkout	.cursor/ is copy
direct	Forbidden for cursor-adapter-v1	—	Use canonical under .zaixos/ only

Lock records installMode and effective mountStrategy.

---

Idempotency

Re-running materialization with unchanged pin and extensions produces:

• Identical checksum (byte-stable template + deterministic merge order)
• Overwrite of workspace and remount
• No platform version change

Re-run required after:

• Platform PATCH/MINOR upgrade
• Extension manifest change
• Adapter version bump
• Mount strategy change

---

Materialization vs Runtime Contracts

Materialization implements contract inventory requirements:

Contract	Materialization obligation
RuntimeConstraintContract	All platform rules present in workspace
RuntimeProcedureContract	Default 10 + registered extensions
RuntimeWorkflowContract	Default 10 + registered extensions
RuntimeDelegationContract	Default 10 + registered extensions
RuntimeEnforcementContract	4 handlers present
RuntimeContextProviderContract	3 immediate-tier providers
RuntimeExecutionContract	cli.json, environment.json present
RuntimeAdapterContract	manifest.json parity

Materialization does not change contract text.

---

Drift detection

Drift type	Detection	Response
Manual edit to .cursor/ without rematerialize	Checksum ≠ lock	Validation fail; rematerialize
Edit to canonical workspace	Checksum ≠ lock	Validation fail
Vendor package update without lock bump	composer/lock mismatch	Validation fail
Extension file missing	ManifestParityTest	Validation fail

KPI-7: Zero undocumented drifts (SUCCESS_METRICS.md).

---

Multi-adapter future (v2+)

.zaixos/adapters/cursor-adapter-v1/workspace/  → .cursor/
.zaixos/adapters/claude-adapter-v1/workspace/  → .claude/  (future)

Only one primary adapter active per product pin in v1.

---

Materialization engine components (logical)

Component	Responsibility
PinResolver	lock + yaml → ResolvedPlatformPin
TemplateLoader	Read adapter workspace from package
ExtensionMerger	Registry merge algorithm
WorkspaceWriter	Atomic write to canonical path
MountManager	Symlink or copy IDE mount
ChecksumComputer	SHA-256 workspace hash
LockUpdater	Persist checksum + timestamp

Implementation deferred to Phase 12-5+ scaffold.

---

Failure modes

Error	Propagation	Recovery
Missing template file	Fail closed	Reinstall package
Extension schema invalid	Fail closed	Fix manifest
Mount permission denied	Fail with copy fallback	Retry copy strategy
Disk full	Fail closed	Free space; rematerialize
Partial write	Fail closed	Delete workspace; rematerialize

---

Runtime Materialization v1.0 — Phase 12-3.