技術参考資料（日本語）。ソースコード・過去の検証チケットはアプリには同梱していません。

保存データ仕様

HDR関連の現行化：2026-10-20。実装とResult0858〜0871を照合。その他の項目は各節の確認範囲・日付に従います。

確認日：2026-10-04。現行の本体Workspace・共通ブラウザ・Kitの保存コードを対象とします。文書の更新のみで、実ユーザーDBの読込・初期化・削除やGUIでの再検証は行っていません。配布中の版とは異なる場合があります。

一般画像対応の追補・照合：2026-10-11（GeneralImage）。一般画像の対応仕様と最終点検結果を参照。従来機能の全件再検証ではありません。

色温度・Tintの操作方向と保存互換性（1119）

調整レイヤーのtemperatureShift／tintShift、通常画像の入力補正、whiteBalance転用情報は従来の保存表現を維持する。移行・符号の書換え・文書version変更は行わない。既存の描画式も維持し、既存編集・プリセット・バリエーション・Undoの見た目を保持する。

GUIとMCPの表示・操作境界ではImageWhiteBalanceControlMappingを使い、温度の増加を暖色、Tintの増加をマゼンタへ対応させる。調整レイヤーの操作値は保存値の逆符号。通常画像の温度は表示基準Bに対しcontrol=2B−stored、Tintは逆符号。RAWデコーダのWBにはこの変換を適用しない。旧設定の表示値は変わり得るが、確定・保存するだけで内部設定を変えてはならない。補正式や永続化側へ重ねて反転を追加しない。結果1119。

保存するものの違い

入力画像の画素を現像DBへ複製する方式ではありません。現像パラメータとレイヤー・マスク等の復元用データを保持します。レンダーキャッシュや画面操作中の一時状態は編集文書と区別します。

本体の保存先

コード上はApplication Support配下のShinG3Genzoディレクトリ。現在の本体はサンドボックス有効、Bundle IDはShinG.ShinG3Genzoです。

~/Library/Containers/ShinG.ShinG3Genzo/Data/Library/Application Support/ShinG3Genzo/
├── WorkspaceEdits.sqlite
├── WorkspaceVariations.sqlite
├── RawLab.sqlite                 # 旧画面専用。通常画面は作成しない
├── UserPresets/
│   └── <UUID>.rawlabpreset
├── ImageExportProfiles.json
├── ToolbarLayout.json
├── LeftPanelLayout.json
├── RecentImages.json
├── MCPFolders/                   # 許可済みRAWフォルダ
└── MCPLUTFolders/                # 許可済みLUTフォルダ

必要になったファイルのみ作成されます。SQLiteには-wal／-shmの補助ファイルが付く場合があります。Bundle IDやサンドボックス設定を変えたビルドでは同じ絶対パスになるとは限りません。

Experimentsは本体とは別の保存先を指定します。例えばバリエーションはApplication Support配下のRawLabExperiments/Variations/Variations.sqliteです。本体DBと共有されると考えないでください。

新しいアプリの保存領域

本体は ShinG.ShinG3Genzo の新しいコンテナで開始します。AppStorageLocation.root はApplication Support配下の ShinG3Genzo だけを選び、起動時に作成します。旧コンテナや旧RawLabフォルダの探索・移動・統合・フォールバックは行いません。以前の実験的な移行処理は削除しました。

編集・バリエーション・プリセット・MCPのフォルダ許可は新しい保存領域から開始します。旧コンテナのデータや許可を引き継ぎません。バンドルID、MCP namespace ShinG.ShinG3Genzo.localmcp、UserDefaultsの製品名接頭辞 ShinG3Genzo.* は今後維持します。UserDefaultsの旧キーを読み替える処理もありません。

根拠：共通保存先、新規アプリへの変更。

旧画面用RawLab.sqlite

通常のWindowGroup／RAWオープンは RawWindowRoot → RawLabNewWorkspaceView を使います。旧 ContentView は削除済みです（Ticket1167）。旧DBはUserDevelopmentDatabaseManagerの読み書き時に遅延生成されますが、現在の通常画面からその経路には入りません。設定のデータ管理は同じ部品を使うものの、サイズ取得はファイル情報の参照のみでDBを作成しません。新コンテナのテストでもサイズ取得前後でRawLab.sqliteが存在しないことを確認しています。

