紙芝居アプリ 4.0 内部仕様書

固定実装の呼出し経路

前図を実装のexportとcomposition rootまで具体化すると、固定commit29c0deaでは次の経路になります。 この追跡は、同commitの公開rc.8 SB3をbaseにしたlocal previewを実行し、immutable sourceの稼働、 Version 4.0.0-rc.8のタイトル、invalid保存時の診断とcurrent integrity維持を観測した結果と 突き合わせています。

実画面ではsource frontendの成功結果がVALID: The current immutable source is running.として表示され、 reload監視はWatchingになります。versionを4.1へ変えた一時candidateはK4-VERSION-001でINVALIDとなり、 current integrityを更新しませんでした。画面との対応、撮影条件、固定した成果物hashは DSL 4.0 実装ビジュアル記録を参照してください。

正本の順序

1. 作者向け構造の正本はschema/dsl-4.schema.jsonです。
2. parse後の追加制約はsrc/dsl4/semantic-validator.jsと、注入されたRuntime Expression validatorが正本です。
3. runtime入力の正本はsrc/dsl4/story-document.jsが生成するStoryDocumentです。
4. 実行状態とeventの正本はsrc/dsl4/runtime-controller.jsです。
5. platform能力はsrc/dsl4/platform/のcomposition rootと各adapterが正本です。
6. preview candidateの切替はlive-reload-session.js、asset byteの切替はasset-reload-transaction.jsが正本です。

Schemaからruntime実装を生成したり、runtimeの受理状態からSchemaを逆生成したりはしません。 Schema、semantic validator、StoryDocument、runtimeの各境界を独立testで同期します。

実装から検証できる関係表

次表は上から下への主要呼出し方向です。「主要関数」は固定commitに存在するexport、 「確認test」はその境界を直接検証するfileです。

test/dsl4-architecture.test.mjsは、core import graphにnode:、DOM、Scratch VM、 platform moduleが侵入しないことを検査します。I/Oとplatform依存を注入するため、同じ StoryDocumentとruntime coreを複数surfaceで共有できます。

図と実装の追跡表

単一sourceの処理順

createDsl4SourceFrontend(schema, options)はSchemaをAJV 2020で一度compileし、parse()ごとに 次の順で処理します。

1. canonicalizeDsl4Sourceで改行とsource表現を規範化する。
2. UTF-8 byte上限を超えるsourceをYAML parse前にK4-SOURCE-LIMIT-BYTES-001で拒否する。
3. YAML 1.2 strict modeで、一つのtop-level mappingだけを読む。
4. alias、anchor、merge key、custom tag、prototype汚染につながるmapping keyを拒否する。
5. YAML node数、collection depth、scalar長を検査する。
6. JSON Schemaで構造、型、未知field、action形を検査する。
7. validateDsl4Semanticsで参照、asset kind、重複stable ID、scene・pose条件などを検査する。
8. scene数、action数、asset数と、branch式の構文・上限を検査する。
9. errorがなければcreateStoryDocumentでimmutable IRを生成する。

図: 失敗結果に部分的なStoryDocumentを含めず、成果物出力前に埋込み後のcomponentを再読込・再検証する build gate。

戻り値はdiscriminated resultです。成功時は{ok: true, canonicalSource, diagnostics, storyDocument}、失敗時は{ok: false, canonicalSource, diagnostics}です。失敗結果に部分的な StoryDocumentを載せないため、後段はokをstage gateとして使えます。

source frontendの既定上限はdsl4SourceFrontendDefaultLimitsに固定されています。

callerはこの値以下へだけ狭めます。未知のlimit名、上限より大きい値、非整数は起動時に拒否します。

Source Graph

createDsl4SourceGraph(entryPath, {readSource, limits})はassetを読まず、source topologyだけを作ります。 各nodeはsourceIdとsourcePathを同じlogical project-relative pathとして持ち、canonical source、 byte数、include edge、宣言、宣言元に対して解決したasset file pathを保持します。

既定上限dsl4SourceGraphDefaultLimitsは次のとおりです。

