バージョニングとruntime discovery

現在の実行可能implementation snapshotはruntime/runtime-1.0.jsonに保存されています。ドキュメントではsemanticsをさらに詳しく説明できますが、toolingはこのmachine-readable snapshot（または接続中Hostのdiscovery）を実行可能なsupport listとして扱う必要があります。

iPhone Hostは、このsnapshotをmachine-readableなRuntimeDiscovery modelとして反映します。Relay/Conductorなど外部transportへ公開する場合も、別のfeature listを新たに作らず、そのmodelをserializeできます。

最初からversioningする理由

project schemaは、独立して進化するiPhone Host、AI tooling、Relay/Conductor integration、将来のWindows Builderで共有されます。versioningによって互換性を明示し、Runtimeが意図的に変わる場合のcontrolled migration boundaryを作れます。

すべてのprojectは次を宣言します。

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

同じmajor runtime/schema lineでは、additiveでbackward-compatibleな変更を優先します。major Runtime/schema releaseでは意図的なbreaking changeを含めても構いません。古い互換性のないmajorを対象とするprojectは、semanticsを暗黙に変更して実行するのではなくmigrationが必要です。

optional permission keyやadditiveなHost API/componentは、既存Projectを無効化せずschema/runtime 1.0内に追加できます。ただし新しいfeatureを使うProjectは、接続中Hostのruntime discoveryがそのfeatureを報告していることを要求する必要があります。

Migrationはbackup-firstです。以前のproject revisionを保存し、projectを変換し、完全なmigrated projectをvalidateしてからactive revisionを置換します。migrationに失敗した場合は以前のprojectを残します。migrationはdeterministic toolingやAI-assisted toolingで行えますが、受け入れ判断は常にApsule validationに基づき、AIの成功自己申告には基づきません。

Runtime discovery

接続中Hostは、おおむね次のようなmachine-readable descriptionを公開します。

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

実際のresponseでは最終的に、文字列だけでなくversionやschemaも含める必要があります。

Host API identifierは2 segmentより多くても構いません。たとえばApple Musicはmusic.player.playやmusic.history.recentlyPlayedTracksのようなoperationを報告します。toolingはすべてのAPIが正確にfamily.operation形式だと仮定せず、報告された完全なidentifierを比較する必要があります。namespace形式のidentifierでも、文書化されたnested objectを表す場合があります（例: legacy webView.cookies）。validatorはその互換性を保ちながら、新しいAPIではexact operation identifierを優先します。

Discoveryが重要な理由

AIやBuilderは、インストール済みHostがfeatureをsupportするか推測してはいけません。次の流れを使えます。

1. project requirementを確認する。
2. 接続中Hostへ問い合わせる。
3. 対応schema/component/style/Host APIを比較する。
4. 互換なproject featureだけを生成・編集するか、必要なHost upgradeを正確に報告する。

Validation

project実行前に、少なくとも次をvalidateします。

• schema version。
• required runtime version。
• route/view reference。
• 既知component type。
• 既知style key。
• 宣言済みHost API permission。
• script/fileの存在。
• malformed binding。
• 未対応required feature。

Validationは、COSやBuilderが自動修復できるよう、stable codeとpath/node IDを含むstructured errorを返す必要があります。

shared SDKがこのvalidation boundaryを実装します。validateProjectはstructuredなerrors[]とwarnings[]を返し、checkRuntimeCompatibilityはProjectのschema/runtime requirementを、checked-in runtime snapshotまたは接続中Host discoveryと比較します。toolingは無効なprojectをpackやsyncの前に拒否しなければなりません。