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

厳密なenvelope

normalizeDsl4DiagnosticSequence()が受理するdiagnosticは、次のfieldだけを持ちます。

{
  "version": 1,
  "code": "K4-REF-001",
  "severity": "error",
  "message": "Unknown reference: MissingBackground",
  "sourceId": "chapters/opening.k4.yml",
  "range": {
    "start": {"line": 12, "column": 7, "offset": 180},
    "end": {"line": 12, "column": 24, "offset": 197}
  },
  "storyPath": "/scenes/opening/actions/2",
  "path": "$.scenes.opening[2]",
  "related": []
}

storyPathだけが任意です。他のfieldは必須で、未知field、accessor、custom prototype、sparse array、NULを拒否します。 codeはK4-で始まる安定識別子、severityはerrorまたはwarningです。固定commitのsource frontendは 失敗をerrorで生成しますが、sequence policyは将来のwarningを受理し、warningだけならcanStage: true、 errorが一件でもあればcanStage: falseとします。

診断はsource offset、code、messageの順で決定的にsortします。既定の100件を超えた場合は、最後のslotを K4-DIAGNOSTICS-TRUNCATEDへ置き換え、省略されたerrorの有無をseverityへ反映します。

file、行、列、pathの意味

Schema errorではschemaErrorSegments()がAJVのJSON Pointerをnode探索用segmentへ変換し、 storyPathFromSourceSegments()がscene／action位置を作ります。semantic errorでは validateDsl4Semantics()のJSONPath風issue.pathをjsonPathSegments()でsource nodeへ戻します。 この違いをUIやeditor統合で一つのpath dialectへ無断変換しません。

stableId、scene、action、causeの境界

stableId、sceneId、actionIndex、actionPath、causeはcanonical diagnosticのfieldではありません。

• actionのstableIdはStoryDocument.scenes[].actions[]に保持され、reload plannerが移動後のactionを照合するために storyPathより先に使用します。診断位置は現在のstoryPathとsource originで表し、stableIdを追加fieldにしません。
• scene／action contextはstoryPathから解決します。runtime snapshotは別契約としてsceneId、actionIndex、 actionPathを持ちます。
• Error.causeとAggregateError.errorsは内部調査・cleanup集約用です。canonical envelopeへcause chain、stack、 dependencyの生messageをコピーしません。
• duplicate declaration等で別位置を示す場合は、causeではなく有限なrelated[]を使用します。

diagnostic-sequence-policy.jsは未知fieldを値の読取り前に拒否します。そのためabsolutePath、sourceText、 runtimeValues、sessionToken、causeをdiagnosticへ混入させてもexportやwireへ通りません。

Source read、canonicalize、YAML parse

parseRestrictedYaml()はsource objectやScratch状態を変更しません。YAML errorがあればSchemaへ進まず、 失敗結果にstoryDocumentを載せません。

Schema、semantic、expression

Schema、semantic、expression、resource diagnosticを正規化した後、errorが残る場合は createStoryDocument()を呼びません。検証中のRuntime Expression compositionも必ずreleaseします。

IncludeとSource Graph

createDsl4SourceGraph()はsource topologyだけを作り、asset byteやruntimeを読みません。 createDsl4SourceGraphFrontend()は各sourceへrestricted YAML policyを適用し、compose成功後だけ単一source frontendへ 渡します。included sourceのsemantic errorはsourceOriginsにより宣言元のlogical fileとrangeへ投影されます。

Asset snapshotとtransaction

build時のlocal asset loaderはmissing、path、symlink、file kind、件数、size、integrity、stable readを K4-ASSET-MISSING、K4-ASSET-PATH-001、K4-ASSET-SYMLINK-001、K4-ASSET-COUNT-001、 K4-ASSET-SIZE-001、K4-ASSET-UNSTABLE-001等で拒否します。asset snapshotが完成する前にbase SB3へ 書き込みません。

asset live reloadのdiagnosticはcanonical source diagnosticではなく、 {formatVersion: 1, code, severity: 'error', message}というtransaction状態です。

