Production catalog architecture¶

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

production catalog は、production Composition component と recipe に対する source-authority boundary を閉じます。supported consumer composition に参加する canonical component descriptor と recipe を定義しますが、具体的な consumer repository を自ら resolve または materialize するものではありません。

Authority¶

catalog/catalog.json が inventory authority です。full descriptor や recipe を複製するのではなく、canonical document が deterministic repository path に存在する component ID と recipe ID を列挙します。

catalog は意図的に closed です。

catalog component IDs == components/*/component.json identities
catalog recipe IDs    == recipes/*.json identities

catalog に列挙されていない component directory や recipe file は invalid であり、canonical file を持たない catalog entry も同様に invalid です。

Component source closure¶

copy される managed または seed material では、materials[].source は component directory からの relative path です。production component は conventional な files/ subtree を使用し、その subtree 配下のすべての regular file は、ちょうど1つの copied material によって宣言されなければなりません。

これにより、undeclared file が偶発的に authority を持つことを許さず、component source content を closed set として review できます。

Dependency graph¶

Catalog validation は dependency reference が存在することと production graph が acyclic であることを要求します。generic capability/lifecycle descriptor は artifact-specific component に depend または conflict してはなりません。foundation component は複数の artifact identity に必要な shared mandatory base を提供し、recipe から直接選択するのではなく dependency closure で到達します。

これは source-graph validation であり、具体的な consumer resolution ではありません。Composer は別途、recipe、explicit consumer include/exclude intent、parameters、conflicts、transitive dependency closure を適用し、consumer-specific な component set を1つ導出します。

Recipe validation¶

すべての production recipe は catalog 内の artifact を1つ指定し、capability/lifecycle selection には catalog 内のものだけを使用します。required/default/optional group は pairwise disjoint です。foundation component は recipe selection ではありません。artifact が foundation を require し、Composer が推移的に解決します。

skill recipe は意図的に default application capability を持ちません。これにより minimal Agent Skill が維持され、runtime と public interface は暗黙に materialize されるのではなく opt-in になります。

website と webapp recipe はどちらも artifact dependency を通じて shared foundation.web を解決しますが、sibling な artifact identity のままです。website は Website-owned な page structure、document metadata、discovery、Website evidence semantics を追加します。webapp は application-specific route、surface、UI state、Webapp evidence semantics を追加します。static generation、server rendering、client rendering、CDN hosting、runtime selection、PWA selection は、この2つの artifact recipe の判定条件ではありません。

どちらの browser-facing recipe も application capability は optional のままです。artifact baseline は reusable implementation evidence を要求し、そこから contract evolution が推移的に追加されます。一方、lifecycle.release-bundle は明示的な top-level release selection として公開されます。したがって runtime selection と release selection は独立した consumer intent です。capability.pwa も artifact-neutral な optional capability であり、artifact identity を変えず website / webapp のどちらからも選択できます。

Webapp の compatibility history として、artifact.webapp-core v4 では release lifecycle が baseline から分離されました。以前の v3 Webapp は complete release chain を推移的に受け取っていました。v4 upgrade でその挙動を維持したい場合は lifecycle.release-bundle を明示的に選択し、選択しない場合は Webapp evidence baseline のみになります。

Portable destination ownership¶

resolved production selection では、各 materialized destination に portable owner が1つ存在しなければなりません。validation は portable ASCII path identity について destination を case-insensitive に比較し、file/directory-prefix collision を reject します。

現在のすべての production recipe について maximal selection がこの invariant に対して regression-tested され、公開されているすべての optional capability と complete transitive lifecycle closure を含みます。foundation、artifact、capability、lifecycle component、recipe のいずれを追加する場合も、同じ ownership rule を保持しなければなりません。

Catalog と consumer resolution¶

production catalog と Composer は異なる responsibility を持ちます。catalog は利用可能な source graph が closed かつ internally valid であることを証明します。Composer はその validated graph を recipe と consumer intent とともに受け取り、1つの deterministic resolved closure を計算し、copied/generated bytes を materialize し、結果となる managed state を .template-composition/lock.json に記録します。

new repository では、initial composition が explicit consumer configuration から lock を導出します。existing managed repository では、update は lock schema version 2 にすでに保存された normalized intent を再利用し、upgrade は compatibility-boundary change のための explicit replacement intent を受け取ります。planning は read-only のままで、apply が managed state を mutate する前に complete target closure と lock preview を生成します。

したがって lock が記録するのは concrete resolution であり、第2の source catalog ではありません。その consumer state について、exact Composition source revision、normalized consumer intent、recipe/component descriptor identity、materialized destination ownership/digest を bind します。validator dispatch は disk 上に残っている file から intent を推測するのではなく、この resolved component set を使用します。

完全な authority / ownership model については Composition model を、resolution、managed reconciliation、transaction、recovery behavior については Composer architecture を参照してください。