ZAIXOS Engineering Platform — Configuration Reference

Document type: Normative Configuration Reference
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Related: CONFIGURATION_ARCHITECTURE.md

---

Purpose

Normative field definitions for all platform configuration artifacts. Implementations MUST validate against these schemas.

---

.zaixos/platform.yml

Schema version: configSchema: 1

# Required root fields
configSchema: 1                    # integer, required, fixed 1 for platform 1.x
productId: string                    # required, kebab-case, e.g. dental-clinic-ros

platform:
  versionConstraint: string          # required, semver range on platform package, e.g. "^1.0"
  adapter:
    id: string                       # required, certified adapter ID, e.g. cursor-adapter-v1
    mount:
      canonical: string              # required, path relative to repo root
      ide: string                    # required, IDE read path, e.g. .cursor
      strategy: enum                 # required: symlink | copy

extensions:
  manifest: string                   # required, default .zaixos/extensions/manifest.yml

validation:
  suite: string                      # required, default EngineeringRuntimePlatform
  failClosed: boolean                # required, must true on release branches

experimental:                          # optional block
  gitTemplateBootstrap: boolean      # default false
  cliAutoMaterialize: boolean        # default false
  orgTeamRulesBridge: boolean        # default false

Field rules

Field	Constraint
productId	[a-z0-9-]+, max 64 chars
versionConstraint	Valid semver range; must accept locked version
adapter.id	Must exist in platform package extra.zaixos.adapters
mount.canonical	Must match pattern .zaixos/adapters/{adapter-id}/workspace
mount.ide	For cursor-adapter-v1: must be .cursor
failClosed	false allowed only on non-release branches (CI may warn)

---

.zaixos/platform.lock

Schema version: lockSchemaVersion: 1

lockSchemaVersion: 1

platform:
  version: string                    # required, exact semver X.Y.Z
  contractMajor: integer               # required, must match package extra
  package: string                      # required, zaixos/engineering-platform

adapter:
  id: string                           # required, matches platform.yml
  version: string                      # required, exact semver

materializedAt: string                 # required, ISO-8601 UTC
installMode: enum                      # required: composer | submodule | tarball

checksum:
  algorithm: enum                      # required: sha256
  adapterWorkspace: string             # required, lowercase hex digest

mountStrategy: enum                    # optional: symlink | copy (records effective)

Field rules

Field	Constraint
platform.version	Must equal composer-installed package version
contractMajor	Must equal 1 for platform 1.x
checksum.adapterWorkspace	SHA-256 of canonical workspace per RUNTIME_MATERIALIZATION
materializedAt	Updated on every successful materialization

---

.zaixos/extensions/manifest.yml

Schema version: schemaVersion: 1

schemaVersion: 1
productId: string                      # required, should match platform.yml

extensions:
  procedures:                          # array, max 20
    - id: string                       # skill-{name}, unique vs platform
      path: string                     # relative to repo root
      contractRef: string              # required citation
  workflows:                           # array, max 10
    - id: string                       # workflow-{name}
      path: string
      contractRef: string
  delegates:                           # array, max 10
    - id: string                       # delegate-{role}
      path: string
      contractRef: string
      readonly: boolean                # optional, default false
  rules:                               # array, max 5
    - id: string
      path: string
      category: enum                   # C | D | E | F | G only
      contractRef: string
  knowledgePacks:                      # array
    - id: string
      path: string                     # directory
      maxBytes: integer                # optional, default 512000

---

Adapter manifest.json (platform package)

Location: adapters/cursor-adapter-v1/manifest.json

{
  "schemaVersion": 1,
  "adapterId": "cursor-adapter-v1",
  "adapterVersion": "1.0.0",
  "platformCompatibility": "^1.0.0",
  "contractMajor": 1,
  "implementedContracts": [
    "RuntimeConstraintContract",
    "RuntimeProcedureContract",
    "RuntimeWorkflowContract",
    "RuntimeDelegationContract",
    "RuntimeEnforcementContract",
    "RuntimeContextProviderContract",
    "RuntimeExecutionContract",
    "RuntimeAdapterContract"
  ],
  "inventory": {
    "constraints": 9,
    "procedures": 10,
    "workflows": 10,
    "delegates": 10,
    "enforcementHandlers": 4,
    "contextProviders": 3,
    "executionModes": 4
  }
}

Inventory counts are locked for platform 1.x — change requires contracts@2.

---

Composer extra.zaixos (platform package)

{
  "platformVersion": "1.0.0",
  "contractMajor": 1,
  "adapters": ["cursor-adapter-v1"],
  "configSchemas": {
    "platformYml": 1,
    "platformLock": 1,
    "extensionsManifest": 1
  }
}

---

Example minimal product configuration

platform.yml:

configSchema: 1
productId: dental-clinic-ros
platform:
  versionConstraint: "^1.0"
  adapter:
    id: cursor-adapter-v1
    mount:
      canonical: .zaixos/adapters/cursor-adapter-v1/workspace
      ide: .cursor
      strategy: symlink
extensions:
  manifest: .zaixos/extensions/manifest.yml
validation:
  suite: EngineeringRuntimePlatform
  failClosed: true

platform.lock:

lockSchemaVersion: 1
platform:
  version: 1.0.0
  contractMajor: 1
  package: zaixos/engineering-platform
adapter:
  id: cursor-adapter-v1
  version: 1.0.0
materializedAt: "2026-06-28T00:00:00Z"
installMode: composer
checksum:
  algorithm: sha256
  adapterWorkspace: "0000000000000000000000000000000000000000000000000000000000000000"

extensions/manifest.yml (empty):

schemaVersion: 1
productId: dental-clinic-ros
extensions:
  procedures: []
  workflows: []
  delegates: []
  rules: []
  knowledgePacks: []

---

Platform Configuration Reference v1.0 — Phase 12-3.