commit()はpreview.asset.commit-started、activate、adapter accept()、 preview.asset.committed acknowledgementの順です。旧generationを解放するのはack後です。 activate失敗時はpreview.asset.commit-failedをpublishし、旧active revisionが変わらないことをtestで固定します。

Runtime、navigation、platform

runtime errorは現在actionまたは式のstoryPathをsourceOriginForStoryPath()へ渡し、canonical v1に近い runtimeDiagnostic()を作ります。

navigation creation diagnosticにはdetails、quiesce diagnosticにはstoryPathとorigin、asset transactionには formatVersionがあり、strict canonical envelopeとは異なります。これらをCLI JSONやtelemetryへ出す場合は、 surface adapterが安全なpathとmessageを決めてcanonical envelopeへ明示変換する必要があります。固定commitには 任意のlifecycle diagnosticを自動的にcanonical化するfallbackはありません。

source frontend

source frontendはpure境界です。filesystem、network、Scratch VM、DOM、asset registryを参照しません。 検証失敗時に禁止される副作用は次です。

• StoryDocument、runtime session、actor clone、renderer skinの生成
• asset fetch、asset登録、cache変更
• input listener、camera、timer、broadcastの開始
• preview candidate、SB3出力、source manifestのcommit

式のsyntax検証で一時的なcompositionを作る場合も、finallyでreleaseAll()を呼びます。

source live reload

createDsl4LiveReloadSession.stage()へok: falseを渡すと、pending candidateをclearし、診断を更新して invalidへ移ります。current sessionが存在する場合は停止・disposeせず、そのscene、action、variables、 source integrityを維持します。invalid sourceからreplacement sessionを生成しないことを keeps the current immutable execution when a changed source is invalid testが固定しています。

valid candidateはcurrent sessionのquiesce()が成功するまでpendingになりません。stale choice、disabled choice、 後から来たinvalid sourceはcandidateをcommitしません。defer()とdiscardCandidate()はcurrent runtimeを resumeQuiesce()してcandidateだけを捨てます。

source sessionのcommitには重要な境界があります。next sessionを先に生成した後、currentをstop／disposeしてから nextをstartします。next startが失敗した時点ではprevious sessionは停止済みのため、自動rollbackで復活させず sessionをfailedにします。discardCandidate()もfailed runtimeをactiveへ戻しません。

production build

buildDsl4RuntimeComponent()はmemory内でsource、asset、artifact、SB3を組み立て、loaderで再検証します。 buildDsl4RuntimeComponentFile()はcandidate directoryへ書き、byte一致とruntime componentを再検証した後だけ installBundleTransactionally()で出力を置き換えます。install途中で失敗した場合はbackupから既存fileを戻し、 自動復元まで失敗した場合だけrollback directoryを残して明示的な確認を要求します。

runtime failure

runtime-controller.jsのfail()は次の順で安全停止します。

1. Structured Data統合が有効ならendStructuredStory('runtime-failed')を試す。
2. statusをfailedへ変更する。
3. 現在のAbortControllerをruntime-failedでabortする。
4. actionまたはmapped expression errorからcode、storyPath、source pathを決める。
5. runtimeDiagnostic()を作り、asset lifecycleをruntime-failedでreleaseする。
6. runtime.fail eventを発行し、進行中のquiesceをrejectする。

Action ContextのgenerationとAbortSignalは両方検査します。取消済みactionのPromiseが後からresolveしても、 setVariable()、scene遷移、action.commitを実行できません。stop()、restart、navigation、quiesceもgenerationを 更新してstale completionを無効化します。

platform environment

createDsl4TurboWarpRuntimeEnvironment()はactor、pose feedback、camera controls、host port、Runtime Expression、 Structured Data、input arbitration、asset session等をcomposeします。途中で失敗した場合も、生成済みの各ownerへ cleanupを試み、元のcreation errorとcleanup errorをAggregateErrorへまとめます。

正常disposeではruntime／navigationを停止し、pending inputとrun settlementを待ち、cache lease heartbeatを止め、 platform resourceを解放します。observerやonEvent、onErrorがthrowしても実行状態を変更しません。

cleanup失敗を無視して成功扱いにはしません。ただし複数ownerの解放を一件目で打ち切らず、全ownerへ試行してから 集約します。