docs: consolidate design documentation and standardize crate English
This commit is contained in:
@@ -0,0 +1,31 @@
|
||||
# 正本・権限・実行の分離
|
||||
|
||||
## 正本と観測
|
||||
|
||||
永続的な判断の根拠は、その判断を所有する明示的な記録に置く。UIの表示、キャッシュ、通知、プロセスの生存情報は、正本を再確認するための観測として扱う。これらだけから操作の成功、作業の完了、権限の継続を推定しない。
|
||||
|
||||
永続化する情報と、現在の状態から再構成できる情報を分ける。別の所有者が管理する状態を複写して第二の状態機械を作ると、更新漏れと復旧時の不一致が生じる。親の処理は子の識別子を保持し、必要な時点で子の正本を読む。
|
||||
|
||||
## 権限と入力
|
||||
|
||||
操作権限は認証された主体、明示的な付与、対象資源の現在の制約から決定する。プロンプト、Profile名、表示名、cwd、ファイルの存在、ツールが見えることを権限の根拠にしない。別の操作経路を設けても、同じ所有者の検証を通す。
|
||||
|
||||
委譲では親が実際に委譲できる範囲を上限にする。読取り、書込み、コマンド実行、観測、レビュー、統合を混同しない。探索で対象を発見できても操作権限を得たことにはならない。
|
||||
|
||||
## 履歴とLLM入力
|
||||
|
||||
LLMの生成に影響する入力は、リクエストへ加える前に履歴へ確定し、永続化形式からリクエストを再構成できるようにする。揮発的な入力の差込みでは、後のターンから発言やツール呼出しの根拠を追えなくなる。
|
||||
|
||||
履歴は追記を基本とする。圧縮や保持範囲の変更は、明示的な境界と再構成規則を持つ処理に限定する。過去の記録を黙って書き換えず、キャッシュとトークン消費への影響をセッションの実測に基づいて判断する。
|
||||
|
||||
## 初期設定と実行処理
|
||||
|
||||
環境変数などの暗黙的なプロセス状態は、起動境界で明示的な入力へ変換する。通常の処理は解決済みの型付き設定を受け取り、実行中に環境を読み直して判断を変えない。秘密情報は明示的な参照で扱い、設定の説明や診断へ値を複製しない。
|
||||
|
||||
## 状態と操作の独立性
|
||||
|
||||
作業の結論、レビュー判断、コード統合、Worker停止、記録の保持、接続解除、資源削除は別の判断である。一つの成功を別の操作の許可として流用しない。自動的に連動させる場合は、その責任を持つ操作として条件と結果を定義する。
|
||||
|
||||
競合確認では、何を、どの観測と比較し、どの操作の前後で検査するかを名前と処理で示す。到着順や時刻で足りる処理に不透明な更新番号を加えない。内容の一致、同じ操作の再送、鍵の一致、接続の生存期間を確認する場合は、それぞれを識別する根拠を使う。
|
||||
|
||||
個別の永続操作と再試行の判断は[永続操作の原則](durable-operations.md)に従う。具体的な認証、保存、復旧の仕組みは所有moduleのドキュメントに置く。
|
||||
Reference in New Issue
Block a user