技術モジュール

公開向けの責務分担

Netlist Studioは、表示、操作調整、純粋なdomain規則、OS境界、重い計算を分離します。

層	公開sourceの目安	入力	所有する責務	出力
UI	src/components/、各windowのApp	利用者操作、view model	盤面、制御canvas、Graph、focus、入力draft、診断表示	intent、確定入力
controller	src/app/controllers/	UI intent、現在revision	use caseの順序、stale応答破棄、pending操作	domain command、adapter request
domain	src/domain/	versioned data、command	回路、接続、解析、制御、I/O、診断の決定的規則	検証済みmodel／artifact description
Electron adapter	electron/	allowlist済みrequest	native menu、dialog、file、外部process、window／IPC境界	bounded result、structured error
worker	worker entryと純粋計算module	snapshot、計算条件	Graph演算、routing、重いprojectionをUI threadから分離	revision付き計算結果

UIはdomain規則を独自に再実装せず、controllerは回路式やPWM semanticsを所有しません。Electron adapterはrendererから任意のfile、process、command、URLを受け取らず、固定または検証済みcontractだけを扱います。

回路編集からGraphまでのデータフロー

UIの入力中の値
  → controllerが確定操作とdocument revisionを束縛
  → domainが部品値・接続・解析条件を検証
  → Electron adapterが固定ngspice executableでbounded jobを実行
  → parserがresultをversioned datasetへ変換
  → workerがGraph表示・演算・統計を計算
  → UIが同じrequest／revisionの結果だけを表示

途中でProjectが変わった場合、古い応答を新しいProjectへ適用しません。外部processのstdoutをそのままUIへ流さず、size、schema、値、単位を検証します。

ControlとFeedbackのデータフロー

Board + ControlGraph + Firmware I/O + timing
  → domain validation
  → ControlProgramIRへlowering
  → reference evaluator／C++ generator／WASM adapter
  → main processがSPICE deck・manifest・WASMを再検証
  → bounded cosimulation
  → result parserとProject fingerprint照合
  → 共通Graph datasetとPID projection

reference evaluator、生成C++、WASMは同じevaluation order、I/O index、state layoutを共有します。PWMのphase、Duty latch、PID stateはtick境界で一括更新し、direct-feedthroughのalgebraic loopは生成前に拒否します。

module contractの読み方

各moduleを調べるときは、実装行より先に次の5点を確認します。

1. 入力schemaとversion。
2. normalizationとresource limit。
3. error／warningのdiagnostic code。
4. 成功時に所有権が移るdataと、移らないdata。
5. stale、cancel、timeout、partial failure時の不変条件。

たとえばanalysisSettingsは解析directiveと点数見積りを所有しますが、ngspice processは起動しません。feedbackSimulationJobはjob lifecycleを所有しますが、renderer表示や回路semanticsは所有しません。

部品を拡張する

新しい回路部品は、次の順で追加します。

1. symbol definitionで端子、向き、既定値、categoryを定義する。
2. sanitizerで値、単位、範囲、legacy入力を正規化する。
3. connectivityとnetlist generatorへ電気的semanticsを追加する。
4. Inspectorへtransactional inputと日本語診断を追加する。
5. ngspice／LTspice出力、保存round-trip、invalid入力をtestする。

見た目のglyphだけ追加しても、接続、保存、SPICE、診断が揃わなければ公開機能にはしません。

制御blockを拡張する

新しいControl blockは、port、signal type、direct feedthrough、state、parameter、diagnosticをdomainで定義します。その後、reference semantics、IR lowering、C++ codegen、必要なUI editorを追加します。

• combinational blockはcycle検査へ参加します。
• stateful blockはcurrent stateとnext stateを分けます。
• firmwareへ出すblockはfloat32／float64の両方を検証します。
• PWMやI/Oを持つblockはtiming、range、safe stateを明示します。
• Custom／Compositeはnode、edge、source、depthの上限を超えたら部分結果を使わず停止します。

Graph演算を拡張する

Graph演算は元datasetを変更しない純粋なprojectionとして追加します。

1. 対応するX軸と系列数を定義する。
2. 単位の組合せと出力単位を定義する。
3. zero division、非finite、点数不足を診断する。
4. 追加前previewへ式、label、単位、点数を表示する。
5. worker結果へrequest IDとrevisionを付け、stale結果を破棄する。

OS／security境界

• Main windowとGraph windowの権限を分離します。
• rendererはNode.js、任意process、任意file、任意navigationへ直接到達しません。
• dialogの取消、保存失敗、stale completionでは元のdocument handleとdirty状態を維持します。
• 外部processは固定実行対象、bounded input／output、timeout、cancel、cleanupを持ちます。
• credential、署名鍵、provider設定、内部運用証跡は公開ガイドへ掲載しません。

問題を追う順序

1. UIに表示された最初のdiagnostic codeと対象field／nodeを記録します。
2. controllerがどのuse caseとrevisionを送ったか確認します。
3. domain validatorが同じsnapshotを受理するか確認します。
4. adapter境界へ渡ったversioned requestとbounded resultを確認します。
5. workerまたは外部processの結果が現在revisionと一致するか確認します。

UI表示だけ、外部logだけ、古いartifactだけで原因を断定しないことが、module境界を保った調査の基本です。