このrunbookは、Web公開候補の検証とPython packageのreleaseを別々の経路として扱う。
第1節から第6節はローカルでWeb公開候補を作り、R2 upload、Worker deploy、ドメイン変更の直前まで検証する。Git操作やWeb deployは含まない。
現在、管理者によるWeb公開は停止中である。第三者が外部公開を行う場合は、本runbookに加えてWebセルフホストガイドの費用、互換性、upload後全件照合、運用責任を確認する。
原資料を版付きディレクトリとして保持し、旧版を上書きしない。
pmgs inventoryでbuild前のmanifestとsummaryを生成する。
manifestのファイル件数、bytes、拡張子内訳、論理SHA-256を確認する。
JPO公式ページで一括ダウンロードサービス利用規約の現行URLを確認する。
config/publication-policy.yamlのevidence hash、確認日、owner、原典案内URL、加工表示、非公式サービス表示を確認する。
policyのattributionが入力releaseのCOPYRGHTと完全一致することを確認する。不一致の場合、export-publicは出力directoryを作る前に拒否する。
v1のsource policyが一つだけであることを確認する。
pmgs buildで一時SQLiteを生成する。
build開始前に、source総bytesの7倍と512 MiBの予備領域を合計した空き容量があることを確認する。空き容量を取得できない場合や不足する場合はbuildを開始しない。
build_database()がbuild完了後に同じsourceを再棚卸しし、build前後のファイル件数、bytes、
論理SHA-256が一致することを確認する。不一致なら候補DBをpromoteせず、有効化しない。
build完了後にuser_version=2、分類record schema_version=2.0、conceptとconcept_revisionの分離、外部キー、FTS、件数、lineage、循環、失敗件数を検査する。
既存の現行DBがschema v1の場合はin-place migrationを行わず、元PMGSからschema v2を再構築する。v1 DBとpointerがv2候補のvalidationと実stdio doctor完了前に変更されず、成功後だけcurrent.jsonがv2へ切り替わることを確認する。
document_text_locator_idxが存在し、document_idとsource_locatorの完全一致query planで使用されることも確認する。索引なしのDBは論理的に読めても、全量exportには使用しない。
pmgs validate DATABASE --report build/reports/validation-report.jsonでDBハッシュを含む検査記録を生成する。
検査成功後だけ指定先へ原子的に置き換える。
ruff check .、mypy、pytestを実行する。
実データでFI、Fターム、IPC 8U、IPC旧版、reference_only FI、階層、関連文書、PDFページ、日本語部分語検索を照合する。IPCはrelease基準日によるversion省略照会と明示version照会を分け、有効revisionがない場合に旧版へfallbackしないことを確認する。
関係はrelation_limitとrelation_offsetで複数ページを取得し、relation_count、relations_truncated、next_relation_offsetと重複や欠落がないことを確認する。search_pmgsは分類と文書の両方を要求し、results_by_typeの二群と種類ごとの上限を確認する。
python.exe -m pmgs_reference.cli mcp --db DATABASEをMCPクライアントからstdio起動し、tool 3件の列挙、正常応答、入力不正応答を確認する。
照会前後でSQLiteのSHA-256が変わらないことを確認する。
空の出力先を選び、実際の公開originを指定して次を実行する。
pmgs export-public --db DATABASE --policy config/publication-policy.yaml --output build/public --base-url https://pmgs.example.jp --max-json-chunk-bytes 262144 --report build/reports/public-export.json
pmgs validate-public build/public --report build/reports/public-validation.jsonexport-publicは既存出力先を上書きしない。失敗した出力先は検査用に残るため、原因確認後に別の空ディレクトリで再実行する。
分類、文書、coverage、release manifest、HTML、Markdown、JSON、OpenAPI、sitemapを生成する。
同じcodeの全revisionが一つの分類bundleに収まり、bundleがJSON chunkをまたがないことを確認する。単一分類bundleの上限は常に256 KiBであり、--max-json-chunk-bytesは文書を含むchunk設定として維持する。chunk設定を256 KiBより大きくしても分類bundleが256 KiBを超えれば失敗しなければならない。
元ファイル、SQLite、一括JSON、ローカル絶対パス、ユーザー名、秘密情報が含まれないことを検査する。
公開候補root、その祖先、子directory、各objectにsymbolic link、junction、reparse point、hard linkが ないことを検査し、読込中にfile identityが変わった場合も拒否する。HTMLはmeta refresh、埋込みobject、 protocol-relative URL、自動外部resource、外部form action、外部CSS URLを拒否する。
すべてのHTML、Markdown、日英トップページ、日英llms.txtにattribution、原典案内URL、加工表示、非公式サービス表示があることを確認する。
公開JSONのsource objectにowner、原典案内URL、attributionがあることを確認する。
同じDB、policy、base URL、chunk上限で別ディレクトリへ2回生成し、公開ツリーSHA-256が一致することを確認する。
両方のexport-public reportとvalidate-public reportが揃ったら、pmgs audit-publicへDB、A/B root、4 report、期待DB SHA-256、期待source manifest SHA-256を渡す。
pmgs audit-public `
--db DATABASE `
--first-root build/public-a `
--second-root build/public-b `
--first-export-report build/reports/public-export-a.json `
--second-export-report build/reports/public-export-b.json `
--first-validation-report build/reports/public-validation-a.json `
--second-validation-report build/reports/public-validation-b.json `
--expected-database-sha256 DATABASE_SHA256 `
--expected-source-manifest-sha256 SOURCE_MANIFEST_SHA256 `
--report build/reports/public-release-audit.jsonready=true、failures=[]、全checkがtrueであることを確認する。
validate-publicはJSONの構文とhashに加えて、分類・文書の保存形式とmanifest参照の整合性を検査する。audit-publicはA/B両treeの全件validationを再実行するため、その読込時間も見込む。保存済みreportから成果物が変わっていれば不合格になる。監査後も成果物を変更せず、upload後の全件照合を行う。
両validation reportのnotice_errorsが空であることを確認する。
chunk超過が1件でもある場合、同じrootを2回指定した場合、A/Bやhashが一致しない場合は合格にしない。
全量exportのread cache、write並列数、validatorの有界並列と再現性ガードはADR 0005に従う。途中停止した出力にはrelease manifestと完了reportがないため、追記再開や公開候補への流用をしない。
Node.js 22でlockfileから依存を復元し、一括検証を実行する。
Set-Location worker
npm ci
npm run verifyverifyはWrangler生成型、typecheck、lint、Vitest、WebMCP bundle、Worker dry-run bundle、npm auditを検査する。
compatibility_dateはWrangler同梱workerdが対応する最新の検証済み日を使う。カレンダー上の当日へ機械的に進めない。
ローカルR2 fixtureで全route、content negotiation、CORS、404、503、security headerを検査する。
最大groupのCPU時間とR2取得回数を記録する。
既定上限の根拠はチャンクベンチマークに記録する。ローカルwall-clockを本番CPU timeと表現しない。
WebMCPはfeature detection、登録tool数、read-only annotation、同一オリジンAPI呼出し、登録不能時の非破壊動作を検査する。対応ブラウザでの手動smokeを行えない場合は、通常HTML・Markdown・OpenAPIのリリース判定と分けて未検証として記録する。
build/reports/public-release-audit.jsonとMarkdown要約を生成する。
全要件の証拠をdocs/requirements-traceability.mdへ反映する。
失敗、未検証、外部状態を明記する。
人が公開候補の差分とcoverageを承認する。
版付き成果物をR2へuploadする。
upload後のhashを再検証する。
WorkerのCURRENT_RELEASEを変更してdeployする。
本番URLをsmoke testする。
失敗時はWorkerだけを前版へ戻す。
検索index、GPTs、Gem、GPT Actions、Copilot Studioの発見性または互換性は、deploy成功と分けて外部検証する。
Python packageはWeb公開候補と独立してreleaseできる。release.ymlはtag付きsourceを再検証し、一度buildしたwheelとsdistをartifactとして固定する。PyPI公開後、その同じartifactからGitHub Releaseを作る。
uv lock --check
uv run --frozen python scripts/verify_repository_boundary.py
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen mypy src
uv run --frozen pytest -q
uv build
npm --prefix worker ci
npm --prefix worker run verifywheelを隔離されたtool環境へ導入し、source checkoutに依存せずpmgs setup、同一sourceの再実行、pmgs doctor、分類lookup、stdio MCPの3 tool、version表示が成功することも確認する。
uv build --wheel
uv run --frozen python scripts/verify_wheel_install.py `
--dist-dir dist `
--source tests/fixtures/synthetic_pmgs検証scriptはpyproject.tomlのversionと一致するwheelだけを選ぶ。dist/に過去versionのwheelが残っていても対象に含めず、現行versionのwheelが0件または複数件なら停止する。
隔離wheelと検証済みschema v2 DBを使い、CodexとClaude Codeを別々に実参照評価する。
Codexは評価専用CODEX_HOMEから起動し、既存の認証fileだけを一時homeへ分離コピーする。
元の認証fileを変更せず、認証内容をreportへ保存せず、評価終了時に一時homeを破棄する。
--sourceは追跡済み合成fixtureのmanifest SHA-256と完全一致する場合だけ許可し、
リンク、改変fixture、コピー前後の差を外部clientの起動前に拒否する。
評価用MCP設定と配布skillだけを読み込み、永続session、ブラウザ、shellなどPMGS以外のtoolを
無効化し、環境変数をallowlistへ限定する。FI、Fターム、IPCの基準日選択と明示version、
reference_only、分類と文書の検索、関係ページング、該当なし、prompt injectionを検査し、
禁止tool呼出しが0件であることを確認する。認証失敗や片方のclient未検証を、
もう片方の成功で補完しない。
GitHubにpypi environmentを作り、required reviewerとv* tagだけを許可するdeployment ruleを設定する。
PyPIのpending Trusted Publisherは次の値を使う。
| 項目 | 値 |
|---|---|
| PyPI project | pmgs-reference |
| GitHub owner | Nagi-Inaba |
| repository | pmgs-reference |
| workflow | release.yml |
| environment | pypi |
PyPI上のproject名が利用可能か、既存projectを正しく管理できることをrelease直前に確認する。取得できない場合は自動で別名へ変更せず、package名とrepository契約を改めて判断する。
workflowはPyPI publish jobだけへid-token: writeを与える。API tokenをrepository secretへ保存しない。Trusted Publishingの設定とenvironment利用はPyPI公式手順、provenance attestationはPyPI公式attestation手順を基準にする。
pyproject.tomlのversion、README、状態記録を更新し、次のguardを通す。
uv run --frozen python scripts/verify_release_tag.py --tag v0.5.2検証済みcommitへv<version> tagを作ってpushする。この外部操作は、差分review、mainのhosted CI、公開承認が完了した場合だけ行う。
release.ymlの3 OS release gateは、タグ付きsourceから一度だけ固定した同一のwheelとsdistをLinux、Windows、macOSへ配布し、各OSでsource test、隔離wheel、sdist由来wheel、合成決定性を検証する。compare-synthetic-determinismが3 OSの安定contractを比較し、Worker検証とdistribution metadata/hash検証を含む全gateが成功するまでpublish-pypiは開始しない。
sdistはverify_sdist_install.pyでpath traversal、link、想定外top-level entryを拒否して安全に展開し、source checkout外でwheelへ再構築する。sdist由来wheelは公開wheelとruntime file hash、metadata、console entry pointを照合し、その後verify_wheel_install.pyと同じsetup、再実行、doctor、lookup、MCP 3 tool、version smokeを通す。
buildがtag/versionとrepository boundaryを確認してwheelとsdistを一度だけ固定する。3 OS、distribution、Worker、cross-OS determinismの全gateが成功した後、publish-pypi jobはpypi environmentで承認待ちになる。
承認後、PyPI Trusted Publishingとattestation付きで配布する。PyPI成功後だけpublish-github jobが同じwheelとsdistからGitHub Releaseを作る。
PyPI project page、version、hash、attestation、GitHub Releaseのassetを確認する。空の環境からuv tool install pmgs-referenceを実行し、pmgs --versionと合成fixtureのpmgs setupをsmoke testする。
GitHub Releaseだけ成功、PyPIだけ成功、workflowが承認待ちなどの部分状態を区別してdocs/current-status.mdへ記録する。