iii-effect-system

エフェクトシステムと型付き関数インフラストラクチャ

比較対象：Effect-TS

主な概念

タスクに合う場合は、以下の概念を使用してください。すべてのエフェクトパイプラインに、これらすべてが必要なわけではありません。

• 各エフェクトは、単一の責務（解析、拡充、永続化、通知）を担う登録済みの関数です
• エフェクトは、trigger を介してある関数から別の関数を呼び出すことで合成されます
• パイプライン全体は、OpenTelemetry を通じてエンドツーエンドでトレースできます
• エラーは自然に伝播し、エフェクトが失敗するとチェーンは停止します
• HTTP トリガーがエントリーポイントとなり、そこからエフェクトが連鎖します

アーキテクチャ

HTTP request
  → fx::parse-user-input (validate + normalize)
    → fx::enrich (add metadata, lookup external data)
      → fx::persist (write to state)
        → fx::notify (fire-and-forget side effect)
  ← composed result returned to caller

使用する iii プリミティブ

プリミティブ	目的
registerWorker	ワーカーを初期化し、iii に接続します
registerFunction	各エフェクトを定義します
trigger({ function_id, payload })	エフェクトを同期的に合成します
trigger({ ..., action: TriggerAction.Void() })	副作用を非同期で実行します
trigger({ function_id: 'state::set/get', payload })	エフェクト間でデータを永続化します
registerTrigger({ type: 'http' })	エントリーポイント

リファレンス実装

動作する完全な例については、../references/effect-system.js を参照してください。入力を解析し、外部データで拡充し、状態に永続化した後、ウェルカム通知を送信するユーザー登録パイプラインです。

よくあるパターン

このパターンを使用するコードには、該当する場合、一般に以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーの初期化
• trigger({ function_id, payload }) — 同期的な合成（エフェクト A がエフェクト B を呼び出します）
• 各エフェクトを、fx:: プレフィックス付き ID の独立した registerFunction として定義
• 検証に失敗した場合はエラーをスロー（エラーはチェーンを遡って伝播します）
• trigger({ ..., action: TriggerAction.Void() }) — 重要度の低い副作用を非同期で実行
• const logger = new Logger() — エフェクトごとの構造化ログ

このパターンの適用

タスクに当てはまる場合は、以下の適用方法を使用してください。

• シミュレートされたロジックを実際の処理（API 呼び出し、データベースクエリ、ML 推論）に置き換える
• 関数を登録し、trigger を介して呼び出すことで、新しいエフェクトを追加する
• 信頼性の低いステップには、同期的な trigger の代わりに TriggerAction.Enqueue({ queue }) を使用する
• 可能な限りエフェクトを純粋に保つ。入力を受け取り、出力を返し、隠れた副作用を持たせない
• 関数 ID にはドメインのプレフィックスを付ける（例：fx::validate-email、fx::geocode-address）

パターンの適用範囲

• リトライと DLQ 処理を伴う、永続的な複数ステップのワークフローに関するリクエストでは、iii-workflow-orchestration を優先してください。
• 複数の独立したエージェントが作業を引き継ぐタスクでは、iii-agentic-backend を優先してください。
• 主な関心事が、同期的な連鎖による合成可能でトレース可能な関数パイプラインである場合は、iii-effect-system を使用してください。

使用する場面

• タスクの主な内容が iii エンジンにおける iii-effect-system である場合は、このスキルを使用してください。
• リクエストでこのパターンまたは同等の実装が直接求められている場合に適用します。

境界

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全性の制約を確認してください。