# Artifact Layers — jp-election-data

Version: 1.0.0-public  
Date: 2026-03-19  
License: jp-election-data License v1.0

---

## 概要

本データセットは四層のアーティファクト構造で管理されている。この構造は、公的選挙データの正確性とトレーサビリティを担保するために設計されたものであり、汎用データ管理フレームワークとして設計されたものではない。

**多目的利用においては、この四層構造の前提が成立せず、データの正確性が保証されない。**

---

## Layer 0: Evidence（一次資料）

各都道府県選挙管理委員会が公式サイトで公開する選挙結果（HTML / XLSX / XLS / PDF / ZIP 等）。

各ソースは internal の `source.yaml` で exact メタデータ（URL、取得日時、形式、variant_key）を記録する。公開面では exact 取得時刻を落とした sanitized source register のみを配布する。

**本リポジトリには Layer 0 の一次資料そのものは含まれない。** source.yaml のソース URL を参照して、利用者が独立に取得・検証できる。

### なぜ一次資料を含めないか

- ファイルサイズが大きく、リポジトリの可搬性を損なう
- 各選管の利用規約が異なり、再配布の法的リスクがある
- 利用者が自ら一次資料を取得・照合することが、検証プロセスの一部である

---

## Layer 1: Internal Model（中間変換物）

パイプラインの各ステップ（M0〜M3b）が生成する中間データ。

- M0: ソース取得・配置
- M1: 抽出（非構造 → 構造）
- M2: 正規化（辞書適用、ID 付与）
- M3a: 情報補完（jis_code、party_id の確定）
- M3b: 統計補完（turnout 情報の統合）

**本リポジトリには Layer 1 の中間変換物は含まれない。** 中間物はパイプラインの内部状態であり、外部利用者にとっては Layer 2 の Release Facts が正本である。

---

## Layer 2: Release Facts（公開正本）

本リポジトリの中核。2つの CSV ファクトと辞書群で構成される。

- `fact_candidate_votes.csv`: 政党 × 市区町村の得票数
- `fact_district_stats.csv`: 市区町村ごとの投票統計
- `dictionaries/common/`: 政党マスタ、市区町村マスタ、エイリアス等

### Layer 2 の不変条件

- すべての値はソース（Layer 0）から導出される。推論・補間・外挿で生成された値を含まない
- `__PENDING__` = 0（仮値が残っていない）
- `__MISSING__` = 0（results 系。取得不能な値は明示的に記録）
- 内部整合性チェック（validate_tidy）が通過している

### 依存方向

```
Layer 0 → Layer 1 → Layer 2 → Layer 3
                      ↑ 正本
```

**原則: 上位層から下位層を生成する。下位層から上位層へ値を戻さない。**

Layer 3 の派生物（スプレッドシート、可視化等）で発見された誤りは、Layer 2 を修正し、Layer 3 を再生成する。Layer 3 の値で Layer 2 を上書きしない。

---

## Layer 3: Deliverables（派生物）

Layer 2 から生成される人間向け・機械向けの出力。

本リポジトリで公開される Layer 3 成果物:
- `public-summary.csv`: 概要サマリ
- `visualization-ready.xlsx`: 可視化用ワークブック
- 検証成果物（verification/）

本リポジトリで公開されない Layer 3 成果物:
- Developer Review Workbook（内部レビュー用）
- GAS 生成スプレッドシート

### 公開後査読との関係

公開時点で人手による exhaustive な全件査読が完了していない場合でも、Layer 2 facts と公開可能な検証成果物を先に提示することがある。

このときの人間確認は、公開後に行う正式な査読段階として扱う。査読で見つかった問題は Layer 3 の見た目だけで補正せず、Layer 2 を修正し、必要な residual 開示と版更新を行った上で再生成する。

---

## この構造が多目的利用で問題になる理由

本データセットの四層構造は、以下の前提に依存している。

1. 入力が日本の選挙管理委員会の公式データであること
2. 辞書（Layer 2 の一部）が選挙データの表記揺れに特化していること
3. 整合性チェックが選挙統計の算術整合に特化していること
4. 行政区分割（§4）が日本の選挙制度に固有のパターンであること

これらの前提が成立しない文脈（他国のデータ、選挙以外の統計、商用 BI への投入等）では、Layer 2 の不変条件が意味をなさず、辞書の結合が機能せず、整合性チェックが検出すべき問題を見逃す。

**本データセットを目的外で利用する場合、四層構造の保証は適用されない。**