pathはproject rootから脱出できず、source suffixも検査します。cycleはK4-INCLUDE-CYCLE、 読込失敗はK4-INCLUDE-READ-001、同じnamespace・IDまたはsingletonの重複は K4-DECLARATION-DUPLICATEで停止します。orderはdependency order、discoveryOrderはentryを 先頭とする安定した発見順です。

createDsl4SourceGraphFrontend(sourceFrontend)はdsl4SourceIncludesがONのときだけ動作します。 各nodeへrestricted YAML policyを適用し、named declarationとsingletonを一つへ構成します。 root優先や後勝ち規則はありません。構成後のcanonical sourceにも明示上限を適用し、その後は単一sourceと 同じfrontendへ渡します。

included sourceの宣言位置は失われません。生成後のStoryDocument.sourceOriginsはstory pathごとに {sourceId, range}を持ち、runtime diagnosticはsourceOriginForStoryPath()で最も近い宣言元へ戻せます。

Schema、意味検証、式検証

検証境界は次のように分離します。

production compositionはcreateDsl4ProductionSourceFrontendが @kubohiroya/turbowarp-runtime-expression/compositionを注入します。独自parser、eval、 Functionへのfallbackはありません。preview、validate、buildはこのfrontend契約を共有します。

runtimeではresolveBranch()がaction contextのvariables snapshotをevaluateCondition()へ渡し、一つのbranchを 上から評価します。4.0.0-rc.8のsnapshotに含まれるのはトップレベルvariables:だけで、Stage／sprite変数、 Temporary Variables、controller status、pose eventをliveには読みません。

形とimmutability

createStoryDocument()はsource objectをcloneしてから再構成し、deepFreeze()した次のrootを返します。

{
  "kind": "StoryDocument",
  "version": "4.0",
  "metadata": {"sourceId": "project/story.k4.yml"},
  "assets": {},
  "actors": {},
  "cover": null,
  "textStyles": {},
  "speechStyles": {},
  "variables": {},
  "loading": null,
  "poseRecognition": null,
  "controls": null,
  "branches": {},
  "scenes": [],
  "sourceMap": {}
}

Source Graph経由ではさらにsourceOriginsが加わります。assetsはIDをkeyとし、compact記法も id、kind、name、delivery、loading、retentionを持つobjectへ正規化します。 既定のdeliveryはembedded、loadingはeager、retentionはpose modelだけscene、 その他はstoryです。

scenesは宣言順の配列です。各sceneは{kind: 'Scene', id, poseModel, posePreview, actions}、 各actionは次の形です。

YAML 1.2のmappingはrepresentation model上で順序を持ちません。DSL 4.0は固有規則として、source YAMLの serialization treeに現れるscenes pairの順序を通常実行のscene順とします。source frontendはYAML nodeの pair列、または全scene IDで同値な順序を保証する中間表現からStoryDocument.scenesを構築し、JSON Schema検証用の native objectが持つproperty列挙順を正本にしてはいけません。formatter、converter、serializerもscene keyを sortせず、parse、serialize、parseのround tripで同じpair順を保持します。

現行実装はDocument#toJS()後のscenesをObject.entries()で配列化するため、ECMAScriptのarray index相当の scene IDではsource順を失います。例えば"10"、"2"、"1"の順に宣言したsceneが"1"、"2"、 "10"の順になります。これは意図した契約ではなく既知の適合差です。toolはこの挙動を互換仕様として固定せず、 YAML nodeのpair順から正規化する実装へ置換します。

{
  "kind": "Action",
  "id": "/scenes/opening/actions/0",
  "target": "Hero",
  "command": "say",
  "args": {"text": "こんにちは"},
  "sourceRange": {}
}

custom actionだけhandler: 'custom'を持ち、明示された場合はstableIdも持ちます。idは StoryDocument内のstory pathであり、Scratch block IDではありません。

source位置

sourceMapはstory pathからcanonical sourceのSourceRangeへ対応します。SourceRangeは 1-originのline・columnと0-originのoffsetを持つstart・endです。診断は 作者向けpathに加え、利用できる場合はstoryPathを持ちます。included sourceでは sourceOriginsからlogical source pathを復元し、絶対machine pathを公開しません。

起動境界

