ZAIXOS Engineering Platform — Extension Architecture

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

---

Purpose

Define the technical merge architecture for product extensions — registry structure, precedence, materialization merge algorithm, and validation binding.

---

Extension graph

                    ┌──────────────────────┐
                    │   Platform Core       │
                    │   (immutable @ pin)   │
                    └──────────┬───────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ Default         │  │ Adapter         │  │ Extension       │
│ Manifests       │  │ Template        │  │ Registry        │
│ (platform)      │  │ (platform)      │  │ (product)       │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                     │                     │
         └─────────────────────┼─────────────────────┘
                               ▼
                    ┌──────────────────────┐
                    │ Materialization       │
                    │ Merge Engine          │
                    └──────────┬───────────┘
                               ▼
                    ┌──────────────────────┐
                    │ Effective Runtime     │
                    │ View (read-only)      │
                    └──────────────────────┘

---

Registry architecture

Single registry file: .zaixos/extensions/manifest.yml

Extension type	Slot path	Registry key
Procedure	.zaixos/extensions/procedures/{id}/SKILL.md	extensions.procedures[]
Workflow	.zaixos/extensions/workflows/{id}/SKILL.md	extensions.workflows[]
Delegate	.zaixos/extensions/agents/{role}-agent.md	extensions.delegates[]
Rule	.zaixos/extensions/rules/{priority}-{name}.mdc	extensions.rules[]
Knowledge pack	.zaixos/extensions/knowledge/{pack-id}/	extensions.knowledgePacks[]

Unregistered files: Ignored at materialization; flagged as validation warnings (errors on release branches).

---

Merge precedence (normative)

Stage 1: Platform constraint rules (categories A–G) — full set from adapter template
Stage 2: Product extension rules — categories C–G only; append, never override A–B
Stage 3: Platform default procedures, workflows, delegates — from adapter template
Stage 4: Product extension procedures, workflows, delegates — append by ID
Stage 5: Platform enforcement hooks — unchanged; extensions cannot disable
Stage 6: Context providers — platform defaults; product extensions add providers only if schema allows (v1: platform-only)
Stage 7: Execution config — platform adapter cli/environment.json; product cannot override fail-closed flags

---

Merge algorithm (logical)

INPUT: platformPin, adapterTemplate, extensionManifest, productExtensionFiles

1. LOAD adapter workspace template → workingTree
2. VALIDATE extensionManifest against JSON schema
3. FOR EACH registered rule:
     ASSERT category NOT IN (A, B)
     COPY file to workingTree.rules/ (adapter-relative path mapping)
4. FOR EACH registered procedure/workflow/delegate:
     ASSERT id NOT IN platformDefaultIds
     COPY artifact to mapped adapter path
5. FOR EACH registered knowledgePack:
     COPY to .zaixos/extensions/knowledge/ (not auto-injected as constraints)
6. RUN enforcement handler manifest parity check
7. WRITE workingTree → .zaixos/adapters/{id}/workspace/
8. CREATE ide mount
9. COMPUTE checksum → return MaterializationResult

---

ID namespace

Prefix	Owner	Example
Platform defaults	D-P	skill-architecture, workflow-phase-implementation
Product extensions	D-R	skill-product-compliance-review
Forbidden	Product	Same ID as platform default

Collision → validation fail closed.

---

Extension limits (enforced at validation)

Type	Soft warn	Hard max
Procedures	15	20
Workflows	8	10
Delegates	8	10
Rules	4	5
Knowledge packs	—	500 KB each

---

Extension validation architecture

Stage	Check
Schema	manifest.yml valid
Path	Each entry file exists
Contract	Each artifact cites Runtime*Contract
Scope	Rules pass category gate
Uniqueness	No platform ID collision
Forbidden actions	Delegates/procedures include escalation + forbidden list
Core integrity	Zero diff vs vendor core for platform paths

Tests: ExtensionSchemaTest, ManifestParityTest (platform validation package).

---

Extension lifecycle (technical)

Author artifact locally
    → Register in manifest.yml
    → Run materialization (refresh effective view)
    → Run validation
    → Product architect review (scope)
    → Commit manifest + artifacts
    → CI validation on PR

Removal: delete artifact + manifest entry + rematerialize — no platform version bump.

---

Anti-patterns (technical enforcement)

Pattern	Detection
Vendor core edit	Checksum diff vs package
Unregistered file	Directory scan vs manifest
Rule category A–B	Frontmatter parser in validation
Missing contract citation	Regex/structured header check

---

Future extension points (v2+ — not v1)

Point	Status
CLI plugins	Experimental
Custom validation rules	Rejected for v1 — platform owns tests
Second adapter mount	Separate mount config block

---

Extension Architecture v1.0 — Phase 12-3.