Versioning and runtime discovery

The current executable implementation snapshot is stored in runtime/runtime-1.0.json. Documentation may explain semantics in more detail, but tooling must treat this machine-readable snapshot (or connected Host discovery) as the executable support list.

The iPhone Host mirrors this snapshot through a machine-readable RuntimeDiscovery model. External transport exposure (for example through Relay/Conductor) may serialize that model without inventing a second feature list.

Why version from day one

The project schema is shared by multiple independently evolving pieces: iPhone Host, AI tooling, Relay/Conductor integration and the future Windows Builder. Versioning makes compatibility explicit and gives Apsule a controlled migration boundary when the Runtime intentionally changes.

Every project declares:

{
  "schemaVersion": "1.0",
  "runtime": {
    "minimum": "1.0"
  }
}

Prefer additive, backward-compatible changes within the same major runtime/schema line. A major Runtime/schema release may intentionally contain breaking changes. Projects targeting an older incompatible major must be migrated rather than silently executed with changed semantics.

Optional permission keys and additive Host APIs/components may be added inside schema/runtime 1.0 without invalidating existing Projects. A Project that uses one of those newer features must still require a connected Host whose runtime discovery reports that feature.

Migration is backup-first: preserve the previous project revision, transform the project, validate the complete migrated project, and only then replace the active revision. A failed migration leaves the previous project intact. Migration may be performed by deterministic tooling and/or AI-assisted tooling, but acceptance is always based on Apsule validation rather than an AI claiming success.

Runtime discovery

The connected Host should expose a machine-readable description similar to:

{
  "runtimeVersion": "1.0",
  "schemaVersions": ["1.0"],
  "components": [
    "Text",
    "Button",
    "List",
    "Map"
  ],
  "styles": [
    "padding",
    "glass",
    "glassInteractive"
  ],
  "hostApis": [
    "http.request",
    "location.current",
    "bluetooth.scan"
  ]
}

The real response should eventually include versions and schemas rather than only strings.

Host API identifiers may contain more than two path segments. For example, Apple Music reports operations such as music.player.play and music.history.recentlyPlayedTracks. Tooling must compare the complete reported identifier rather than assuming every API is exactly family.operation. A reported namespace-style identifier may still represent a documented nested object (for example legacy webView.cookies); validators preserve that compatibility while preferring exact operation identifiers for new APIs.

Why discovery matters

AI and Builder should not guess whether an installed Host supports a feature. They can:

1. inspect the project requirements;
2. query the connected Host;
3. compare supported schema/components/styles/Host APIs;
4. generate or edit only compatible project features, or report the exact Host upgrade required.

Validation

Before a project is run, validate at least:

• schema version;
• required runtime version;
• route/view references;
• known component types;
• known style keys;
• declared Host API permissions;
• script/file existence;
• malformed bindings;
• unsupported required features.

Validation should return structured errors with stable codes and paths/node IDs so COS and Builder can repair them automatically.

The shared SDK implements this validation boundary. validateProject returns structured errors[] and warnings[], while checkRuntimeCompatibility compares the Project's schema/runtime requirements against either the checked-in runtime snapshot or connected Host discovery. Tooling must reject invalid projects before packing or synchronization.