createDsl4RuntimeStartup()は起動時に一度resolveDsl4FeatureFlags()を呼びます。 dsl4RuntimeがOFFならdependencyを初期化せずenabled: falseを返します。ONならpackaged componentを 検証し、hostが明示したsource・asset上限の下でStoryDocument、runtime artifact、asset bundleを読み、 createDsl4NavigationSession()へ渡します。

runtime environmentは次を提供します。

• port: action command名をkeyとするplatform operation
• assetLifecycle: prepare、setLoading、releaseAssets、release
• evaluateCondition: branch式評価
• inputArbitration: navigationと作品内inputの競合を一つのconsumerへ決める契約
• dispose(reason): environmentが所有する全resourceの冪等解放

sessionはenvironmentを単独所有します。session dispose時はnavigationを停止した後、environmentを解放し、 双方のcleanup失敗をAggregateErrorへまとめます。

RuntimeStatusとsnapshot

createDsl4RuntimeController()のRuntimeStatusはidle、running、paused、failed、 finished、stoppedです。公開snapshotはstatus、sceneId、actionIndex、actionPath、 generation、primitiveだけのvariables、失敗時のdiagnosticをdeep-freezeして返します。

図: start()、reposition()、quiesce、resume()、正常終了、失敗、停止の遷移。破線はterminal状態から 再度start()したときの再初期化を表します。

この図の主体は一つのRuntimeControllerです。「現在の一つのgenerationを、どのscene・action位置で どう再生しているか」だけを表します。source変更の有無、candidateの妥当性、作者がreloadを承認したかは RuntimeStatusへ混ぜません。それらは後述するLiveReloadSessionが別の状態として持ちます。

scene transitionはtarget sceneのlazy assetをprepareしてからtransitionTo()をpublishします。 scene commit後に不要なscene-retained assetを解放します。準備失敗時は現在sceneを置き換えません。

図: portが返す非同期operationの完了後だけaction.commitへ進みます。action、port、式、assetの失敗は current generationを無効化し、canonical diagnosticとruntime.failへ収束します。

RuntimeEvent

eventは{sequence, type, sceneId, storyPath, actionPath, generation, details}です。 sequenceはstartごとに0へ戻り、observerは実行意味を変更できません。onEventがthrowしてもruntimeは継続します。 主要typeは次です。

• lifecycle: runtime.start、runtime.resume、runtime.finish、runtime.fail、runtime.stop
• scene: scene.transition、scene.enter
• action: action.start、action.commit、action.cancel
• navigation: navigation.advance、navigation.reposition
• asset: assets.startup.start、assets.startup.ready、assets.preload.start、 assets.loading.show、assets.loading.hide、assets.scene.ready、assets.release
• reload boundary: runtime.quiesce

Action Context

coreが各actionへ渡すActionContextは次を持ちます。

generationとsignalの両方を検査するため、取消済みの非同期actionが遅れて完了しても変数やsceneをcommitできません。

custom actionは別の起動時flag dsl4CustomActionsEnabledで既定OFFです。 createDsl4ActionInvocationAdapter()がAction Registry Snapshot、Structured Dataのaction scope、 TurboWarp primary threadを一つのinvocationへ束ねます。invocationはrunningからcompleted、 transitioned、failed、cancelledのいずれかへ一度だけsettleします。既定timeoutは30秒です。

createDsl4ActionContextTurboWarpSurface()はunsandboxed TurboWarp hostへ、次の開発者blockを flag ON時だけ登録します。

• whenCustomAction
• currentActionName、currentActionTarget
• currentActionHasArgument、currentActionArgument
• completeCurrentAction、failCurrentAction、gotoFromCurrentAction

contextがないthread、二重settle、未知引数、不正goto、timeout、thread cleanup失敗は K4-CUSTOM-*診断へ変換されます。

build時のsnapshot

buildDsl4RuntimeComponent()は検証済みStoryDocumentが参照するlocal assetだけを loadDsl4LocalAssetSnapshot()で読みます。fileごとのbyte上限、件数、総byte数を明示し、 integrity付きassetBundle、sourceDescriptor、runtimeArtifactを作成します。base SB3へ埋め込んだ後、 loadDsl4RuntimeComponent()で同じ上限を使って再読込し、成功したbyteだけを返します。

file出力はbuildDsl4RuntimeComponentFile()がcandidate directoryを検証し、 installBundleTransactionally()で置き換えます。検証に失敗した途中SB3を最終出力へ残しません。

