DSL 3.1 台本診断・安全停止 設計レビュー

文書の位置付け

• 対象Issue: #201
• 実装Issue: #198
• 親Issue: #200
• 状態: 2026-08-03承認済み。本文の「提案」は#198の実装仕様として採用する
• 対象バージョン: kamishibai DSL 3.1

この文書は、#198ですでに存在する未コミット差分を含め、DSL 3.1の台本診断をどこまでJavaScript機能拡張へ担当させるかを実装前に決めるためのものです。

1. 解決する問題

現在のDSL 3.1では、Scratchで実装されたパーサーが台本を処理します。正常な台本は実行できますが、異常な台本では次の問題があります。

• 未知のコマンドが検出されない、または後続処理で間接的に失敗する
• Asset ManagerやRuntime Expressionの例外で、そのScratch threadだけが終了することがある
• 台本の物理行番号と原文が失われ、利用者が修正位置を特定できない
• 一部のloopや入力listenerが残り、停止したことが画面から分かりにくい
• invalidScript表示は原因を区別せず、開発者向け情報も不足する

#198では、少なくとも次の6種類を詳しく表示して安全に停止する必要があります。

1. 非対応のkamishibaiバージョン
2. 非対応のトップレベルコマンド・アクションコマンド
3. asset=で指定したproject-localアセットアドレスを解決できない場合
4. setSkin、poseなどから未定義アセット名を参照した場合
5. 未定義シーンへの遷移
6. Runtime Expressionで評価する式の文法エラー

2. 非目標

DSL 3.1安定化では、次を行いません。

• ScratchパーサーをJavaScriptで全面的に置き換える

• DSL 3.1の構文やコマンドを追加・変更する

• 4.0用のStoryDocument、Object Store、Iteratorを先行実装する

• 複数エラーの回復処理や、エラー後の途中再開を実装する

• 汎用Diagnostic Overlayの公開APIを#198の中で確定する

• 外部URLのネットワーク障害、カメラ権限拒否など、今回の6種類以外を網羅する

  3.1用実装は、3.1の寿命を安全に延ばす互換パッチです。4.0のパーサー基盤には流用しません。

3. 現在の処理境界

現在は、startStoryを受けたStageのScratch scriptがTemporary Variablesのscriptを読み、Scratchのlistとcustom blockを使って次の処理を行います。

flowchart LR
  A["外部または埋め込み台本"] --> B["runtime variable: script"]
  B --> C["Scratch parser"]
  C --> D["assetList / actorList / sceneList"]
  D --> E["Scratch runtime executor"]
  C -->|失敗| F["generic invalidScript"]
  E -->|extension例外| G["該当threadが停止"]

Scratchパーサーは実行用listを作るための正本です。しかし、各行をlistへ変換した後には物理行番号が残りません。

4. 選択肢

5. 提案する全体構成

JavaScript側は「実行用データを生成しない限定preflight」とします。正常時の実行は、従来どおりScratchパーサーだけが担当します。

flowchart LR
  A["script取得"] --> B["3.1 Preflight Scanner"]
  B -->|成功| C["既存Scratch parser"]
  C --> D["既存Scratch executor"]
  B -->|Diagnostic| E["Diagnostic Presenter"]
  E --> F["安全停止"]
  C -->|既存invalidScript| G["3.1 Runtime Error Adapter"]
  G --> E

6. Diagnosticのデータモデル

3.1では最初のfatal errorを一つだけ返します。小学生の利用者へ同時に多数のエラーを表示しないためです。修正後に再実行すると、次のエラーを表示します。

{
  severity: 'fatal',
  code: 'K31-SCENE-REF-001',
  phase: 'preflight',
  messageKey: 'diagnostic.undefinedScene',
  args: {scene: 'missing-scene'},
  source: {
    line: 12,
    column: 1,
    text: 'action=keyInputToChangeScene:ArrowRight:missing-scene'
  },
  technicalDetail: 'scene label was not found in the declaration pass'
}

7. 限定的な二重化の管理

限定preflightでも、Scratchパーサーと次の情報が重複します。

• トップレベルcommand名
• global action名
• actor action名
• 各actionのどの引数がasset・scene参照か

この重複を隠してはいけません。3.1では次の制約を設けます。

1. dsl31Contractという一つの宣言表へcommand/action/ref位置を集約する
2. scannerの条件分岐へcommand名を直接散在させない
3. 全対応command/actionの正常fixtureを用意する
4. Scratch runtimeがfixtureを実行でき、preflightも同じfixtureを受理することを検証する
5. コマンドリファレンスに存在する名前とcontractの差分をテストする
6. 3.1で新しいcommandを追加する場合、contractとfixtureの更新をDoDへ含める

このcontractは実行用ASTを定義しません。4.0のschemaへ発展させない、3.1専用の互換表です。

8. 外部機能拡張との境界

validateProjectAssetAddress({name, resourceId});
// => {ok: true, normalized}
// => {ok: false, type, label, message}

validateConditionSyntax(expression);
// => {ok: true}
// => {ok: false, position, message}

9. 実行タイミングと副作用

preflightはstartStoryを受け、既存のcontext削除、asset登録、actor生成、カメラ開始より前に一度だけ実行します。

sequenceDiagram
  participant S as Scratch startStory
  participant V as 3.1 Preflight
  participant P as Existing Scratch Parser
  participant U as Diagnostic Presenter

  S->>V: validate(script)
  alt success
    V-->>S: ok
    S->>P: existing parse and run
  else fatal diagnostic
    V-->>S: diagnostic
    S->>U: present and halt
    Note over S,P: parserへ進まない
  end

preflightは次の副作用を禁止します。

• Scratch list、runtime variable、Stage variableの変更
• asset登録・削除
• network access
• cache access
• broadcast
• clone生成
• renderer skin生成

SVG skin生成と停止処理は、validation成功・失敗が確定した後のPresenterだけが行います。

10. feature flag

起動時固定のStage variable featureDetailedScriptErrorsを使用し、既定値はfalseとします。

値は最初のstartStory時に一度だけ読み、そのproject実行中は固定します。再読込またはgreen flagより前の値変更だけを反映します。

11. 表示と安全停止

12. 現在の未コミット案に対する評価

13. テスト方針

14. ロールバック

• feature flag OFFで3.1.7相当の経路へ即時に戻せる
• app-local extensionとhidden blockを小粒PRでrevertできる
• Asset Manager／Runtime Expressionへ追加するsyntax-only APIは後方互換の追加APIとし、Kamishibai側revert後も既存blockへ影響させない
• 3.1.8公開後に重大な問題が見つかった場合は、3.1.8を上書きせずdeprecateし、修正版を新しいパッチバージョンで公開する

15. レビュー結果

2026-08-03に次の8項目を承認しました。この決定をもって#201のレビューゲートを解除し、#198は以下の制約内で再開できます。

実装中にこの責務境界を変更する必要が生じた場合は、#198へ理由と代替案を記録し、実装を進める前に本設計を再レビューします。