旧画面・プレビュー用のコードと、既存ファイルの容量表示・初期化対象としての RawLab.sqlite は維持します。通常本体に新しい同名DBを作らせるための変更は追加しません。

ブラウザの保存先

評価・タグ・スタック・現像済みサムネイルは AppStorageLocation.rawBrowserRoot（AppStorageLocation.root/RawBrowser）に統一しています。通常キャッシュは再作成可能なため、引き続きCaches配下に置きます。

~/Library/Containers/ShinG.ShinG3Genzo/Data/Library/
├── Application Support/ShinG3Genzo/
│   ├── WorkspaceEdits.sqlite            # 現像DB等は前節参照
│   └── RawBrowser/
│       ├── assessments.sqlite          # 評価・フラグ・タグ
│       ├── stacks.sqlite               # スタック
│       └── DevelopedThumbnails-v1/
│           └── <URL識別子のSHA256>.plist
└── Caches/ShinG.ShinG3Genzo/RawBrowserThumbnails-v2/
    └── <キャッシュキーのSHA256>_<source>.jpg

Experimentsは同じ共通rootを参照しますが、本体はサンドボックス内、通常Experimentsはサンドボックス外で動くため、実際のApplication Supportは別です（Experimentsは ~/Library/Application Support/ShinG3Genzo/RawBrowser/）。本体の評価・タグ・スタックは共有しません。未配布の新アプリの配置を確定する変更であり、前段階の検証で作ったBundle ID名フォルダからの自動移行・統合は行いません。

根拠：評価DBの配置、スタックの配置、現像サムネイルの配置、キャッシュの配置。

ブラウザDBの構造・画像識別

両DBはWALを使用します。評価DBは既存version 1へタグ用テーブルを追加してversion 2へ移行します。それ以外の不適合な識別子・バージョンは拒否します。タグ名の正規化値は一意で、タグ定義の削除は全画像の関連付けへ波及します。画像からのタグ解除は定義削除とは別です。

評価は0〜5、フラグはunflagged／picked／rejected。評価なし・未判定の組み合わせは評価レコードを削除します。ブラウザの星評価はバリエーションのratingと別の値です。スタックは1画像1スタックを前提に、メンバー順序・代表・展開状態を保存します。解除は関連付けを消し、RAWを削除しません。

画像識別子は標準化・シンボリックリンク解決後のファイルURLです。現像DBと同様、ファイル内容を追跡する仕組みではなく、移動・改名後の評価・タグ・スタックの自動追従は保証しません。

根拠：評価ストア、タグストア、スタックストア。

サムネイルの保存・鮮度・リセット

一覧では、有効な現像済みサムネイルを優先します。現像済みレコードはversion 1のバイナリplistで、JPEGデータ、RAWのファイルサイズ・更新日時、編集文書のrevision、RAW使用範囲を一緒に保存します。URL識別子のSHA256をファイル名に使い、atomicで書き込みます。JPEG生成の既定は長辺1024px・sRGB・品質0.92です。

読込時にファイルサイズ・更新日時・revision・使用範囲が一致するか検証します。古いレコードのusageRange省略はcaptureとして扱います。既存の現像済みレコードがあるが現在の設定と一致しない場合、保存済み現像設定からの再描画経路を使えます。レコードがない場合は通常のカメラ表示へ進みます。DBに現像設定があることだけで、常に一覧の現像サムネイルを再生成する仕様ではありません。

通常キャッシュはJPEGで、キーに生成方式の版・RAW使用範囲・画像識別情報・要求サイズ・埋込プレビュー優先の指定を含みます。撮影範囲では対応メタ情報による埋込画像の画角補正を行い、埋込画像が使えなければRAWから縮小生成します。メモリキャッシュとディスクキャッシュを使い、容量超過時は最終利用が古いファイルから削除します。容量設定は256／512／1024／2048 × 1024²バイト、既定512 × 1024²バイトです。出力JPEGの容量指定（1MB=1,000,000バイト）とは単位が異なります。

現像側は編集文書とRAW使用範囲の鮮度を確認して現像結果を保存・通知し、ブラウザは対象画像の表示を更新します。現像ウィンドウを開かないペーストでも、適用先画像の設定とサムネイルを更新します。