runtime prepareとretention

createDsl4EmbeddedAssetLifecycle()はasset IDごとにpending、ready、failedのcache entryを持ちます。 prepare()はasset materializeとplatform adapter prepareを行い、generationがstaleまたはsignalがabort済みなら 作成済みresourceを即座にreleaseします。

createDsl4AssetPreloadCoordinator()はasset kindを知らず、dependency indexに従って時期だけを調整します。

1. startupでcover、loading、actor、eager assetをprepareする。
2. scene開始前にそのsceneのlazy assetをprepareする。
3. pending中だけloading presentationを表示する。
4. 準備完了後にscene transitionをpublishする。
5. scene commitで次sceneに不要なretention: scene assetをreleaseする。
6. stop、failure、disposeで全resourceを逆所有順に解放する。

PoseモデルについてposeRecognition.modelInitialization.policyがlatest-neededの場合、preload coordinatorの 最新要求をTurboWarp TM 1.12.0 Compositionへ渡し、重い初期化をactive 1件＋最新pending 1件へ制限します。 superseded requestはasset lifecycleのAbortSignalでcancelし、registryへ公開しません。Aの実行中にB、Cが 要求された場合はBを開始せず、Aの安全な終了後にCだけを開始します。pose不要sceneへskipした場合はpendingを 破棄します。

camera lifecycleとmodel lifecycleは別の所有者です。getUserMedia()／video.play()はdescriptor探索、 decode、SHA検証、TensorFlow／PoseNet初期化と並行できます。未検証byte列をTensorFlowへ渡してはならず、 最初の推論でcamera readyとmodel registeredを同期します。model cancelだけでcameraを停止せず、stopまたは session disposeがcameraを解放します。既定値legacy／parallel: falseはこの最適化を無効化します。

poseRecognition.preview.overlayがある場合、hostは正規化済みの表示、joint style、bone style、最低confidence、 confidence連動をTurboWarp TM 1.12.0の公開Composition APIへ順番に適用します。overlay専用feature flagはありません。 camera canvas、2D context、推論readback、SVG要素はTurboWarp TMが所有し、hostはDOMやTensorFlow.js内部経路をpatchしません。

remote assetは自動的に許可しません。createDsl4RemoteAssetLifecycle()へhost loaderを明示注入した場合だけ 有効です。通常のposeModelはHTTPS directory URLからmodel.json、metadata.json、宣言されたweightsを lazy取得します。検証付きremoteはSHA-256 integrity、media type、sizeを再検証して同じlifecycleへ入ります。

source generation transaction

Web／CLI previewは安定読込を二回行い、source graphとasset manifestのfingerprintが一致した一式だけを generationとしてstageします。途中保存、sourceだけ新しい状態、assetだけ新しい状態はprotocolへ公開しません。 invalid candidateはdiagnosticだけを更新し、current runtimeを維持します。

createDsl4LiveReloadSession()の状態はwaiting、active、invalid、quiescing、pending、 failed、disposedです。

図: invalidはreload表示の状態であり、current runtimeを停止する状態ではありません。quiesceの安全性を 証明できない場合だけfailedへfail-closedします。

RuntimeStatusとの読み分け

二つの状態機械は階層が異なり、同じ時点に併存します。LiveReloadSession.getState()は外側の reload statusだけでなく、current.runtime.statusとして内側のRuntimeStatusも保持します。 UIやprotocolはこの二つを一つの状態へ平坦化してはなりません。

観点	RuntimeStatus	LiveReloadSession.status
状態を持つ主体	一つのRuntimeController	一つのLiveReloadSession
答える問い	current generationを今どう再生しているか	currentとcandidateの更新を今どう調停しているか
時間の単位	一回のstart()と、そのgeneration内のscene・action実行	source監視開始から複数generationのstage・defer・commitまで
主な入力	start、action完了、navigation、resume、stop、実行失敗	parse結果、candidate、quiesce token、作者のchoice、dispose
待機を表す状態	paused: current runtimeが再開可能な実行境界で停止	pending: candidateとreload planが揃い、作者の選択を待つ
failedの意味	action・port・式・assetなど、current generationの実行失敗	quiesceまたはcommitを安全に完了できず、更新調停をfail-closedした
正常終了・所有終了	finished: 作品の全action完了、stopped: currentの明示停止	disposed: currentとcandidateを含むreload session全体の所有・監視終了

