Refactor# — Contract Purity
Summary / 概要
This RFC proposes a contract-purity refactoring before ABI stabilization.
The main goal is to remove mutation and processing responsibilities from contract objects and move them into explicit service interfaces.
本 RFC は、ABI 固定前に行う Contract Purity のためのリファクタリング提案です。
主な目的は、Contract オブジェクトから mutation と処理責務を排除し、それらを明示的な service interface へ移動することです。
Motivation / 背景
Several current contracts include methods that imply mutation, normalization, transformation, or processing.
This creates a risk that immutable contract objects become active processors, making ABI stabilization harder and increasing the chance of later breaking changes.
現在の一部 Contract には、mutation、正規化、変換、処理責務を示唆するメソッドが含まれています。
このまま ABI を固定すると、不変であるべき Contract オブジェクトが処理主体になり、後から破壊的変更が必要になる可能性があります。
Primary Target / 主対象
IMaterialContract
Current concern:
Normalize()Structurize()
These methods place transformation behavior directly inside the contract.
懸念点:
Normalize()Structurize()
これらは Contract 自体に変換処理の責務を持たせています。
Proposed Direction / 提案方針
1. Keep contracts immutable
Contract interfaces should represent immutable views of system state or material.
Contract interface は、システム状態や素材の不変 view を表現するものに寄せます。
Example direction:
IMaterialContract
- metadata
- identity
- content reference
- semantic attributes
- hash / version information
Not:
- normalization
- structuring
- mutation
- parsing side effects
2. Move transformations into services
Transformation logic should be moved into dedicated services.
変換処理は専用 service interface へ移動します。
Candidate interfaces:
IMaterialNormalizerIMaterialStructurizerIMaterialCanonicalizerIMaterialHashProvider
候補:
IMaterialNormalizerIMaterialStructurizerIMaterialCanonicalizerIMaterialHashProvider
3. Review adjacent contracts
The following interfaces should be reviewed for hidden mutation or mixed responsibilities:
IContextCollectionIConversationStore- material-related DTO / contract interfaces
以下の Interface についても、暗黙の mutation や責務混在がないか確認します。
IContextCollectionIConversationStore- Material 関連 DTO / Contract interface
Acceptance Criteria / 完了条件
IMaterialContract no longer exposes mutation or processing methods.- Transformation behavior is moved into dedicated service interfaces.
- Contract objects become immutable views or immutable descriptors.
- No contract object is responsible for modifying itself.
- Tests and docs are updated accordingly.
- Migration guidance is added if public identifiers change.
IMaterialContract から mutation / processing メソッドが除去されている。- 変換処理が専用 service interface に移動している。
- Contract オブジェクトが不変 view または不変 descriptor として整理されている。
- Contract オブジェクトが自己変更の責務を持たない。
- テストとドキュメントが更新されている。
- 公開識別子が変更される場合は移行ガイドが追加されている。
Out of Scope / 対象外
- Implementing full material processing logic
- Implementing CacheDB
- Implementing Governance
- Runtime optimization
- Material 処理ロジックの完全実装
- CacheDB 実装
- Governance 実装
- Runtime 最適化
Notes / 補足
This RFC is a prerequisite for ABI stabilization.
Contracts define boundaries.
Boundaries must not mutate themselves.
本 RFC は ABI 固定前の前提作業です。
Contract は境界を定義する。
境界は自分自身を変化させてはならない。
Refactor# — Contract Purity
Summary / 概要
This RFC proposes a contract-purity refactoring before ABI stabilization.
The main goal is to remove mutation and processing responsibilities from contract objects and move them into explicit service interfaces.
本 RFC は、ABI 固定前に行う Contract Purity のためのリファクタリング提案です。
主な目的は、Contract オブジェクトから mutation と処理責務を排除し、それらを明示的な service interface へ移動することです。
Motivation / 背景
Several current contracts include methods that imply mutation, normalization, transformation, or processing.
This creates a risk that immutable contract objects become active processors, making ABI stabilization harder and increasing the chance of later breaking changes.
現在の一部 Contract には、mutation、正規化、変換、処理責務を示唆するメソッドが含まれています。
このまま ABI を固定すると、不変であるべき Contract オブジェクトが処理主体になり、後から破壊的変更が必要になる可能性があります。
Primary Target / 主対象
IMaterialContractCurrent concern:
Normalize()Structurize()These methods place transformation behavior directly inside the contract.
懸念点:
Normalize()Structurize()これらは Contract 自体に変換処理の責務を持たせています。
Proposed Direction / 提案方針
1. Keep contracts immutable
Contract interfaces should represent immutable views of system state or material.
Contract interface は、システム状態や素材の不変 view を表現するものに寄せます。
Example direction:
IMaterialContractNot:
2. Move transformations into services
Transformation logic should be moved into dedicated services.
変換処理は専用 service interface へ移動します。
Candidate interfaces:
IMaterialNormalizerIMaterialStructurizerIMaterialCanonicalizerIMaterialHashProvider候補:
IMaterialNormalizerIMaterialStructurizerIMaterialCanonicalizerIMaterialHashProvider3. Review adjacent contracts
The following interfaces should be reviewed for hidden mutation or mixed responsibilities:
IContextCollectionIConversationStore以下の Interface についても、暗黙の mutation や責務混在がないか確認します。
IContextCollectionIConversationStoreAcceptance Criteria / 完了条件
IMaterialContractno longer exposes mutation or processing methods.IMaterialContractから mutation / processing メソッドが除去されている。Out of Scope / 対象外
Notes / 補足
This RFC is a prerequisite for ABI stabilization.
Contracts define boundaries.
Boundaries must not mutate themselves.
本 RFC は ABI 固定前の前提作業です。
Contract は境界を定義する。
境界は自分自身を変化させてはならない。