現像済みplistには通常キャッシュの容量上限・自動削除を適用しません。サムネイルリセット後も、拡大プレビューの「現像結果」は保存済み設定を使えます。再度現像結果を保存・通知すれば一覧へ現像サムネイルが反映されます。

根拠：現像済み保存、生成処理、通常キャッシュ、本体の通知、ブラウザのリセット。

RAW使用範囲の保存

RAW使用範囲はUserDefaultsのraw.sourceUsageRange.filesに、URL識別子→capture／fullSensorの辞書として保持します。明示的な画像別選択があればそれを優先し、なければraw.sourceUsageRange.default、未設定・不正ならcaptureを使います。初期値の変更は、明示選択のない画像に適用します。通知で開いている対象も再読込します。

この選択は現像文書・バリエーション・プリセットに含める補正ではありません。別画像へのペーストでは転送せず、現像Undo／Redoとも独立します。現像・ブラウザのサムネイル／プレビュー・書き出しは対象画像の選択を使います。枠表示の設定もUserDefaultsですが、確認用の黄色い枠は書き出しません。

全範囲の取得は対応RW2に限ります。元RAWは変更せず、必要なクロップメタ情報をメモリ内で調整してデコードします。既存クロップ・マスク・ごみ取りの正規化座標は新しい使用範囲に対して解釈されるため、切り替え後は位置を確認してください。RAW使用範囲のバックアップにはDBだけでなくUserDefaultsの設定も必要です。

根拠：使用範囲設定、選択UI。

新DBの構造

両DBともWALを使います。新規DBはスキーマを作成し、既存DBは識別子とバージョンを確認して不適合なら拒否します。旧RawLab.sqliteを新ストアのURLへ渡して使うことはできません。

根拠：RawWorkspaceEditStore、RawVariationStore。

画像との紐付け・保存タイミング

本体のeditIdentityは、URLを標準化してシンボリックリンクを解決したabsoluteStringです。ファイル内容のハッシュではありません。そのため画像の移動・名前変更後に、以前の編集データが自動で追従する保証はありません。

本体はRAW／一般画像読込後に最新編集状態をロードして現像します。保存内容の復元に失敗した場合はエラーを表示し、データを上書きしない経路になっています。通常の編集では操作区切りの保存に加え、ウィンドウ終了時のflushで保存を確定します。

根拠：RawLabNewWorkspaceControllerのopen／editIdentity／saveEdits／flushEdits、RawLabAppのウィンドウ終了処理。

編集文書・互換性

RawPipelineWorkspaceDocumentCodecはJSONへencode／decodeします。現行文書versionは1。DBのuser_versionとは独立した番号です。

文書はparametersとlayersを持ち、復元時に検証結果を確認します。対応していない文書バージョンは拒否します。既存フィールドには省略時の既定値を持つものがありますが、任意の未来の文書を読める契約ではありません。

RawPipelineNamedSnapshotは画像IDと文書Dataを保持し、別画像への復元を拒否します。RawPipelineUserPresetは別画像へ適用するための形式で、適用項目やレイヤーの追加／置換を選択できます。レイヤー参照の整合性を保ちながらIDを再構成します。

全体と各レイヤーのlutStackには、LUT名・入力／出力プロファイル・適用率・有効状態と、cubeの寸法・domain・RGBAデータを保存します。元の.cubeファイルへのパス参照だけではありません。過去の文書でlutStackがない場合は空配列に復元します。レイヤー適用度は既存opacityを使います。これらの追加で文書versionを変更していません。

LUTを含む編集状態はDB・スナップショットへ保持されます。プリセットでは適用項目の選択に従います。埋め込むLUTの数・サイズが増えるほど文書サイズも増えるため、DBだけでなくプリセットやメモリ上のスナップショットの容量にも影響します。根拠：RawLUT、Result0618、Result0624。

フィルムスタイルはparametersのfilmStyleProfile（選択ID）とfilmStyleGrainSeed（任意のUInt32）を保存します。同梱カタログ全パラメータを文書へ凍結する方式ではないため、同じIDの定義がアプリ更新で変わると再現像結果も変わり得ます。完成した画素を残す場合はJPEG／PNG／TIFFも書き出してください。

旧DBから新DBへの自動移行を、本体Workspaceの通常読込経路は行っていません。旧DBのデータを残す必要がある場合は、削除前に退避してください。