特にactiveは「runtimeがrunning」という意味ではなく、current sessionを保持し、candidateがない というreload側の状態です。このため、作品が最後まで進んだ後もfinished + activeになり得ます。 同様に、invalidとfailedは二つの図で同じ失敗を重複表現しているのではありません。

代表的な時点	current.runtime.status	LiveReloadSession.status	二つを分ける理由
valid sourceを通常再生中	running	active	実行中であり、更新候補はない
保存したcandidateがinvalid	running	invalid	診断を表示しても、検証済みcurrentの再生は止めない
valid candidateを安全化中	running→pausedなど	quiescing	action cleanupとtoken確定を待つ間も、更新処理の進捗を別に示す
reload choice待ち	pausedまたはfinished	pending	currentの安全な位置と、candidate採用の意思決定を区別する
作品が正常終了、監視は継続	finished	active	再生完了後も次のsource変更を受け付けられる
current自体のaction実行が失敗	failed	active	実行失敗であり、reload transactionの失敗とは限らない
quiesce／commit安全性が破綻	stopped	failed	currentをfail-closed停止し、更新失敗の原因と所有状態を外側へ残す
previewを閉じる	currentなし	disposed	個別runtimeの状態ではなく、reload session全体のresource解放を表す

したがって、RuntimeStatus図だけではinvalid candidateを表示しながらcurrentを継続する契約を表せず、 LiveReloadSession図だけではscene・actionの進行、正常終了、実行失敗を表せません。安全なlive reloadは 「内側の実行状態」と「外側の世代交代状態」を同時に観測するため、二図を併記します。

1. 最初のvalid generationは新sessionを作り、先頭から開始してactiveにする。
2. 次のvalid generationはcandidate IDを発行し、current sessionへquiesce()を要求する。
3. Dsl4QuiesceTokenのscene、action、variables、generationを検証する。
4. reload plannerがstoryStart、currentScene、currentActionの可否とfallbackを決める。
5. defer()はcandidateを捨て、current sessionをresumeQuiesce()する。
6. commit()はnext sessionを先に生成し、currentを停止・解放してから選択位置でnextをstartする。

図: invalid、defer、commit、quiesce／commit failureを分けたsource generation transaction。candidateと currentの同時公開を避け、commit成功時だけgenerationとintegrityを切り替えます。

source session commitはcandidate生成前までcurrentを保持します。ただしcurrentを停止した後にnext startが 失敗した場合、停止済みcurrentへ暗黙rollbackはせずfailedにします。作者が明示的にrestartし、同じ失敗を 自動loopさせないのが安全側の契約です。

action quiesce

action handlerはfinish-onlyまたはcancel-replay-safeです。finish-onlyは現在actionが完了した次のdispatch境界で pauseします。cancel-replay-safeはactionをabortし、Structured Data scopeとplatform resourceのcleanup完了後、 同じactionを再実行できる境界をtoken化します。既定5秒、許容100 ms〜30秒のtimeoutを超えると K4-RELOAD-QUIESCE-TIMEOUTでruntimeをfail-closed停止します。

asset live reload transaction

createDsl4AssetReloadTransaction()の状態はidle、preparing、ready、applying、active、 diagnostic、full-rebuild、disposedです。

candidateはrevision、provider ID、source・graph・content integrity、change classification、affected scene、 validation summaryを持ちます。byteや絶対pathはprotocol summaryへ含めません。

commitはprepare済みcandidateへactivate()を呼び、adapterのrevision受理を確認します。activate失敗時は rollback('activation-failed')、release()、adapter discardを順に試し、旧active generationを維持します。 成功時はpreview.asset.committed acknowledgementをpublishしてから旧generationをreleaseします。 ack後の旧resource解放失敗はcommitを取消さずK4-ASSET-RELEASE-001とし、disposeで再試行します。

図: activation失敗時はcandidateをrollback・release・discardし、旧active generationを維持します。 full rebuild分類はcandidateをprepareせず、作者へ明示します。