ZAIXOS Engineering Platform — Public API Architecture

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

---

Purpose

Define the technical shape of the Public API — how classification maps to paths, schemas, entrypoints, and consumer integration — complementing governance classification without duplicating policy.

---

API surface layers

┌─────────────────────────────────────────────────────────┐
│ Consumer Integration Layer (product repo)               │
│  platform.yml · platform.lock · extensions/manifest.yml │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│ Public Entrypoints Layer                                 │
│  validation command · materialization contract · docs    │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│ Public Artifact Layer                                    │
│  contracts · methodology · templates · adapter profile   │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│ Internal Implementation Layer (not consumer-facing)      │
│  validation/src · hook scripts · CI scripts              │
└─────────────────────────────────────────────────────────┘

---

Public path registry (technical)

Path pattern	Class	Consumer access
core/methodology/*	P	Read
contracts/*	P	Read
runtime/manifests/schemas/*	P	Read
runtime/manifests/defaults/*	P	Read
adapters/{certified-id}/profile.md	P	Read
adapters/{certified-id}/manifest.json	P	Read
adapters/{certified-id}/workspace/**	P	Materialized copy
templates/**	P	Read / copy
docs/developer-guide.md	P	Read
validation/tests/*Test.php	P	Execute via PHPUnit
schemas/config/*.json	P	Validate against
.zaixos/platform.yml	P	Product write
.zaixos/platform.lock	P	Product write
.zaixos/extensions/manifest.yml	P	Product write

---

Non-public paths (forbidden for product config reference)

Path	Class
validation/src/Support/*	I
Adapter hook *.py internals as API	I
Platform release scripts	I
Draft docs pre-acceptance	I

---

Schema-public surfaces

All Public config files validate against JSON Schema in schemas/config/:

Schema file	Target
platform-yml.schema.json	.zaixos/platform.yml
platform-lock.schema.json	.zaixos/platform.lock
extensions-manifest.schema.json	.zaixos/extensions/manifest.yml
adapter-manifest.schema.json	adapters/*/manifest.json

Schema files are Public — field additions follow semver rules in EVOLUTION_MODEL.md.

---

Entrypoint stability

Entrypoint	Stability	Documented in
PHPUnit suite EngineeringRuntimePlatform	Stable per platform MAJOR	developer-guide
Materialization sequence	Stable per platform MAJOR	RUNTIME_MATERIALIZATION
Config schemas v1	Stable for platform 1.x	PLATFORM_CONFIGURATION_REFERENCE

Experimental entrypoints (zaixos CLI) are not Public until promoted.

---

Adapter public surface (technical)

Products integrate adapters only via:

1. platform.yml → adapter.id
2. Materialized workspace at configured mount
3. adapter.manifest.json validated by ContractComplianceTest

No PHP API to adapter in v1 — file materialization only.

---

Extension public surface (technical)

1. Register in manifest.yml
2. Place files in declared slot paths
3. Pass ExtensionSchemaTest

Extensions do not receive semver from platform — product owns extension content versioning informally via Git.

---

API change detection (implementation guidance)

Platform CI SHOULD:

• Diff Public path registry vs previous release tag
• Fail MAJOR release if Public path removed without ADR
• Emit DEPRECATED notices in validation output for Deprecated catalog items

---

Consumer contract (technical enforcement)

Products at Public API level MUST:

Requirement	Enforced by
Pin exact lock on release branches	ConfigSchemaTest + CI policy
Run Layers 0–5 on PR	CI
No vendor core edits	ChecksumIntegrityTest
Extensions registered	ExtensionSchemaTest
No contract text forks	ContractComplianceTest + review

---

Public API Architecture v1.0 — Phase 12-3.