diff --git a/.github/actions/build-wheels/action.yml b/.github/actions/build-wheels/action.yml new file mode 100644 index 0000000..d983d40 --- /dev/null +++ b/.github/actions/build-wheels/action.yml @@ -0,0 +1,19 @@ +name: Build and upload wheels +description: Build and test platform wheels, then upload the artifacts. + +runs: + using: composite + steps: + - name: Set up QEMU + if: runner.os == 'Linux' + uses: docker/setup-qemu-action@v4 + with: + platforms: arm64 + + - uses: pypa/cibuildwheel@v4.2.0 + + - uses: actions/upload-artifact@v7 + with: + name: wheels-${{ runner.os }} + path: wheelhouse/*.whl + if-no-files-found: error diff --git a/.github/workflows/build-dev.yml b/.github/workflows/build-dev.yml new file mode 100644 index 0000000..fc042d4 --- /dev/null +++ b/.github/workflows/build-dev.yml @@ -0,0 +1,34 @@ +name: Build wheels (dev) + +on: + push: + branches: [dev] + paths-ignore: + - '**.md' + - '**.rst' + pull_request: + branches: [dev] + paths-ignore: + - '**.md' + - '**.rst' + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + wheels: + name: Wheels / ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + steps: + - uses: actions/checkout@v7 + with: + submodules: recursive + - uses: ./.github/actions/build-wheels diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 45d02c7..57c480c 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -5,6 +5,7 @@ on: branches: [master] tags: ["v*"] pull_request: + branches-ignore: [dev] workflow_dispatch: permissions: @@ -51,23 +52,11 @@ jobs: os: [ubuntu-latest, windows-latest, macos-latest] steps: - - name: Set up QEMU - if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v4 - with: - platforms: arm64 - - uses: actions/checkout@v7 with: submodules: recursive - - uses: pypa/cibuildwheel@v4.2.0 - - - uses: actions/upload-artifact@v7 - with: - name: wheels-${{ runner.os }} - path: wheelhouse/*.whl - if-no-files-found: error + - uses: ./.github/actions/build-wheels publish: name: Publish to PyPI diff --git a/.github/workflows/test-dev.yml b/.github/workflows/test-dev.yml new file mode 100644 index 0000000..1b434fb --- /dev/null +++ b/.github/workflows/test-dev.yml @@ -0,0 +1,20 @@ +name: Test (dev) + +on: + push: + branches: [dev] + paths-ignore: + - '**.md' + - '**.rst' + pull_request: + branches: [dev] + paths-ignore: + - '**.md' + - '**.rst' + +permissions: + contents: read + +jobs: + test: + uses: ./.github/workflows/test.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e3425f2..7fcbc6f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -4,7 +4,9 @@ on: push: branches: [master] pull_request: + branches-ignore: [dev] workflow_dispatch: + workflow_call: permissions: contents: read diff --git a/.gitmodules b/.gitmodules index b633420..14f2305 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "src/ext/uchardet"] path = src/ext/uchardet url = https://github.com/PyYoshi/uchardet.git - branch = cchardet + branch = dev diff --git a/README.md b/README.md index f9fc20f..2d78bc3 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ CPython 3.14 build. Each version is tested on Linux, macOS, and Windows. ## Development +The [cChardet v3 development roadmap (Japanese)](docs/v3-roadmap.md) describes +the native development, corpus/model, accuracy, and API work planned for the next +major release and the v3 series. Development is integrated on `dev`, while `master` +tracks stable releases. v3 may include breaking changes with documented migration paths. + Install [uv](https://docs.astral.sh/uv/), clone this repository with its submodules, then create the locked development environment and run the checks: diff --git a/docs/v3-roadmap.md b/docs/v3-roadmap.md new file mode 100644 index 0000000..7c99b77 --- /dev/null +++ b/docs/v3-roadmap.md @@ -0,0 +1,742 @@ +# cChardet v3 開発ロードマップ + +状態: 開発の方向性は合意済み。具体的な実装計画・評価閾値は本書の提案を出発点として検証する。 + +現状確認日: 2026-09-20。対象は cChardet `bc41189`(2.3.0)と、同梱する +PyYoshi/uchardet `7993e0a`。本書の公開をもって各作業が実装済みになったとは扱わない。 +リリース日は未定。 + +本書および今後のv3開発文書は日本語で管理する。 +利用者向けのREADME、APIリファレンス、公開リリースノートなどは英語を基本とする。 +開発上の議論と利用者向けの説明を分け、確定した仕様は利用者向け文書にも反映する。 + +## 目次 + +- [目指す製品と対象範囲](#direction) +- [現状と根拠](#baseline) +- [リポジトリ・ブランチの責務](#ownership) +- [優先順位・依存関係・リリース範囲](#phases) +- [Phase 1: native開発基盤](#phase-1) +- [Phase 2: corpusとmodelの基盤](#phase-2) +- [Phase 3: 失敗分析](#phase-3) +- [Phase 4〜6: 検出器の改善](#phase-4-6) +- [Phase 7〜9: 代替実装と長期研究](#phase-7-9) +- [測定方法と変更の受け入れ基準](#measurement) +- [v3で決める契約と移行方針](#contracts) +- [最初の実装単位](#first-prs) +- [リリース条件・リスク・進捗管理](#release) + + + +## 目指す製品と対象範囲 + +cChardet v3は、実際のデータ取り込み処理に適した、高速・軽量・並列化可能な +native文字コード検出器を目指す。主要用途はスクレイピング、クローリング、 +HTML・文書の取り込み、RAG前処理、学習用corpusの整備、ETL、大量ファイルの並列処理とする。 + +特に数KiB〜数百KiBの入力における速度、少ないallocation、incremental処理を重視する。 +通常のCPythonとfree-threaded CPythonの双方で、独立したdetectorを効率よく並列実行できる +設計を維持する。複雑な判定ロジックはPython wrapperへ移さず、native側で扱う。 + +ダウンロード数増加の原因は未確定である。AI用途、大規模downstream、使い捨て環境での +再インストールなどは仮説として扱い、ダウンロード数から入力分布や利用目的を断定しない。 + +chardetとの完全互換を最上位目標にはしない。馴染みのあるAPIは価値があるが、 +必要な改善を互換性が妨げる場合は、Python API、C API/ABI、検出結果、デフォルト設定の +破壊的変更をv3の選択肢に含める。変更には理由、測定結果、明示的な仕様、移行方法を用意する。 +互換アダプターは必要に応じて検討し、nativeの主要な処理経路に恒久的な複雑さを持ち込まない。 + +本書はv3系列全体のロードマップであり、すべてのPhaseを3.0までに終える計画ではない。 +Rust、新しい検出器architecture、SIMDは条件付きの後続作業とする。 +3.0では基盤整備に加えて利用者に意味のある改善を届けるが、具体的な対象は失敗分析の後に選ぶ。 + + + +## 現状と根拠 + +以下は現在のリポジトリを確認して得た事実であり、本書の作成時に既存テストや測定を +すべて再実行したという意味ではない。 + +| 領域 | 既にあるもの・確認先 | 今後必要なこと | +| --- | --- | --- | +| Python開発環境 | [uv設定](../pyproject.toml)、[Makefile](../Makefile)、型情報、テスト | lockされた環境を維持し、engine用toolとwrapper用toolの責務を分ける | +| CI・native安全性 | [Test workflow](../.github/workflows/test.yml): Linux ASan/UBSan、3 OSでのPython 3.11〜3.14/3.14t | native compiler・build構成のmatrix、専用fuzzing、静的解析の継続実行 | +| native build | [CMake設定](../src/ext/uchardet/CMakeLists.txt): 最小版宣言は3.5、C++11、DebugでASan付与、CPU/浮動小数点flagはglobal | 明示的で移植可能なoption、target単位のflag、実際の最小版とmulti-config動作の確認 | +| native test | [CTest登録](../src/ext/uchardet/test/CMakeLists.txt)で既知の失敗5組を除外 | 対象・失敗理由を可視化し、既知の失敗を黙って集計から消さない | +| 挙動比較 | [random bytesのwrapper test](../tests/test_robustness.py)、[native候補出力tool](../src/ext/uchardet/benchmark/uchardet-output.cpp) | 機械可読な比較、lifecycle・終了状態の追跡、失敗入力の最小化 | +| 性能測定 | [native benchmark](../src/ext/uchardet/benchmark/README.md)、[Python比較](../benchmarks/pyperf_compare.py)、[threading比較](../benchmarks/pyperf_free_threading.py) | version付きworkload、測定値の分布、allocation・memory・並列scalingの報告 | +| 精度測定 | [評価script](../benchmarks/accuracy.py)でcorpus別のexact/compatible/decode-equivalentとlanguage指標 | sample単位の記録、評価定義のversion管理、data分割、失敗分類 | +| test data管理 | [Test data policy](test-data-policy.md) | corpus manifest、license一覧、決定的な生成、data混入の検査 | +| model生成 | [生成手順](../src/ext/uchardet/script/README)、[BuildLangModel.py](../src/ext/uchardet/script/BuildLangModel.py)、language/charset定義と生成log | 参考調査と由来の記録。既存generatorは非採用を基本とし、再現性・品質を検証できる新規実装を作る | +| packaging | [wheel workflow](../.github/workflows/build.yaml)、[wheel smoke test](../tools/wheel_smoke.py) | native連携を変更しても配布物をinstallした状態で検証 | + +[既存の性能分析](performance-analysis.md)には、同梱fixture 158件について、2.2.0 baselineから +nativeの実行時間がwhole-fileで54.5%、64-byte chunkで51.6%減少した測定がある。 +これは特定workloadでの結果であり、すべての入力で同じ改善があるという意味でも、 +新しいv3の測定結果でもない。engineを変更する前にbaselineを取り直す。 + +既存の候補比較だけでは、任意のchunk境界で必ず同じ結果になることや、異なるplatform間での +bit単位の一致までは証明できない。その保証範囲も今後明示する。 + + + +## リポジトリ・ブランチの責務 + +### cChardetのブランチ運用 + +`master`を安定版、`dev`をv3の開発統合先として分ける。 +`dev`は2.3.0リリース後の`master`から開始し、v3の作業branchは原則として`dev`から作成する。 +v3開発用のDraft PRは`dev`をbaseにする。本ロードマップのPRも同じ運用に従う。 + +安定版に必要な修正は`master`向けPRとして扱い、`dev`にも必要な修正を計画的に反映する。 +v3の破壊的変更を2.xへまとめて逆流させない。 +3.0の公開前に、`dev`の内容を`master`へ統合するrelease PRでリリース条件を確認する。 +公開tagは承認したrelease commitに付け、branch名だけを公開の根拠にしない。 + +CIは`dev`向けPRと`dev`へのpushを専用の入口から実行し、テスト・wheel buildの本体を +既存workflowと共有する。変更がMarkdown(`.md`)/reStructuredText(`.rst`)だけなら、 +`dev`ではworkflow自体を起動しない。code・設定・submodule更新を含む場合は通常どおり検証する。 +`master`向けPRでは既存の必須checkを維持するため、文書だけでもCIを実行する。 +release tagと手動実行も引き続き検証対象にする。 +GitHubのpath filterによる省略はPR全体の差分で判断され、code変更のあるPRへ文書commitを +追加した場合もCIは実行される。今後`dev`に必須checkを設定する場合は、文書PRでcheckが +未報告のままmerge待ちにならない設計を選ぶ。 +Rulesの適用範囲とprereleaseの起点も開発基盤整備で確認し、`dev`という名前だけで既存の +保護・release設定が引き継がれるとは仮定しない。 + +### uchardetのブランチ運用とsubmodule連携 + +PyYoshi/uchardetも`dev`をv3の開発統合先として分離する。 +開始点はcChardet 2.3.0が使用している`7993e0afe3b6c64f0ea3b43c7d4987118f6c5c12`とする。 +既存の`cchardet`を改名・置換せず、v2のnative保守先として残す。 + +| 用途 | cChardet側 | PyYoshi/uchardet側 | 連携方法 | +| --- | --- | --- | --- | +| v2安定版・保守 | `master`(v3公開前) | `cchardet` | v2互換の修正をnative側へmerge後、承認したcommitへsubmoduleを更新 | +| v3開発 | `dev` | `dev` | native側の`dev`向けPRをmerge後、cChardetの`dev`向けPRでcommitを固定 | +| 過去の実装 | 過去のtag・履歴 | `obsoleted-cchardet` | 履歴参照用。新規開発やv2保守のbaseにはしない | + +uchardetのv3作業branchは`dev`から作り、Draft PRのbaseも`dev`とする。 +既存のuchardet `master`はv3統合先に転用せず、現在の履歴を維持する。 +双方のrepositoryで`dev`を作っても、自動的に同じ時点の実装になるわけではない。 + +cChardetのv3開発側では`.gitmodules`の`branch`を`dev`、v2保守側では`cchardet`とする。 +URLは引き続きPyYoshi forkを指す。`branch`は主に`git submodule update --remote`で参照する +branchの指定であり、通常のcheckoutやCIが使うのは親repositoryに記録したcommitである。 +branch指定だけの変更ではgitlinkを進めず、実際のnative更新は別途レビュー・検証する。 +CIやrelease buildでbranch先端を自動取得せず、必ず記録されたcommitを使う。 + +共通のbug修正は、v2でも成立する小さな修正なら`cchardet`へ先に適用し、 +`dev`向けの別PRでcherry-pickまたは同等の修正を反映する。 +v3で先に見つけた問題はv2への影響を調べ、必要な修正だけを個別にbackportする。 +元PR・commitと反映先を紐付け、両方で検証する。v3のbranch全体をv2へmergeしない。 +upstream由来の修正も、各branchへの必要性とAPI互換性を確認して取り込む。 + +3.0公開時にもuchardetの`cchardet`はv2保守先として維持し、`dev`はv3系列の統合先として使う。 +nativeのrelease対象commitを記録し、cChardet releaseのgitlinkで固定する。 +cChardetの`master`をv3へ移行する前には、2.xの保守を継続する場合の専用branchと保守期間を +Betaまでに決める。安定版branchを移行したためにv2の修正先が消える状態にしない。 +uchardetの`dev`に適用するCI・RulesもPhase 1で確認し、branch作成を保護設定の完了とは扱わない。 + +### Repository間の分担とPR + +- cChardetは、全体ロードマップ、Python API/CLI、packaging、downstream連携、 + Python経由の競合比較、リリース時の移行案内を管理する。 +- PyYoshi/uchardet forkは、native build、安全性検証、fuzzing、内部状態の追跡、C API、 + engine benchmark、engineの挙動比較を管理する。v2は`cchardet`、v3は`dev`で管理する。 + 実体のあるforkを使い、submoduleはcommitを固定する。 + `.gitmodules`をAPI互換性のないupstreamへ切り替えない。 +- corpus/model toolは、まず利用するnative engineと同じforkに置く。 + Python製toolにはuvでlockした環境を用意し、取得・生成・評価を別moduleとして扱う。 + data専用repositoryへの分離は後から判断し、初期着手の前提にはしない。 +- native変更をforkのPRでmergeした後、依存するcChardet側PRでsubmoduleを更新する。 + 連携testは実際に固定するnative commitを対象にする。 + cChardetとuchardetのversion番号を揃える必要はなく、native ABIのversionは別に判断する。 +- PRはDraftで作成する。local検証後に関連変更をまとめてpushし、CIの再試行や状態確認のためだけに + pushを繰り返さない。不要なCIはcancelし、重い定期job・release wheel buildと軽いPR検証を分ける。 +- Gitには小さな再配布可能fixture、schema、生成recipe、設計判断、要約reportを置く。 + 大規模dataと生のbenchmark結果は別保管とし、hashと保管先・保持方針を記録する。 + 通常のCIではWebのlive crawlingを行わない。 + +実装時の配置案は以下とする。まだ存在しないpathを含み、実装済み成果物や実行可能commandを +表すものではない。 + +| 管理先 | 配置するもの | +| --- | --- | +| cChardet | `docs/decisions/`、`docs/v3-migration.md`、version付きbenchmark report | +| uchardet | `CMakePresets.json`、`fuzz/`、`test/`または`tools/`内の挙動比較・trace tool | +| uchardet | `corpus/`内のschema・manifest・recipe、`modelgen/`内のoffline generator | +| uchardet | model一覧と`legacy`/`generated`の由来分類。実際のfile移動は必要性がある場合に行う | + + + +## 優先順位・依存関係・リリース範囲 + +| Phase | 優先度 | 依存するもの | 完了を示す成果物 | リリース上の位置づけ | +| --- | --- | --- | --- | --- | +| 1. native開発基盤 | P0 | 現状棚卸し | 移植可能なbuild、安全性検証、挙動比較、trace | 3.0の必須基盤 | +| 2. corpus/model基盤 | P0/P1 | Phase 1のbaseline。schema作業は並行可能 | 監査済みcorpus v1、用途別分割、再現可能なmodel生成の試作 | 3.0の必須基盤。全model置換は不要 | +| 3. 失敗分析 | P1/P2 | Phase 2の評価dataとPhase 1のtrace | 再現可能な失敗report、優先順位付き改善候補 | 3.0で利用者に届ける変更を選ぶ | +| 4. 対象を絞った精度改善 | P2 | Phase 3 | 変更前後のreport、意図した候補差分、移行判断 | 3.0の候補 | +| 5. encoding/language拡充 | P2 | Phase 2〜3 | 独立dataで評価したmodel追加と処理cost測定 | 3.0または後続v3の候補 | +| 6. 段階的検出とevidence方針 | P3 | Phase 3〜5の知見 | hint、入力制限、早期終了の実験 | 3.0に含めるか個別判断。後続なら互換性を再確認 | +| 7. Rust試験実装 | P4 | Phase 1〜2のmodel・挙動の契約 | 挙動を維持した並行実装と比較report | 3.0の必須条件ではない | +| 8. 次世代model/engine | 研究 | Phase 2〜3。実装言語比較にはPhase 7 | 現在の限界を根拠にした設計提案 | 後続。互換性は改めて判断 | +| 9. 高度な最適化 | P5 | profilingで確認した遅い箇所と回帰検証基盤 | portable fallback、runtime dispatch、実測した効果 | 必要な場合のみ | + +主要な順序は「1 → 2 → 3 → 選択した4/5 → 3.0」とする。 +corpus schemaとmodelの棚卸しはPhase 1と並行できるが、検出結果を変える作業は評価基盤を待つ。 +後半のPhaseは、問題なく動くengineを必ず書き換えるという約束ではない。 +3.0公開後に必要になった破壊的変更は、ロードマップに載っていたことを理由にminor releaseへ +押し込まない。必要なら次のmajor releaseで扱う。 + + + +## Phase 1: native実装を安全に変更し、結果を説明できるようにする + +### Build・静的解析・CI + +Debug/Releaseとsanitizer有効化を分離する。CMake/compilerの最小versionは、実際に使う機能と +wheelの対象環境から決めて文書化する。 +C++20を有力候補として検証し、安全性・保守性に役立つ機能を採用する。 +既存のC++11維持を目標にはせず、採用する機能と配布条件を根拠に規格を決める。 +warning、sanitizer、benchmark、fuzzのoptionをtarget単位に整理し、static/shared build、 +install/exportのsmoke test、再現可能なpresetを用意する。 +native toolはPythonをimportせずにbuild・実行できるようにする。 + +setuptools経由の拡張module buildには独自の連携がある。 +CMakeの検証だけでwheelも確認できたとは扱わず、両方を検証する。 +platform・浮動小数点flagの変更は候補scoreに影響し得るため、toolchain整理とscore変更を分ける。 +配布binaryでは`-march=native`や実行環境を選ぶISAの無条件有効化を行わない。 + +### C++規格とmemory safetyの改善 + +規格の更新だけで安全になるとは扱わず、所有権・寿命・境界条件をcodeで表現するために使う。 +まずC++20で必要な機能を小さく試し、配布対象すべてで検証してから採用を確定する。 +さらに新しい規格の機能も、解決する問題と配布costを示せる場合は個別に検討する。 + +| 改善対象 | 採用候補 | 確認すること | +| --- | --- | --- | +| 所有するbuffer・resource | `std::vector`、`std::unique_ptr`などのRAII | 解放漏れ・二重解放・error経路の後始末を減らす。再利用するbufferのallocation回数や初期化costも測る | +| 借用するbuffer | C++20の`std::span`、読み取り専用なら`std::span` | pointerとlengthの食い違いを減らす。所有者・有効期間・再allocationによる無効化を明示する | +| 状態・値の区別 | `enum class`、index/長さなど用途ごとの型 | magic valueや異なる単位の混同を減らす。C APIとの変換点で値域を検証する | +| model tableの整合性 | `constexpr`、`static_assert` | tableの寸法・定義・参照の整合性をbuild時に検証する。生成物にも検証を適用する | + +RAIIなど既存規格でも使える機能の導入を、C++20採用の決定まで待つ必要はない。 +一方、`std::span`は所有権を持たず、参照先の寿命や範囲外アクセスを自動的に保証するものではない。 +境界検査、整数overflow、符号付き/符号なし変換、buffer無効化の規則は別途整理する。 +`const`なviewでも別threadによる元bufferの書き換えは防げないため、Pythonから借用する可変bufferと +GIL解放の扱いも確認する。ASan/UBSan、fuzzing、allocation失敗の検証と組み合わせる。 + +規格採用の判断では、構文のcompile成功と、標準library・runtime・ABIの互換性を分けて確認する。 + +- Linux: 対象manylinux imageと最小glibc条件を固定し、必要なC++機能をbuildする。 + `auditwheel`で`GLIBC_*`/`GLIBCXX_*`などの要求を調べ、最低対応環境でwheelを実行する。 + musllinuxを追加する場合は別の配布対象として検証する。 +- Windows: 対応MSVC toolsetとruntime条件を決め、生成したwheelのimport・native処理を検証する。 +- macOS: Apple Clang、SDK、deployment target、libc++の機能可用性を確認し、最低対応OSで実行する。 +- Python連携: standalone CMakeとCython/setuptoolsの両経路で同じ規格方針を適用し、 + 通常版・free-threaded版のwheelと、sdistからのbuildに必要なcompiler条件を確認する。 + +結果は「使う機能・規格・最小toolchain・最低対応OS/runtime・検証artifact」を対応付けた +設計判断に残す。利用したい機能が現在の最低環境で使えない場合は、代替実装だけでなく +v3で最低環境を引き上げる選択肢も、利用者への影響と利益を比較して判断する。 + +PRは、規格/build設定の変更、所有権・型の整理、検出algorithmの変更に分ける。 +所有権の整理は小さな対象から進め、同じ入力・feed手順で候補結果を比較し、 +allocation・memory・latencyの変化を測る。必要なerror契約の変更は明示的にレビューする。 +規格更新と同時にscoreやrankingを変えず、差分の原因を追える状態を維持する。 + +### CIの実行範囲 + +| CI区分 | 対象 | 初期budget・運用方針 | +| --- | --- | --- | +| 関連PRごと | Linux GCC/Clang、Windows MSVC、macOS Apple Clang。代表的なDebug/Releaseとstatic/shared | 全組合せではなく必要な軸を覆う。native job単位で15分以内を初期目標 | +| native PRごと | Linux ASan + UBSan、決定的な挙動比較、最小化済みfuzz回帰入力 | 問題検出時は失敗させる。sanitizer有効時の速度を通常buildと比較しない | +| native PRごと | Clang Static Analyzer、対象を絞ったclang-tidy | 既存指摘には理由・担当を付け、新しい未説明の指摘を増やさない。抑制よりinvariant明示を優先 | +| native PRごと | 時間制限付きlibFuzzer smoke test | 初期値はtargetごと60秒。既知の回帰入力は毎回再実行 | +| 定期・手動 | 長時間fuzz、compiler構成の拡大、利用可能ならnative ARM64、統制した環境での性能測定 | fuzzはtargetごと30分を初期値とし、実行回数・coverage・seed corpusを記録 | +| Release candidate | サポートするPython/wheel matrix、installed-wheel smoke、sdistからのbuild | 通常版とfree-threaded版。リリース時の対応範囲を明示 | + +これらの時間は初期案であり、現在のCI設定でも、十分なfuzz coverageの証明でもない。 +実測に応じて調整する。依存libraryのinstrumentationとplatform条件が整う場合に、 +未初期化memory検出のMSan、独立detector間の競合検出のTSanを検討する。 +CodeQLはlocal解析が役立つ状態になってから、導入・維持costを踏まえて判断する。 + +### Nativeの挙動比較とfuzzing + +既存の候補出力toolを拡張し、比較結果を機械可読にする。 +fixtureと決定的に生成した入力ごとに、one-shot、1・7・64・1,024 byte単位、 +seed固定のrandom境界でfeedする。 +空・極短入力、NUL、壊れたmultibyte sequence、長い繰り返しや不利な入力、reset/reuse、 +複数回のfinalize、candidate取得、終了状態を対象にする。 +fuzz入力には上限を設ける。巨大入力やallocation失敗は別のresource budgetとfault injectionで +検証し、通常のPRに数GiBのfixtureを要求しない。 + +次の2種類の比較を区別する。 + +1. **変更前後・実装間の同等性**: 同じ環境・同じfeed手順で旧実装と新実装を比較する。 + candidate数・順序、encoding、language、confidence、最終結果、error、終了eventを対象にする。 +2. **chunk境界によらない結果の一致**: 同じbytesを異なる区切りで渡した場合を比較する。 + まず現状の差を記録し、bug、仕様上の早期終了の影響、意図したv3の仕様変更のどれかを判断する。 + 変更前後で同じだったことは、chunk境界への非依存性を証明しない。 + +呼び出し側が渡したbyte数、観測可能な範囲でengineが実際に調べたbyte数、`done`が変化した +eventを記録する。chunk単位の終了判定を、終了の根拠になった正確なbyte位置とはみなさない。 +終了後のfeedを無視・拒否・継続処理のどれにするかも、trace比較の前に定義する。 + +同じtoolchainで挙動維持を目的とする変更は、まずexact comparisonを基準にする。 +既存toolの10進数出力は出発点として使うが、bit単位の一致を主張する場合は浮動小数点の +生の表現も記録する。異なるtoolchain間の差は、根拠のないepsilonで隠さず、数値計算の契約を決める。 + +public APIと関連するmodel/state machine内部をfuzzし、one-shotとincrementalの比較も行う。 +失敗は最小化し、seed、build flag、再現commandを付けてtest data policyに従って保存する。 +allocation失敗を注入し、OOM時の解放・error通知を検証する。 +C ABI境界から想定外の例外が漏れないようにする。 + +独立detectorと共有する不変model dataのthread safetyを定義する。 +可変なdetectorを複数threadで共有できるかは別の契約であり、GILを解放するだけでは保証されない。 + +### 内部状態の追跡とmodel生成過程の調査 + +任意で有効化するnative traceに、稼働・除外されたprober、score、language、状態遷移、 +早期終了理由、rankingと同点処理の理由を記録する。 +分析に使う理由codeとmodel/prober IDは安定させ、詳細event形式は開発用interfaceとして扱ってよい。 +release buildではtraceをcompile時に除外するか、無効時costが十分小さいことを測定する。 +入力本文はデフォルトでlogに残さない。 + +model familyごとにgenerator、入力source、revision、license表記、parameter、生成file、 +手動変更を棚卸しする。`script/BuildLangModel.py`、language/charset定義、既存logから始める。 +既存手順で自動生成が説明されているのはsingle-byte modelであり、multibyte tableにも +同じ手順が使えるとは仮定しない。追跡できない由来は「不明」と記録し、推測で埋めない。 +調査は既存modelの理解とprovenance把握のために行い、既存generatorの改修・再利用を前提にしない。 + +保守者から、過去の利用で「同じ処理を繰り返しても結果が安定せず、生成modelの品質がかなり +落ちる傾向があった」と報告されている。これは過去の経験に基づく判断材料であり、今回の +再現実験で原因を特定したという意味ではない。v3では既存のmodel生成scriptの使用を推奨せず、 +新しい生成基盤の依存にしないことを基本方針とする。 + +調査範囲は入力取得・正規化・統計処理・出力形式・既知の制約の把握に絞る。 +旧scriptの再現や修復を新規開発の必須条件にはしない。 +v3側での削除は、依存するbuild・文書・生成物の参照と必要な由来記録を確認したうえで別PRにする。 +v2の保守branchと既存modelは一括削除しない。既存modelの品質とgeneratorの品質も別々に評価する。 + +Phase 1の完了条件は、新規checkoutから文書どおりにbuild・検証できること、既知の安全性問題と +test失敗が見えること、native比較を再現できること、代表的な誤判定をtraceで説明できること、 +model生成の再現可能範囲と不足が明確になっていることとする。 + + + +## Phase 2: corpusとmodelの再現可能な基盤を作る + +### Corpusの役割・層とdata混入の防止 + +corpusの**用途**と**性質による層**を別々に扱う。 +用途はtraining/model生成、tuning、validation、independent evaluationの4区分とする。 +層は次のとおり。 + +| 層 | 目的 | 初期候補と制約 | +| --- | --- | --- | +| A: 文字・構造の網羅 | codec mapping、状態遷移、境界条件 | version固定のmappingと生成case。自然言語精度の根拠にはしない | +| B: 制御した自然文 | language model、ranking、confidence、入力sizeごとの傾向 | 由来を確認した多言語Unicode sourceをstrictに再encode | +| C: 独立評価 | 汎化性能と競合比較 | revision固定のchardet/charset-normalizer corpusなど、独立して管理されるdata | +| D: 実際の文書 | 壊れたdata、宣言、現実の取り込み処理 | local archive抽出と再配布可能な文書。Common Crawl本文はcommitしない | + +encoding変換、切り出し、HTML化、size別生成を行う**前に、元の文書/source group単位で分割**する。 +分割のseed、algorithm、割り当て結果を固定する。 +完全一致・近似重複を検出し、可能な範囲でlegacy corpus/modelのsourceとの重複も調べる。 +過去の学習dataとの重複が不明なら、完全に独立した評価とは主張しない。 +評価dataの失敗を見てtuningした場合は、その参照を記録する。 +以後の独立評価には新しい未参照のholdoutを用意する。 +同じ原文の文字コード違い・size違いを別の独立文書として数えない。 + +source候補は、多言語自然文のLeipzig、mapping・境界条件のUnicode data、作品ごとに権利確認した +Gutenberg、local Web評価のCommon Crawlとする。 +collection全体で同じlicense・再配布権・生成modelの配布条件が適用されるとは仮定せず、 +dataset単位で確認する。取得adapterは任意で使えるものとし、取得不能によって通常buildが +壊れたり、評価の母数が黙って減ったりしないようにする。 + +archive由来sampleはsnapshot、WARC位置、offset/length、content hash、抽出recipe、正解labelの +根拠を持つ。charset宣言だけを正解にはしない。 +確認済みlabel、複数のcompatibleな可能性、未解決caseを分ける。 +未解決caseは堅牢性や遭遇頻度の観測に使い、正解率を出すために推測でlabelを付けない。 +archiveの公開状況や削除要請で再現できなくなったsampleは、欠落として明示する。 + +### Manifestと生成の契約 + +version付きJSON/JSONL schema、validator、受理・拒否される小さな記述例を用意する。 +初期の必須項目は以下とする。 + +| 記録 | 必須情報 | +| --- | --- | +| Source | 安定したID、URL/保管位置、license識別子・原文参照・確認状態、revision、元dataのhash、languageとlabel決定方法 | +| Sample | schema/corpus version、sample/source-group ID、用途・層、language、encodingとlabel確度、encoder/version、source textとbytesのhash、byte/文字数、変換parameter、生成日時 | +| 派生関係 | 親ID、正規化方針、切り出し範囲、目標/実size、分割先、途中切断・不正sequenceの状態、該当するHTML templateと宣言 | +| 実行記録 | manifest hash、tool/engine commit、環境、command、seed、除外/欠落数と理由、成果物hash | + +元のUnicode sourceを保存し、正規化、改行変換、大文字小文字処理、本文選択を明示・version管理する。 +判定に役立つ情報を黙って正規化で消さない。 +encodeはstrictを使い、decodeで元に戻ることを確認する。 +表現できない文は生成対象から外した理由を記録し、`ignore`/`replace`で黙って変換しない。 +alias、CP932とShift_JISのようなvariant、superset関係は実際のmappingに基づくversion付き定義で扱う。 + +入力sizeは16・32・64・128・256・512 B、1・4・16・64・256 KiBを目標budgetにする。 +正常sampleは完全なencoded文字境界で止め、実sizeを記録する。 +stateful encodingは終端・状態の復帰も含めてbudget内で正しく生成する。 +sequence途中で切れるsampleは、明示的な途中切断・異常系として別に生成する。 +短いsourceを繰り返しで埋めて、大きな自然文の代表として扱わない。 +同じ本文を使う比較と、同じbyte budgetを使う比較も区別する。 + +plain textはclean/adversarial、HTMLはclean/declared/undeclared/mismatched/malformedに分ける。 +HTTPとmetaの不一致、UTF-8宣言なのにCP932のbytes、宣言なし、XML宣言、entityの多いmarkupなどを含める。 +宣言内容と実際のencodingは独立に記録する。 +API response、CSV、e-mail、subtitle、document exportも由来を確認したworkloadとして段階的に追加する。 +生成HTMLだけで実Webの評価を済ませない。 + +### Model生成とprovenance + +生成pipelineは完全新規実装を基本とする。既存scriptを抽出・整理して使い続ける計画にはしない。 +取得 → 正規化 → language/encodingによる選別 → 統計生成 → 検証 → 出力を、それぞれ検証可能な工程として設計する。 +必要な仕様・数式・data形式とその出典を記録し、旧codeやtableを取り込む場合は再利用として明示する。 +新しいfileに書いたことだけを理由に、独立した由来や希望するlicenseを適用できるとは判断しない。 +まず棚卸しを基にsingle-byteのlanguage/encoding familyを1つ選ぶ。 +再配布可能な小さなcorpusで決定性を検証し、別途、現実的なtraining dataでmodel品質を調べる。 +小さなdataから再現可能に生成できただけでは、実用modelが完成したとはしない。 + +generator/runtime/dependencyはuvで固定し、走査・出力順序、乱数seedを固定する。 +network利用は取得工程に限定する。 +独立したclean環境で2回生成し、canonicalなmodel内容のhashが一致することを確認する。 +実行日時はcanonicalな内容から分離するか再現可能な時刻規則を使い、 +記録用timestampのために同じmodelが異なるhashにならないようにする。 +同じ作業directoryで繰り返しても既存出力を二重集計しないこと、途中失敗後の再実行でも +結果が変わらないことを検証する。固定入力に対する決定性と再実行時のべき等性を別々に確認する。 +生成したmodelは同じengine上で既存modelと比較し、未使用dataで精度・候補・confidence・ +性能を評価する。hashが一致するだけでは品質の合格とせず、採用基準を満たすまで既存modelを置換しない。 + +生成modelにはmodel/format version、generator version/commit、corpus revision/hash、 +source license参照、language/encoding family、生成parameter、由来分類、生成日時の規則、 +内容hashを付ける。legacy modelの実際のlicense表記や不明項目は保持する。 +新しいgeneratorで処理しても、再利用したtableや変換処理の由来が消えるわけではない。 + +試作modelには、特定言語に依存しない小さな表現形式を定義する。 +tableの次元、順序、数値型、量子化、検証条件を明示し、まずbuild時のC++ source生成を使う。 +必要性を示さずruntime loaderやallocationを追加しない。 +出力前に次元・値域・参照を検証し、将来のRust emitterも同じcanonical artifactを使う。 +初期schemaで歴史的modelすべてを表す必要はなく、未対応familyを明記してversionを上げながら拡張する。 + +### 新規fileのlicenseを決める時期と対象 + +新規fileに適用するlicenseは未決定である。 +利用・組み込み・開発参加のしやすさを重視し、LGPL、MIT、Apache-2.0などを候補として比較する。 +LGPLはversionと「or later」の有無も決める。以前のMPL-2.0を第一候補とする案は固定方針にせず、 +由来に応じた条件を確認する。ここでは候補の適用可否や既存資産のrelicense可否を確定しない。 + +Phase 1のV3-01でlicenseの設計判断を行い、対象componentの新規実装・外部contributionを +受け入れる前に、そのcomponentで使うlicenseとfile表記の規則を決める。 +model generatorの新規実装まで未決定を持ち越さない。 +全componentを一括で決める必要はないが、未決定の対象を明示する。 + +| 対象 | 判断時に確認すること | +| --- | --- | +| 新規engine/tool/generator/test | 独自実装か既存codeの派生か、依存library、希望するlicenseの適用条件、利用・修正・配布時の扱い | +| 既存codeと改修file | 現在のlicense・著作権表示・由来。新規file向けの選択を一律に適用しない | +| Corpus | sourceごとの条件、取得・加工・再配布・model生成に関する確認事項 | +| Generated model/table | corpus・generator・再利用tableの由来、生成物の配布条件。generatorと同じlicenseだと自動判断しない | +| 開発文書・schema・sample | codeと同じ方針にするか、外部資料やsampleの条件、帰属表示 | + +判断結果は`docs/decisions/`に日本語で残し、対象範囲、採用licenseとversion、選定理由、 +未解決事項を記録する。確定後、対応するLICENSE/COPYING、file header/SPDX、package metadata、 +contribution案内を整合させ、配布物の表記も確認する。 +希望するlicenseへの移行を妨げる既存資産は由来を追跡し、必要なら段階的な独自実装・model置換を検討する。 +既存の表示を削除して方針に合わせることはしない。 +取り込み・再配布・表記変更前の確認が済まないdataは、local参照に留める選択肢を持つ。 + +Phase 2は、corpus v1、検証済みのmanifest/分割validator、決定的なsize/encoding/HTML生成、 +provenance一覧、C++ emitterを含む再現可能な試作modelが揃った時点で完了とする。 +不明な歴史的training dataの復元や、全legacy modelの置換は完了条件にしない。 + + + +## Phase 3: 失敗を分析し、改善対象を選ぶ + +固定した2.3.0 referenceと開発中engineを、利用可能な固定済みcorpus全体に対して実行する。 +sampleごとの予測、候補、score、label確度、source group、入力size、model version、必要なtraceを残す。 +corpus・language・encoding family・size・workload別に件数と母数を公開し、 +data欠落、未対応codec、判定保留、crash、誤判定を区別する。 + +失敗は無理に一つへ分類せず、根拠とともに複数labelを付けられるようにする。 + +| 分類 | 必要な根拠 | +| --- | --- | +| `UNSUPPORTED_ENCODING`、`MODEL_MISSING` | 対応一覧・model一覧と、欠けているcodecまたはlanguage coverage | +| `WRONG_ENCODING_FAMILY`、`RIGHT_FAMILY_WRONG_CODEC` | version付きfamily/mapping定義と候補の観測結果 | +| `SUPERSET_AMBIGUITY`、`INSUFFICIENT_EVIDENCE` | 複数codecで同じbytesが妥当・同値になること、または識別根拠の不足 | +| `RANKING_FAILURE` | 正しい可能性のある候補が負けた理由を示すtrace。候補に含まれることだけでは断定しない | +| `CONFIDENCE_CALIBRATION` | 定義したscoreの意味と実際の正解頻度が、未使用dataでも継続してずれること | +| `STRUCTURAL_VALIDATION_FAILURE`、`LANGUAGE_MODEL_FAILURE` | decoder/state machineまたはmodel/proberの挙動による根拠 | +| `DECLARATION_CONFLICT` | bytesとmetadata・宣言内容の不一致 | +| `UNRESOLVED` | 根拠不足。考えられる原因を残して調査する | + +top-k candidate recallを測り、候補生成とrankingの問題を分ける。 +confidenceは初めから正解確率とはみなさず、まずscoreとして扱う。 +何の正しさを校正するのか(exact codec、compatibleなdecode、languageとの組合せ)を定義し、 +binごとの件数を伴う信頼度曲線や、判定保留率と誤り率の関係を調べる。 +確率としての校正結果は未使用dataで評価する。 + +少数の文書しかない区分から強い結論を出さず、件数の不足を明示する。 +不確かさを推定する際はsource group単位で再標本化し、多数の派生sampleを独立観測として扱わない。 + +改善候補は、実際の遭遇頻度と誤判定cost、見込める精度改善、実装工数、実行時間・memoryの増分、 +provenanceの整備状況から優先順位を付ける。 +costが高いほど優先度が上がるような単純な掛け算は使わない。 +収集しやすいcorpusでの頻度を、そのままWeb全体の頻度とはみなさない。 +選んだencoding familyごとに根拠と不確かさを公開する。 + +Phase 3は、再実行可能なreport、人が確認した代表的失敗、優先順位付きbacklog、3.0範囲の決定で完了とする。 +評価指標の定義はレビュー・version固定し、競合すべてに同じものを適用する。 +現在の`chardet.evaluation`依存もversion付きの実装であり、永遠に不変な正解定義として扱わない。 + + + +## Phase 4〜6: 根拠に基づいて検出器を改善する + +### Phase 4: 対象を絞った修正 + +確認できた構造検証・BOMの問題、model選択、ranking、confidenceから着手する。 +変更ごとに失敗分類を紐付け、一般化できるbytes/modelの性質を修正し、 +成立する例・成立しない例・曖昧な例を用意する。 +corpusごとの変更前後の全結果と候補差分を、悪化したcaseも含めて公開する。 +外部benchmarkに直接合わせる調整や、その場しのぎのheuristicの積み重ねは避ける。 + +languageのconfidenceはencoding labelと区別する。 +ASCIIだから英語とは限らず、複数言語が混じる入力は、無理に一つを断定せず +unknownや複数languageを表す仕様が必要か検討する。 + +### Phase 5: 必要性の高いcoverageを増やす + +調査候補は日本語、簡体字・繁体字中国語、韓国語、Cyrillic、中東欧、トルコ語、ギリシャ語、 +ヘブライ語、アラビア語、ベトナム語とする。 +これは候補一覧であり、これらがすべて未対応という意味ではない。 +実際に不足するlanguage/codecの組合せはPhase 3の結果から選ぶ。 + +model追加ごとにprovenance、training/tuning/evaluationの分離、独立corpusと実dataでの検証、 +別familyの誤検出、初期化・allocation cost、model size、throughput、候補安定性を確認する。 +旧modelと新modelを同じengineで比較してから、engine書き換えの効果を判断する。 + +### Phase 6: 段階的な判定とcontent hint + +安価な構造検証(BOM、ASCII、UTF-8としての妥当性、UTF-16/32構造、escape sequence)と、 +任意のXML/HTML/HTTP hintを試作する。 +特に短いASCII互換入力では、UTF-8として妥当なだけで元のencodingを確定できるわけではない。 +選んだ仕様の下で確定的な根拠になるものと、候補の順位付けに使うものを分ける。 + +metadataの不一致・欠落、壊れたmarkup、hintとbytesの不整合時の挙動を定義する。 +native側で処理量に上限のあるparseを行い、costを測る。 +HTML専用APIまたは明示的hintを検討し、汎用detectにWeb固有の意味を黙って持ち込まない。 +統計的な判定ロジックはnative側に置く。 + +evidence limitは64 KiB、200 KiB、1 MiB、unlimitedを比較する。 +識別に必要な情報が後半に現れる入力も含め、調べたbyte数、精度・confidence、latency、 +allocation、memoryを報告する。 +現在のunlimited defaultは比較基準であり、v3の制約ではない。 +根拠が揃えば変更し、明示的に制限を解除する方法と移行案内を用意する。 + +早期終了と候補の枝刈りは、捨てる候補の上限に関する根拠、または実測による評価を必要とする。 +後続bytesが判断を覆すcaseを検証する。 +architecture変更の前にprofilingと失敗分析を行い、重複計算をSIMDで埋め合わせない。 +Phase 4〜6は大きな一括mergeではなく、選んだ機能ごとに完了を判定する。 + + + +## Phase 7〜9: 代替実装と長期研究 + +Rustの試験実装は、共通のmodel形式と挙動比較の契約が使えるようになってから着手する。 +目的は性能比較に加え、安全に保守できることと開発参加の容易さである。 +C++を実行可能なreferenceとして残し、最初は入力から結果までを通せる小さな範囲を選ぶ。 +初期portは承認済みmodelを再利用して挙動を維持し、score/model改善と同じ変更に混ぜない。 + +encoding、language、candidate、状態を型で表し、可変状態はdetector内に閉じ、所有関係を明確にする。 +通常の検出logicはsafe Rustを基本とし、`unsafe`はFFI、dispatch、最適化kernelなどへ局所化して +必要な理由を記録する。 +`cargo test`、rustfmt、clippy、property-based test、fuzzing、Miri、sanitizerは、 +それぞれ実際に検証できる範囲を踏まえて使う。 + +薄いC ABI層は選択肢だが、Rust内部へC APIの構造をそのまま移す理由にはしない。 +FFI境界ではbufferの寿命、所有権、panic/errorの変換、独立detectorのthread safetyを定義する。 + +同じfeed手順、壊れた入力、lifecycle、終了event、候補順序・language・confidence、model内容を比較する。 +数値計算の契約上可能ならexactに一致させ、不一致を調査した後でのみ根拠のある許容差を検討する。 +native latency、throughput、memory、allocation、並列scaling、binary size、build/install cost、 +wheel対応範囲も比較する。 +Rustで書いたという事実だけでは、安全性、独立した著作物であること、license適合性の証明にはならない。 + +Rustを主実装にするか、両engineを維持するか、C++を主実装のままにするかは、比較reportの後に決める。 +独自生成modelの拡大や新architectureは、既存の限界を示す根拠が得られてから、互換性も別途判断する。 + +SIMDやarchitecture固有kernelは最後に検討する。 +profilingで確認した遅い箇所、runtime feature dispatch、portable fallback、architecture間の正しさ、 +小〜中規模workloadでの実際の利益を条件とする。 +dispatch・allocation・保守のcostが効果を上回る最適化は採用しない。 + + + +## 測定方法と変更の受け入れ基準 + +engineの性能改善にはnative C API benchmarkを使う。 +cChardet/chardet/charset-normalizer間の比較にはinstall済みrelease wheelを使う。 +native engineの処理時間とPython API経由の時間は意味が異なるため、別々に公表する。 + +競合に利用可能なnative acceleratorがあれば有効にし、実際にloadされたmodule pathを確認する。 +Pure Python fallbackは別構成として報告し、package名だけから実装方式を推測しない。 +version、wheel hash、interpreter/GIL mode、compiler flag、CPU/OS、利用可能ならaffinityと電力設定、 +corpus hash、commandを記録する。 + +bytesは測定前にmemoryへ読み込み、code/modelを同じ条件でwarm-upする。 +baselineと変更版の実行順を交互にし、測定値の分布を保存する。 +detectorを毎回生成する場合とreuseする場合の両方を測る。 +warm-upを理由に、毎回生成する測定から初期化costを黙って除外しない。 + +最上位結果だけの取得と全候補取得、serialとmulti-thread、one-shotとincrementalを分ける。 +I/O込みのend-to-end測定は別枠にする。 +affinityを設定できないplatformでは未設定と記録し、同じ統制条件を満たしたと主張しない。 +p50/p95 latency、throughput、allocation回数・byte数、peak memory、model/binary sizeを、 +測定toolの制約とともに報告する。 + +精度reportにはexact codec、compatible/superset、decode-equivalent、language、 +encodingと言語の組合せ、判定保留、正解不明による除外を含める。 +decodeはstrictに行い、不正・途中切断入力でdecode-equivalenceを定義できない場合は別に扱う。 +corpus別・区分別の件数を維持し、macro平均やworkloadで重み付けした平均だけにまとめない。 + +リリース時には精度・性能reportに加え、次の評価表を維持する。 + +| 評価軸 | 残す根拠 | +| --- | --- | +| Coverage | codec/language/script対応一覧、観測した未対応sample、明示したworkload分布に限った重み付きcoverage | +| 堅牢性 | 最小化した異なるfuzz不具合、sanitizer指摘、chunk/lifecycle不一致、OOM処理結果、fuzzのcoverageとbudget | +| 保守性 | 新規checkoutからのsetup手順・時間、検証したcompiler/platform、静的解析の残課題、model生成の再現性、由来の未解決事項 | +| 代替engine | FFI/unsafeの使用箇所と理由、buildの複雑さ、挙動差、速度・memoryと並べた維持cost | + +fuzzで失敗を観測しなかったことをmemory safetyの証明とはしない。 +対応encoding数が増えたことだけを、実際のdataに対する精度改善ともみなさない。 + +Phase 1のbenchmark手順とともに確定する、初期のレビュー基準は次のとおり。 + +- **安全性**: 未調査のcrash、sanitizer error、新しい静的解析指摘、不正な出力を残さない。 + 既知の問題は明示し、xfailを精度testの成功として数えない。 +- **機械的変更・port**: 定義した同等性の範囲で、未説明の候補・lifecycle差分を残さない。 + 意図して変える挙動は別のレビュー対象にする。 +- **性能**: 主要workloadのいずれかで、native median latency/throughputに再現する5%超の悪化、 + またはp95/memory/allocationに10%超の増加があれば調査する。 + throughputの悪化はbytes/secの減少、latencyの悪化は時間の増加であり、同じ百分率として扱わない。 + allocationが0だった処理は百分率ではなく絶対数で比較する。 + noiseが大きい、または測定数が不足する結果は未確定とし、統制した環境で再測定する。 +- **精度**: 正解が既知の入力で変わった結果をすべて列挙する。 + 全体の改善でfamily/size別の未説明の悪化を隠さない。 + 曖昧な入力で想定した変化や統計的に未確定の改善は、そのように明示する。 +- **トレードオフ**: 精度と性能の交換は、対象範囲、測定結果、緩和方法を記録した判断で受け入れられる。 + 閾値はレビューのきっかけであり、価値あるv3変更の禁止でも、閾値未満なら無条件に悪化してよいという意味でもない。 + + + +## v3で決める契約と移行方針 + +publicな挙動を変更する前に、以下の設計判断を文書として残す。 + +| 判断対象 | 決めること | 判断時期 | +| --- | --- | --- | +| 結果・confidence | mappingか型付きresultか、unknown/判定保留、scoreの意味、language名、候補の同点処理 | 新しい結果APIの実装前。Betaまでに固定 | +| Streaming | `done`、終了後feed、finalize/reset、未完のmultibyte状態、chunk非依存性、error | 挙動比較の期待値をv3の契約にする前 | +| Resource・evidence | default `max_bytes`、切り詰めの通知、copyと寿命、GIL解放中の可変buffer、OOM | 制限やbuffer処理の変更前 | +| Hint・検出範囲 | 汎用とHTML/XMLの区別、metadata優先順位、不正/binary/混在encoding入力の扱い | hint APIまたはfallback方針の変更前 | +| Native境界 | 公開symbol、該当するABI version/SONAME、所有権、error code、Cythonとの結合 | native API変更と連携PRの前 | +| C++規格・安全性 | C++20を有力候補とした機能選定、RAII/借用view/型の方針、標準library・runtime条件 | 規格依存機能の導入前。各配布環境での検証を根拠に決める | +| Platform | Python/compiler/CMake最小版、architecture、free-threaded対応、packaging負担 | Beta前。偶然サポートを失わない | +| 新規fileのlicense | LGPL/MIT/Apache-2.0等の比較、component別の適用範囲、version・表記・contribution方針 | Phase 1のV3-01で着手。対象componentの新規実装・外部contribution受入れ前 | +| Data/model | format version、reader互換性、由来、配布条件 | model公開前。新規generatorのlicenseは実装前に決定 | +| Engine選択 | Rust試作の完了条件、両実装の維持cost、default engine | Phase 7の根拠が揃ってから | + +破壊的変更ごとに、旧/新の例、影響する利用者、変換方法または代替API、変更されるversion、 +理由、回帰検証、戻す方法を示す。 +意味が曖昧な互換flagより、明確な移行を優先する。 +低costでできるなら2.xでの非推奨化は有用だが、正当なv3変更の必須条件にはしない。 + +2.xへの新機能backportや無期限保守は本書では約束しない。Beta時点で保守期間を定義する。 +2.3.0はbenchmark referenceとして固定し、結果やconfidenceの意味を永久に縛る仕様にはしない。 + + + +## 最初の実装単位 + +各行はPRに分けて着手する単位の案とする。 +nativeとwrapperで管理先が異なる場合は、依存関係を示した別PRに分ける。 +現時点ではすべて未着手。本ロードマップPRと`dev`作成は、以下の実装完了には数えない。 + +| ID | 管理先 | 作業・成果物 | 受け入れ条件・依存関係 | +| --- | --- | --- | --- | +| V3-01 | 両repository | baseline棚卸し、両repositoryの`dev`のCI・Rules確認、新規fileのcomponent別license判断。既知の失敗・toolchain・model family・benchmark manifestと測定hashを記録 | 再現手順を記録。測定なしに性能効果を主張しない。新規実装前に対象licenseを決定 | +| V3-02 | 両repository、別PR | sanitizerとDebugの分離、build preset、C++20機能と配布互換性の検証、規格採用の設計判断 | GCC/Clang/MSVCとApple Clang、CMakeとCython経由で検証。最低対応runtimeでwheelを実行しsdist要件も記録。V3-01に依存 | +| V3-03 | uchardet | 機械可読なnative出力、比較harness、終了/lifecycle case | 同じfeedでの同等性とchunk間差分を分けて報告。V3-01 | +| V3-04 | uchardet | ASan/UBSan preset、上限付きfuzz target、回帰seed | 再現可能なsmoke実行と最小化入力の再検証。V3-02/03 | +| V3-05 | uchardet中心、必要に応じwrapper | Analyzer/tidyの既存指摘一覧、RAII・借用buffer・状態/値の型・compile時検証による安全性改善 | 小さなPRに分けて候補同等性とallocation/memory/latencyを検証。規格更新・判定のtuningと分ける。V3-02/03、安全性検証はV3-04も利用 | +| V3-06 | uchardet | 任意で有効化するprober/ranking trace | 代表的失敗を説明でき、無効時costを測定済み。V3-03 | +| V3-07 | uchardet | corpus manifest/分割schema、license一覧、validator | 権利情報欠落や分割を跨ぐ派生dataを拒否。V3-02と並行可能 | +| V3-08 | uchardet | offline strict再encode、正常境界でのsize生成、HTML生成 | 決定的hash、生成できなかった件数、data混入test。V3-07 | +| V3-09 | uchardet | legacy generatorの参考調査、新規offline generator・試作model・C++出力。旧script廃止は参照確認後に別PR | 決定性・再実行のべき等性・未使用dataでの品質を別々に検証。新規generatorのlicense決定済み。V3-01/07/08 | +| V3-10 | 両repository | 失敗report、top-k分析、coverage/ranking改善の優先順位 | 代表例を確認済みで、未参照holdoutがある。V3-03/06/08 | +| V3-11 | cChardet | 3.0範囲・契約の設計判断、移行案内の初版 | V3-10から測定可能な利用者向け改善を選ぶ。日程を満たすために範囲を捏造しない | +| V3-12 | 両repository、別PR | 選択した修正/model、submodule連携、report | 上記の基準、wheel/API test、意図した差分のレビュー。該当するV3-09/10/11 | + + + +## リリース条件・リスク・進捗管理 + +### Alpha・Beta・正式版の条件 + +**Alpha**: Phase 1〜2の一連の工程が小さな対象で動き、選択した利用者向け改善を評価pipelineに +通せること。試験中・破壊的なAPIを明記し、未完了の項目も公開する。 +Alpha公開を安定性の保証とはしない。 + +**Beta**: Phase 3で範囲を合意し、選択した機能が受け入れ基準を満たすこと。 +publicな契約と移行例を固定し、corpus/modelの由来を確認済みとする。 +対応platformと2.xの保守方針を文書化する。 +HTML/CSV/streaming/threadingなど、代表的なdownstream利用をsmoke testへ加える。 + +**Release candidate・3.0**: 固定した評価と統制した性能測定を再現し、公開を妨げる安全性問題と +未説明の挙動回帰を解消する。 +対応するwheelとsdistをinstallした状態で、型情報、CLI、free-threaded動作まで検証する。 +code/model/corpusのrevisionと成果物を紐付ける。 +release notesは直前のstableとの差分にし、2.xの機能を新機能として再掲しない。 +[リリース手順](releasing.md)に従い、最初のAlpha前にprerelease用の手順も整備・検証する。 + +全corpusの置換、Rust、段階的検出、SIMDの完了を一律に3.0の条件にはしない。 + +### 主なリスクと対応 + +| リスク | 対応・再判断のきっかけ | +| --- | --- | +| 互換性が必要な改善を妨げる | v3の破壊的変更と移行記録を使う。3.0以後は次のmajorが必要か再評価 | +| 基盤を整えても明確な精度改善が出ない | 改善しなかった結果も公開し、label/traceを改善して範囲を見直す。benchmarkの見かけだけを良くしない | +| corpusの偏り・混入・正解の曖昧さ | source groupで分割、参照履歴、未使用holdout、確度を区別した指標 | +| corpusの消失・配布権不明・model由来不明 | 再配布を保留し、hash/recipeと不明点を保持。監査可能な置換を優先 | +| 新modelで速度・memoryが悪化 | modelごとのcostを報告し、根拠のある枝刈りを検討。正当化できない増分は採用しない | +| platformや浮動小数点計算による差 | compiler matrix、明示した契約、不一致の再現artifactを保存 | +| CI cost・Actions rate limit | local検証、まとめたpush、上限付きPR job、重い処理の定期実行 | +| Rust portだけが膨らむ | 小さな試作と比較判断を区切りにし、C++ referenceを維持 | +| 文書と実装が乖離する | 実装PRで完了の根拠と設計判断も更新 | + +### 進捗の記録方法 + +GitHubでの作業は[cChardetのv3 Issue一覧](https://github.com/PyYoshi/cChardet/issues?q=is%3Aissue+label%3Av3) +へ集約し、ロードマップ追跡IssueからV3-01〜V3-12へリンクする。 +uchardet実装もここで追跡し、実装先repository・base branch・依存Issue・完了条件を明記する。 +実装PRは対象Issueへリンクし、native側のmergeだけでPython連携まで完了したとは扱わない。 +初期の作業は「v3 基盤整備・スコープ確定」milestoneにまとめ、期日は根拠が揃うまで設定しない。 +Rust/SIMDなどの条件付き研究を3.0の必須作業として扱わない。 + +作業は未着手・進行中・blocked・延期・完了で管理する。 +完了にはmerge済み実装、再現command、artifact hash、受け入れ条件の根拠への参照を必要とする。 +blockerや延期理由は記録し、黙って完了条件を縮めない。 + +Phase 1終了時、最初の失敗report完成時、各リリース判定時に本書を見直す。 +合意した方向性、提案中の閾値、試験的な選択肢、測定済みの結果を区別し、 +範囲の変更と設計判断をGitの履歴で追跡できる状態を維持する。