初期化・削除・バックアップ

本体設定の「現像データベースを初期化」は、RAWウィンドウをすべて閉じた状態で確認ダイアログを経て実行します。

新DBを未作成なら初期化のために作成しません。新DBは残存接続を壊さないようSQLで内容を消し、稼働中のWAL／SHMを直接削除しません。各DBの処理はトランザクションですが、新旧DB全体で単一のトランザクションではなく、途中のI/Oエラーで一部だけ初期化済みになる場合があります。

旧データだけが不要な場合は、本体を完全に終了してRawLab.sqliteと同-wal／-shmだけを退避・削除します。設定の初期化ボタンは新DBも対象なので使い分けてください。旧コードが再度DBへアクセスすると旧DBが再作成される可能性があります。

ファイル単位のバックアップはアプリを終了してから、DBと存在する補助ファイルを同じ時点の組として扱います。稼働中に.sqliteだけをコピーすると、WAL内の最新データが含まれない場合があります。現像DBはRAW画像自体のバックアップにはなりません。

ブラウザの選別・分類を残すにはassessments.sqliteとstacks.sqliteも退避します。現像済みplistは再表示用の派生データで、編集文書の代わりにはなりません。通常のCachesは再作成可能です。UserDefaultsにはRAW使用範囲、表示幅、フォルダbookmark、お気に入り等があるため、Application Supportだけのコピーでは設定全体のバックアップにはなりません。bookmarkはアクセス権の状態に依存し、他のMacへコピーするだけでアクセスを保証しません。

根拠：RawLabSettingsView、DevelopmentSettingsStore、RawWorkspaceDatabaseMaintenance、Result0607。

未確認・今後整理

DBの自動世代バックアップ、画像移動時の再紐付け、将来のスキーマ移行方針は別途仕様化が必要です。クラッシュ・電源断・ディスク不足の全条件での回復検証は今回の文書整備には含めません。

ブラウザの「プリセットを適用…」も現像画面と同じ Application Support/ShinG3Genzo/UserPresets のライブラリを使用します。選択画像の最新編集状態と現像済みサムネイルを既存ペースト処理で更新し、保存済みバリエーション・プリセットファイル・コピー済み設定は変更しません。

ブラウザの一括ペースト／プリセット適用履歴は、適用前後のシリアライズ済み設定をメモリ内に保持します。DBへ保存した実際のバイト列を記録し、Undo／RedoのDB更新は RawWorkspaceEditStore.replaceDocument で期待した保存状態と同一かをトランザクション内で照合します。未保存状態への復元は当該画像の最新設定行を削除し、現像済みサムネイルも取り除きます。プリセットライブラリとバリエーションDBは変更しません。履歴は再起動時には保持しません。

ブラウザの「現像設定をリセット」は、最新設定DBの対象画像の行を、期待する文書と一致する場合だけ削除します。履歴の適用後状態はnilです。現像済みサムネイルも削除して通知します。Undoはリセット前の正確な文書を復元してサムネイルを再生成し、Redoは再削除します。現像画面に未保存編集がある場合はそれを保存してからリセットし、Undoでその編集を復元します。バリエーションDB、プリセット、ブラウザDB、RAW使用範囲の設定は変更しません。

現像画面の全設定リセットはブラウザと同じ最新設定削除／通知経路を使用します。未保存の内容を保存してから初期状態へ戻し、現像画面の通常履歴にリセット状態を記録します。その画面でUndo／Redoすると、復元したパラメータ・レイヤーは既存の自動保存経路で保存されます。バリエーションは削除しません。

ブラウザのペースト選択はUserDefaultsの ShinG3Genzo.browser.pasteSections（項目ID配列）と ShinG3Genzo.browser.pasteLensCorrection（Bool）に保存します。初期値は全項目ON、実行確定時のみ保存。RAW現像文書・プリセットファイル・バリエーションDBの形式は変更しません。KitのRawPipelinePresetOptions.applyLensCorrectionはnilで既存のNR項目連動を維持し、明示的なtrue／falseでレンズ補正の移送／保持を独立指定します。

