AIKernel-NET
diff --git a/‎docs/architecture/18.DSL_PIPELINE_AND_ROM_SPEC-jp.md‎
Lines changed: 257 additions & 0 deletions b/‎docs/architecture/18.DSL_PIPELINE_AND_ROM_SPEC-jp.md‎
Lines changed: 257 additions & 0 deletions
@@ -0,0 +1,257 @@
+---
+updated: 2026-06-04
+published: 2026-06-04
+version: "0.0.3"
+edition: "Draft"
+status: "Implementation"
+issuer: ai-kernel@aikernel.net
+maintainer: "拓也（AIKernel プロジェクト メンテナー）"
+---
+
+# DSL Pipeline and ROM Specification
+
+この文書は、AIKernel.Core に実装された標準 DSL pipeline 形式と
+DSL ROM 実行モデルを定義する。
+
+DSL は C# ソースコードではない。JSON で表現された構造化 Semantic IR である。
+AI が生成した計画は、検証され、決定論的な `ResultStep` pipeline に compile され、
+不変 ROM 素材として保存され、再利用可能な capability として呼び出せる。
+
+---
+
+## 1. 設計規則
+
+- DSL は構造化データであり、実行コードではない。
+- root node は必ず `Pipeline` である。
+- すべての loop は有限である。`LoopUntil` も `maxIterations` を必須とする。
+- 未知の node type、未知の capability、不正な ROM 名、不正な field は fail-closed する。
+- `Map` projection は replay node を増やさない。実行された DSL node と loop transition は `ResultStep` replay entry として観測される。
+- Suspend は決定論的な停止点であり、background wait ではない。
+
+---
+
+## 2. JSON Node Schema
+
+### 2.1 Pipeline
+
+```json
+{
+  "type": "Pipeline",
+  "steps": []
+}
+```
+
+`steps` は必須で、pipeline node の配列でなければならない。
+
+### 2.2 Step
+
+```json
+{
+  "type": "Step",
+  "name": "start"
+}
+```
+
+`Step` は決定論的な実行 node を記録する。外部 capability は呼び出さず、現在の DSL pipeline value をそのまま引き継ぐ。
+
+### 2.3 CallCapability
+
+```json
+{
+  "type": "CallCapability",
+  "name": "Observe",
+  "args": {
+    "mode": "summary"
+  }
+}
+```
+
+`name` は `IDslCapabilityRegistry` で解決できなければならない。`args` は任意。
+指定する場合は JSON object とする。文字列値は文字列として保持され、非文字列値は JSON text として渡される。
+
+### 2.4 Loop
+
+```json
+{
+  "type": "Loop",
+  "maxIterations": 3,
+  "body": [
+    { "type": "CallCapability", "name": "Observe" },
+    { "type": "CallCapability", "name": "Decide" }
+  ]
+}
+```
+
+`maxIterations` は 0 以上の整数でなければならない。各反復は `body` を実行し、
+その後 `loop_iteration` と `loop_decision` を持つ loop transition delta を記録する。
+
+### 2.5 LoopUntil
+
+```json
+{
+  "type": "LoopUntil",
+  "timeout": "00:00:10",
+  "maxIterations": 10,
+  "body": [
+    { "type": "CallCapability", "name": "Observe" }
+  ]
+}
+```
+
+`timeout` は必須で、秒数または `TimeSpan` 文字列で指定できる。
+`maxIterations` も必須である。これは clock が timeout に到達しない場合でも
+loop を有限に保つためである。各 transition は `loop_iteration`、
+`loop_decision`、可能な場合は `loop_timestamp` を記録する。
+
+### 2.6 Suspend
+
+```json
+{
+  "type": "Suspend",
+  "reason": "user_approval"
+}
+```
+
+`Suspend` は semantic delta kind `suspend` を持つ suspended `ResultStep` を返す。
+Resume は別の実行フェーズであり、前回の replay log を因果記録として扱う。
+
+---
+
+## 3. 完全な例
+
+```json
+{
+  "type": "Pipeline",
+  "steps": [
+    { "type": "Step", "name": "start" },
+    {
+      "type": "Loop",
+      "maxIterations": 2,
+      "body": [
+        { "type": "CallCapability", "name": "Observe" },
+        { "type": "CallCapability", "name": "Decide" }
+      ]
+    },
+    { "type": "Suspend", "reason": "user_approval" },
+    { "type": "CallCapability", "name": "ExecutePlan" }
+  ]
+}
+```
+
+compile flow:
+
+```text
+JSON DSL
+  -> DslDocument.FromJson
+  -> IDslPipelineCompiler.Compile
+  -> IKernelPipeline.Execute
+  -> ResultStep + ReplayLog + ReplayLogHash
+```
+
+---
+
+## 4. DSL ROM
+
+AI が生成した DSL は不変 ROM 素材として保存し、capability として再利用できる。
+
+### 4.1 VFS Path と Capability Name
+
+実装上の VFS path は次の形式である。
+
+```text
+rom/dsl/{namespace}/{name}.json
+```
+
+呼び出し可能な capability name は次の形式である。
+
+```text
+dsl://{namespace}/{name}
+```
+
+`namespace` と `name` は、どちらも normalize 済みの単一 path segment でなければならない。
+`dsl://agent/nested/plan1` のような nested capability name は拒否される。
+
+### 4.2 Save / Load Flow
+
+```text
+SaveDslAsRomAsync(namespace, name, jsonDsl)
+  -> DSL を parse / compile
+  -> SHA-256 ROM hash を計算
+  -> VFS に未存在なら JSON を保存
+  -> 既存 path の内容が異なる場合は拒否
+  -> DslRomSnapshot を IDslRomRegistry に登録
+```
+
+load には expected ROM hash が必要である。VFS の内容が expected hash と異なる場合、
+load は fail-closed する。
+
+### 4.3 DSL ROM の呼び出し
+
+```json
+{
+  "type": "CallCapability",
+  "name": "dsl://agent/plan1"
+}
+```
+
+`DslRomCapabilityRegistry` は ROM snapshot を解決し、metadata を検証し、
+compile 済み inner pipeline を実行し、その `DslPipelineValue` を返す。
+ROM 呼び出しは replay metadata にも記録される。
+
+---
+
+## 5. Replay and Metadata
+
+DSL 実行は、node execution、loop transition、capability call、suspend point、
+DSL ROM call の semantic delta を記録する。
+
+安定 ROM metadata key は次の通り。
+
+| Key | 意味 |
+| --- | --- |
+| `dsl_rom_hash` | JSON DSL 内容の SHA-256 hash。 |
+| `dsl_rom_call` | `dsl://agent/plan1` などの capability name。 |
+| `dsl_rom_path` | `rom/dsl/agent/plan1.json` などの VFS path。 |
+| `dsl_rom_namespace` | ROM namespace。 |
+| `dsl_rom_name` | ROM name。 |
+| `dsl_rom_replay_log_count` | inner ROM pipeline が生成した replay entry 数。 |
+| `dsl_rom_replay_log_hash` | inner ROM pipeline が生成した replay hash。 |
+
+これらにより、どの DSL ROM が実行され、どの inner pipeline replay が outer execution に畳み込まれたかを証明できる。
+
+---
+
+## 6. Failure Rules
+
+次の条件は fail-closed する。
+
+- 空または非 object の DSL JSON。
+- `Pipeline` 以外の root node。
+- 未知の node type。
+- 必須 field の欠落または型不一致。
+- 負の `maxIterations` または負の `timeout`。
+- compile 時の未知 capability name。
+- capability registry の例外。
+- capability が successful null value を返す場合。
+- DSL pipeline value の key / value が不正な場合。
+- DSL ROM hash mismatch。
+- 同じ ROM capability へ異なる内容を再登録する場合。
+- 不正な DSL ROM capability name。
+
+---
+
+## 7. Host Integration Notes
+
+Server/API host は AI system が JSON DSL を提案することを許可してよいが、
+再利用可能 capability として扱う前に、host 側で検証し DSL ROM として保存しなければならない。
+browser/WASM client は trusted ROM を直接書き込まず、server boundary を呼び出すべきである。
+
+外部 module 連携では、assembly 参照 Provider、process-backed adapter、`dsl://` ROM capability
+へ name を route する `IDslCapabilityRegistry` を登録する。registry が境界であり、
+Core は provider 実装を知らない。
+
+---
+
+# 変更履歴
+
+- v0.0.3 (2026-06-04): 標準 DSL pipeline と DSL ROM 仕様を追加。