Production Composition カタログ¶

参考訳（非正本）: この文書は英語版 catalog/README.md の日本語参考訳です。正本は英語版であり、内容または解釈に相違がある場合は英語版が優先されます。

catalog.json は、この composition revision で利用可能な production component authority と recipe authority の閉じた inventory です。

各 component ID は components/<component-id>/component.json に、各 recipe ID は recipes/<recipe-id>.json に解決されます。catalog の配列は重複せず辞書順に並び、validation では物理的な authority directory / file と正確に一致することが要求されます。

Consumer 向け選択ガイド¶

recipe は、言語、framework、rendering strategy、deployment platform ではなく、作成する artifact の種類から選択します。browser-facing product では optional capability を選ぶ前に Website と Web application の選び方 を参照してください。

Website と Web application の区別は product identity の判断です。static generation、server rendering、client rendering、CDN hosting、runtime の有無は recipe を決めません。documentation、publishing、institutional information など document navigation が中心なら website、task/state/action-oriented browser product なら webapp を選びます。

具体的な zero-to-one Website path は Website product walkthrough を参照してください。Website contract、browser proof、product evidence を Webapp-private な surface/state semantics と分離したまま進めます。

optional application capability は、外部から見える product の挙動に基づいて選択します。必要な capability を直接 include すれば、Composer が dependency を推移的に解決します。

browser-facing artifact であることだけでは capability.runtime、capability.web-interface、capability.pwa、capability.webmcp は必要になりません。statically generated Website は optional component なしで website recipe を使えます。CDN-hosted stateful SPA も runtime component なしで webapp recipe を使えます。capability.webmcp の選択は MCP、MCP Apps、runtime、service、capability.web-interface を意味しません。runtime-bound capability、PWA capability、WebMCP capability は product が実際にその挙動を公開するときだけ追加します。

lifecycle component は product workflow に応じて選択します。skill recipe は各 lifecycle level を独立して公開します。website と webapp recipe は contract evolution と implementation evidence を baseline に含み、lifecycle.release-bundle を top-level release choice として公開します。

リポジトリトポロジの選択¶

明示的なマルチブランチまたは projection 構造が必要な場合にリポジトリトポロジを選択します。未選択は明示的なリポジトリトポロジがないことを意味するだけであり、local checkout や worktree の layout については何も示しません。

Workspace / local-checkout の選択¶

repository が local checkout の materialization 方法を宣言する場合は workspace component を選択します。これは repository topology とは独立しています。workspace 未選択は local-checkout topology の宣言がないことを意味し、default filesystem layout を意味しません。

最小 Website は空の include list を使用し、foundation.web、Website contract、implementation-evidence / contract-evolution support を受け取りますが、PWA/runtime/release material は含みません。

{
  "schema_version": 1,
  "recipe": "website",
  "components": {"include": [], "exclude": []},
  "parameters": {}
}

最小 Web application も空の include list を使いますが、shared Web foundation に加えて Webapp-private な application route、surface、UI state を受け取ります。

{
  "schema_version": 1,
  "recipe": "webapp",
  "components": {"include": [], "exclude": []},
  "parameters": {}
}

PWA Website は artifact identity を変えず PWA を明示的に選択します。

{
  "schema_version": 1,
  "recipe": "website",
  "components": {
    "include": ["capability.pwa"],
    "exclude": []
  },
  "parameters": {}
}

完全な Composition release lifecycle を使う Webapp は top-level release component だけを選択します。release readiness は component selection 自体ではなく、その後に得られる evidence と gate によって成立します。

{
  "schema_version": 1,
  "recipe": "webapp",
  "components": {
    "include": ["lifecycle.release-bundle"],
    "exclude": []
  },
  "parameters": {}
}

Composition release lifecycle を使用しない runtime-backed Website/Webapp は runtime を独立して選択できます。例:

{
  "schema_version": 1,
  "recipe": "website",
  "components": {
    "include": ["capability.runtime"],
    "exclude": []
  },
  "parameters": {}
}

MCP Apps UI を公開し、完全な release workflow を使用する Skill では、最上位の2つだけを要求できます。resolver が prerequisite を追加します。

{
  "schema_version": 1,
  "recipe": "skill",
  "components": {
    "include": ["capability.mcp-apps", "lifecycle.release-bundle"],
    "exclude": []
  },
  "parameters": {}
}

Webapp v3 から v4 への upgrade¶

artifact.webapp-core v4 では artifact dependency closure が変わるため、既存の managed Webapp が v3 から移行する場合は明示的な component-version compatibility boundary を越えます。ordinary update ではなく upgrade を使用してください。

v3 が推移的に選択していた完全な release lifecycle を repository で維持する場合、v4 の upgrade configuration で lifecycle.release-bundle を明示的に include する必要があります。release execution / evidence / bundle behavior が不要なら include せず、apply 前に upgrade plan を確認してください。

v3 の release contract file は seed material だったため、release lifecycle を deselect する upgrade でも Composer は consumer-owned bytes を自動削除せず保存します。apply 後に保存されている contracts/release-execution.json、contracts/release-evidence.json、contracts/release-bundle.json は v4 baseline では登録済み contract ではありません。contract registry は closed なので、consumer がこれらを contracts/ 外へ archive するか削除するまで validation は失敗します。この cleanup は consumer-owned です。

repository に同名の lifecycle file が残っているだけで release validator が選択されることはありません。selection authority は .template-composition/lock.json の resolved component set です。

apply の前に plan を使い、正確に解決された component closure と materialized file action を確認してください。直接選択可能な component の machine-readable source of truth は recipe descriptor です。

Closure rules¶

Production catalog validation は次を保証します。

• descriptor / recipe / schema が妥当であること。
• component source file の宣言が正確であること。
• dependency / conflict の target が存在し、dependency graph が非巡回であること。
• generic capability / lifecycle / topology / workspace が artifact-specific authority から独立していること。
• recipe reference が妥当で、required / default / optional selection が互いに素であること。
• 登録された contract ID、document path、schema path が repository 全体で一意であること。
• 登録された各 contract document / schema / migration を1つの component が所有すること。
• contracts/manifest.json に対する generated owner が一意であること。
• 解決済み contract_registrations から manifest が deterministic に render されること。
• 解決可能なすべての production component が少なくとも1つの materialized file を所有すること。
• material destination が portable で単一 owner を持つこと。
• production Skill、Website、Webapp composition の materialized validation が成功すること。

catalog は source authority であり、consumer material でも execution-hook registry でもありません。

Composer はこの閉じた source graph を検証し、1つの正確で clean な Git revision に対して recipe と consumer configuration を解決し、initial materialization が成功した後に得られた component / file closure を .template-composition/lock.json に書き込みます。Generated material は allowlist に含まれる declarative generator ID を通じてのみ dispatch されます。

unmanaged target では initial composition は managed-state transition を推測せず、既存の composition lock がある場合は拒否します。既存の managed repository では update が normalized intent を維持して descendant revision へ進み、upgrade が recipe/component/parameter/version の明示的変更を受け取ります。どちらも汎用 merge engine ではなく、local 変更された managed / generated material や ownership transition は fail closed します。

コンポーネントロールと直接選択¶

recipe は1つの artifact を選択し、optional な capability、lifecycle、topology、または workspace component を公開します。foundation role の component は artifact component の依存関係です。自動解決され、recipe option には現れず、consumer が直接 include する target でもありません。repository topology と workspace の選択は独立した axis であり、それぞれ高々1つの component を選択できます。六つの role のメンタルモデルは Composition concepts を参照してください。