部分ペースト時の基準は、対象画像の保存済み設定、またはそのRAWの撮影時既定値です。未選択のレイヤー・マスクは既存IDとデータを維持し、移送されて新IDになったAIマスクだけ再生成の対象です。履歴は実行前後の全体文書を保持するため、部分ペーストも既存の一括Undo／Redoで復元できます。

ブラウザの現像状態フィルターは最新設定DBの edits.source_identity の存在を基準にします。Kit PersistenceのRawWorkspaceEditStore.savedSourceIdentitiesは文書BLOBを読み込まず、重複を除いた対象IDを500件単位のSQL照会で取得します。RawBrowserDevelopmentStatusSourceがバックグラウンドのactor上でURL識別と照会を実行し、DBがなければ作成せず未現像として返します。サムネイルキャッシュ・バリエーションDBは参照しません。

保存・照合付き保存・置換／削除の確定後、RawWorkspaceEditStore.changedをsource identity付きで通知します。ロック解放後に通知し、失敗した更新は通知しません。ブラウザは状態をメモリに保持し、通知されたIDを短時間まとめて再照会します。SwiftUIの絞り込み・スクロール中にSQLiteやURLのファイル情報は読みません。フィルター選択は永続化しません。

一般画像とWB転送

JPEG／PNG／TIFF／HEIFも同じURL識別子・編集DB・バリエーション・サムネイル経路を使います。入力の画素精度を編集DBへコピーする方式ではなく、元画像は変更しません。一般画像サムネイルの通常キャッシュはstandardImage種別でImageIOの縮小画像を保持します。

新規プリセットにはoptionalのwhiteBalance情報（RAW絶対値／一般画像の温度・ティント補正量）を記録します。version 1の旧JSONも読めますが、種類情報がなければコピー先WBを維持して再保存を案内します。RAW↔一般画像もWBを維持。他項目は選択どおり転送します。詳細は一般画像の対応仕様。

HEIF出力プロファイルはformat: "heif"とheifBitDepth: 8 | 10を保持します。新フィールドがない旧プロファイルは10bitを既定値として読み込み、既存の形式・設定を維持します。品質は共通のquality、容量指定のusesByteLimit等はJPEG専用のままです。拡張子はheic、入力HEIFの編集DBの形式変更はありません。

HDR入力解釈（2026-10-13、0794）

編集パラメータのstandardImageDynamicRangeでSDR／HDRの入力解釈を保持します。値がない旧文書はSDRです。新規画像はHDRデコードを試み、実際にHDRである場合だけHDRとして保存します。プリセット・設定転送は対象画像の入力解釈を維持します。

SDR文書は従来のversion 1を維持し、HDR文書だけversion 2を使用します。現行版は両方を読み込みます。旧版はversion 2を拒否するため、HDR編集をSDRとして誤って再現することを防ぎます。SQLiteのスキーマ変更はありません。「HDR表示」は表示状態であり編集パラメータには保存しません。

ペアサムネイルの最新現像判定には edit_save_dates の保存日時を使います。編集文書と同一トランザクションで保存し、リセット時は日時も削除します。従来DBには補助テーブルを追加し、既存文書を書き換えません。日時未記録の旧編集は現像サムネイルの更新日時を代用し、同時刻または両方不明ならRAWを優先します。サムネイルを削除しても保存済み現像設定は残るため、その設定から再生成できます。

RAW HDR表示とPQ出力プロファイル（2026-10-20）

RawImageExportProfile.dynamicRangeはsdr／pq。未指定の旧プロファイルはsdrで読み込みます。heifBitDepthの未指定時は従来どおり10です。PQはHEIF・10bit・署名無効・容量上限無効を必須とし、不正な組合せを拒否します。PQ表示中も通常のcolorSpace値はSDRへ戻るために保持し、符号化にはBT.2100 PQを使用します。

rawHDRPreviewEnabledは本体Controllerの一時状態で、既定OFF。写真を開き直すとOFFです。DB・バリエーション・プリセット・出力プロファイルへ保存しません。通常画像のstandardImageDynamicRange（保存対象の入力解釈）とは別です。既存DBスキーマと通常画像文書のversion規則は変更しません。

HDRプレビュー用の画像とピーク値も一時的な表示資源です。ヒストグラム・保存用サムネイルは通常画像を使います。元RAW・編集記録をPQ出力のために変更しません。

根拠: 出力プロファイル、HDR表示状態、Result0859、Result0867。