[V3-11] 3.0の範囲・API契約・移行方法を確定する #125

親トラッカー: #114

目的・成果物

3.0範囲・契約の設計判断、移行案内の初版

実装先・順序

• 実装先: cChardet
• v3実装PRのbase: 対象repositoryのdev。Draft PRで作成する。
• Phase: 3
• 前提となる作業: [V3-10] 失敗分類・top-k分析から改善対象を順位付けする #124
• 新規実装のライセンスはV3-01で対象componentごとに決定する。

作業

• 破壊的変更は利益と影響を記録して選択可能とし、旧/新の利用例と移行手順を用意する。
• 3.0への必須作業とRust/SIMD等の後続研究を分離する。

完了条件

V3-10から測定可能な利用者向け改善を選ぶ。日程を満たすために範囲を捏造しない

• 対象の実装PR・設計判断へのリンクを記録する。
• 再現command、検証結果、必要なartifact hashを記録する。
• 未解決事項・既知の制約と、依存先への影響を明記する。

現在の実績（2026-09-21）

• 基盤整備と標準採用の条件を分離し、日本語で記録（v3: corpus・内部観測・再現可能なモデル生成を統合 #131/生成モデルの採用判断と内部選抜の観測を更新 #163/[skip-build] 固定ratioモデルのchunk差分と採用制約を記録 #167）。
• 2件の試作枠を明確化：BOM buffering、新規model生成pipeline。
• モデル品質後退とincremental制約を踏まえ、今回の生成modelの標準採用を推奨しない判断材料を記録。
• 測定可能な利用者向け改善を選定する。
• 選定した変更のAPI/既定値/互換性を確定し、旧新利用例・移行手順を作る。

新規generatorは非デフォルトでnative接続・品質評価まで進んだが、既定model/APIへの採用は未決定。BOM試作はP01依存で保留。基盤の完成と試作の不採用を、本Issueの利用者向け成果選定の代わりにはしない。

判断材料・残るD01〜D06/P01:
採用条件、判断ログ、品質結果、incremental制約。
公開仕様の変更が未確定のため架空のmigration手順は書かない。

第3試作の判断と着手（2026-09-22更新）

#171で#124の開発順位を確定。先行候補はSBCS filterのincremental証拠の一貫性。

• 固定blockへ外部feedを正規化するnative adapterの非デフォルト実験案を提示。
• 2026-09-22のmaintainerの再開指示に基づき、第3の非デフォルト試作へ着手。
• 実験契約を固定し、native Draft PR PyYoshi/uchardet#46で実装・固定tuning評価に着手。標準採用は別判断。

提案契約: 同じbyte列/evidence limitを同じ内部block列へ変換。EOFで端数を一度flush、空feedではflushせず、resetで端数とcoreを破棄。メモリはblock長に比例させ、文書全体を保持しない。doneのcore処理位置とcaller feed境界を区別する。旧whole-inputのcandidate/confidence/doneとの一致や精度向上は約束しない。

既存filterのbyte出力完全維持・append-only出力・固定メモリの同時成立に制約があるため、単純な状態持越しとは別案として評価する。これは統計の仮保存等の別設計を否定するものではない。

根拠・設計案・選択肢。元の2試作はBOMとgeneratorとして保存。第3試作の許可確認に対する2026-09-22の再開指示を受け、adapterを追加した。P01解除・標準採用の承認とは解釈しない。独立holdout未開封・公開API/既定model不変を維持する。

第3試作の初期結果

uchardet Draft PR #46。通常小入力1000比較成功。固定tuning 16入力×4内部block×5外部chunkの320観測で、同じblock長の候補/done/core処理位置が一致。cp1252 decode-equivalentはblock 1/7/64/1024で0/6/8/8（各8入力）。block長選定や一般的精度改善は未確定。report content hash d198e153f5167a561d5809f011717def074fb3ab3991d84fa0f438bad816c63d、再実行全byte一致。
初回11 CI成功。追加回帰テストを含むhead 676dde4も全11 CI成功。native #46をmerge済み。Python側submodule統合も#172で通常17 CI成功後merge済み。性能/memory測定・標準採用・移行案の完成とは区別する。

第3試作の統合状況（2026-09-22）

• native PR #46は最終11 CI成功後merge。固定commit 058aec784a0891103584a79c7c52b217340db67d。
• cChardet PR #172でsubmodule固定と日本語契約/結果を統合済み。通常CI run 35623116962の17件成功後merge、wheelのみ明示省略。統合commit 6e208b021b968e74f548d6642968604c5b1ca154。
• ローカルpytest 355 passed / 15 skipped / 88 subtests。小入力1000比較・tuning320観測・report再実行一致。詳細は#172のdocs/v3-fixed-block-pilot.md。
• 既定engine/API/modelは不変。第3試作追加は個別許可であり、P01解除や無制限の試作追加ではない。
• 次は採用前の性能/memory・別validation・block選定/公開契約。[V3-11] 3.0の範囲・API契約・移行方法を確定する #125/#126はこの比較基盤だけで完了にしない。milestoneは6/12のまま。

第3試作の追加評価・統合完了（2026-09-22）

• native PR #47は全11 CI成功後merge。固定点 2863aeaf420d766c05dfa8c44604c33f20fe9d91。
• cChardet PR #173は通常17 CI成功（run 35625843669）後devへmerge。最新統合点 6fabbdd7826a231d7ab26c45b63aefb7e2da6a83。wheelのみ省略。
• ローカルpytest 362 passed / 15 skipped / 94 subtests。native診断suite 38成功・5 skip。
• 既存validation32入力×4 block×5外部chunkの640観測で、同じ内部blockなら結果が一致。64/1024はcp1252 decode-equivalent16/16を維持するが、候補/confidenceは旧wholeと異なる。
• CPU固定のnative warm reuse性能を2 run測定。64-byteは外部wholeの文書別5%超悪化が14/16・15/16と再現。1024は同条件で両runとも5%超なし。
• 1/7は品質、64は性能に採用上の問題が残る。1024は追加評価候補で、まだ標準採用しない。

日本語の結果・再現・hash。性能は文書別trial平均の合計であり、request p95やcorpus-pass latencyではない。初回確保・allocation・peak/live memory・別言語/domain・公開契約の検証が残る。独立holdout未開封、P01保留、既定API/model不変。#125/#126は未完了、milestoneは6/12。

allocation観測の統合完了（2026-09-22）

• native PR #48: 全11 CI成功後merge、e5272917896eb49dc4860204fead1d1e7bdb1482。
• cChardet PR #174: 通常CI run 35627297523成功後devへmerge、最新統合点 631600384a85926dcba8c3176e4990d21b29a4b0。wheelのみ省略。
• ローカルpytest 365 passed / 15 skipped / 94 subtests。native診断suite 41成功・5 skip。
• 固定tuning16入力で1024-byte adapterの構築時newは直接fixedより1回多い。初回/warm文書の対象8 counterは一致し、外部whole/1-byteでも同じ。計測なし版・保存canonical観測との候補全体一致、report再実行全byte一致を確認。
• これはselected static-link API call counts。strdup等shared-library内部は対象外であり、physical allocationやlive/peak memoryの測定ではない。対象counterが0でも無allocationと解釈しない。

結果・再現・制限。report content hash f1e073ce9e72d360435be5986af752c18e4f01d48b0edd29d1fc90ccceb22dad。
Valgrind 3.27.1とMassifの導入を確認済み（2026-09-22）。通常小入力のpeak/live memory測定は未着手で、maintainerの希望により一時停止中。保留中のP01/fuzz/OOMは再開しない。追加platform・別言語/domain・request p95・公開契約/採用条件は引き続き残る。

一時停止・次回の再開地点（2026-09-22）

maintainerの希望により、allocation観測の統合とValgrind導入確認までで一区切りとし、開発・自動継続を一時停止した。この記録更新のみ実施し、新しい実装や計測は開始していない。

• 完了済み: native PR #48とcChardet PR #174のdev統合。#174のmerge commitは 631600384a85926dcba8c3176e4990d21b29a4b0。ローカル作業ツリーは変更なし。
• 環境確認済み: /usr/bin/valgrind、valgrind-3.27.1、Massif利用可能。導入待ちは解消したが、peak/live heap memoryの実測はまだ行っていない。
• 次回は明示的な再開指示後、通常の小規模入力（既存pilotの上限4096 bytes）でメモリ計測を準備する。既存の固定tuning16入力、whole/direct fixed/1024-byte adapterの比較条件と候補一致を維持する。
• 計測時は構築・初回・warm・破棄の区間、requested heap bytesとprofiler推定overhead、入力/実行環境/tool versionを区別して記録する。既存allocation API counterをlive/peak bytesとみなさない。Valgrind下の実行時間を通常の性能比較に流用しない。
• 再開時に参照する資料: 固定block試作・結果、nativeの benchmark/fixed-block-allocations.ja.md。ローカルreportは archives/v3-corpus/fixed-block-allocations-v2.json（content hash f1e073ce9e72d360435be5986af752c18e4f01d48b0edd29d1fc90ccceb22dad）に保持。
• P01のfuzz/OOM/関連安全性・BOM調査は引き続き保留。独立holdoutは未開封。既定API/modelは変更せず、1024-byte blockの標準採用も未決定。
• [V3-11] 3.0の範囲・API契約・移行方法を確定する #125/#126は未完了のまま。メモリ・追加platform/言語/domain・request p95・公開契約/採用条件などの残作業は、導入確認や今回の停止をもって完了扱いにしない。