chore: 0.1.1 公開前の品質関門（AI slop 排除・品質 MAX）

.gitattributes

@@ -0,0 +1,3 @@
+# scripts/licenses/ は、上流の原文をそのまま写したもの。行末の空白も原文のまま残し、
+# GitHub の言語の集計からも外す（COPYRIGHT-library.html は大きな HTML）
+scripts/licenses/** -whitespace linguist-vendored

.github/workflows/ci.yml

@@ -8,27 +8,62 @@ on:
 permissions:
   contents: read
 
+# PR は新しい push で古い run を取り消す。main の push は run ごとの group にして、
+# 取り消しも待機中の run の置き換えも起こさず、どのコミットにも結果を残す
 concurrency:
-  group: ci-${{ github.ref }}
+  group: ci-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
   ts-quality:
-    name: ts (biome + tsc + test)
+    name: ts (biome + tsc + test, node ${{ matrix.node }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # 24 = engines の下限（.nvmrc と同じ）、26 = 次の LTS
+      matrix:
+        node: [24, 26]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version-file: .nvmrc
+          node-version: ${{ matrix.node }}
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint          # biome check .
+      # npm の 2 パッケージ・proxy の crate・SAR の版と、SourceCodeUrl のタグ・CHANGELOG の見出し
+      - run: pnpm check:versions
       - run: pnpm build         # tsc emit — zankyo-cdk/dist を生成（examples の typecheck/test が依存）
+      # CLI のテストは src を型除去で実行する。公開する bin（package.json の bin が指す dist）の
+      # import 書き換えやパスの誤りは、ここで実際に起動して確かめる（bin.js は全コマンドを静的 import する）
+      - name: smoke-test the cli bin (dist)
+        working-directory: cli
+        run: node "$(node -p 'require("./package.json").bin.zankyo')" --version
       - run: pnpm typecheck     # tsc --noEmit in each package
       - run: pnpm test          # node --test in each package
 
+  construct-peer-min:
+    name: construct (aws-cdk-lib peer minimum)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # construct/package.json の peerDependencies の下限を正とし、devDependencies より
+      # 古い宣言値でも型検査とテストが通ることを確かめる（lockfile の書き換えはこのジョブ内だけ）
+      - name: install the declared aws-cdk-lib minimum
+        working-directory: construct
+        run: |
+          min=$(node -p 'require("./package.json").peerDependencies["aws-cdk-lib"].replace(/^[\^~]/, "")')
+          pnpm add --save-dev "aws-cdk-lib@$min"
+      - working-directory: construct
+        run: pnpm typecheck && pnpm test
+
   rust-quality:
     name: rust (fmt + clippy + test)
     runs-on: ubuntu-latest
@@ -38,22 +73,39 @@ jobs:
       - uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
       - run: cargo fmt --all -- --check
-      - run: cargo clippy --workspace --all-targets -- -D warnings
-      - run: cargo test --workspace
+      - run: cargo clippy --locked --workspace --all-targets -- -D warnings
+      - run: cargo test --locked --workspace
+
+  rust-msrv:
+    name: rust (MSRV)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      # proxy/Cargo.toml の rust-version を正とし、rust-toolchain.toml より
+      # 古い宣言値でもビルドできることを確かめる（RUSTUP_TOOLCHAIN が toml に優先する）
+      - name: install the declared rust-version
+        run: |
+          msrv=$(sed -n 's/^rust-version = "\(.*\)"/\1/p' proxy/Cargo.toml)
+          rustup toolchain install "$msrv" --profile minimal
+          echo "RUSTUP_TOOLCHAIN=$msrv" >> "$GITHUB_ENV"
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - run: cargo check --locked --workspace --all-targets
 
   audit:
     name: dependency audit
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: .nvmrc
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm audit --prod
-      - uses: rustsec/audit-check@69366f33c96575abad1ee0dba8212993eecbe998 # v2
+      # 最新のリリース v2.0.0 は node20 で動く。action.yml の runs.using を node24 に
+      # 変えただけの main のコミット（#48、未リリース）に固定する
+      - uses: rustsec/audit-check@858dc40f52ca2b8570b7a997c1c4e35c6fc9a432 # main (v2.0.0 + node24)
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
@@ -64,19 +116,85 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
-      - name: install musl tools + cmake (aws-lc-sys build)
-        run: sudo apt-get update && sudo apt-get install -y musl-tools cmake zip
-      - name: build x86_64
-        run: cargo build --release --target x86_64-unknown-linux-musl -p zankyo
-      - name: build aarch64 via cross (docker)
+      - name: install zip (layer packaging)
+        run: sudo apt-get update && sudo apt-get install -y zip
+      # 両 arch とも、Cross.toml で digest に固定したコンテナでビルドする。
+      # リリースの zip は、タグの commit でこの job が作った artifact を使う（RELEASING.md）
+      - name: build x86_64 and aarch64 via cross (docker)
         run: |
           cargo install cross --locked --version 0.2.5
-          cross build --release --target aarch64-unknown-linux-musl -p zankyo
+          cross build --locked --release --target x86_64-unknown-linux-musl -p zankyo
+          # 2 つのコンテナは glibc が違う（x86_64 は 2.31、aarch64 は 2.27）。1 つ目が
+          # target/release に作ったホスト用のビルドスクリプトは、2 つ目では実行できない
+          # （GLIBC_2.28 not found）。ターゲット別の成果物（target/<triple>/release）は残す
+          rm -rf target/release
+          cross build --locked --release --target aarch64-unknown-linux-musl -p zankyo
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
       - name: package layer zips
         # 直前ステップで両 arch をビルド済みなので梱包だけ行う
         env:
           SKIP_BUILD: '1'
         run: node scripts/build-layer.mts
+      # エントリの並びと mode（実行ファイルは 755、ライセンス表示は 644）と CRC を確かめる。
+      # THIRD_PARTY_LICENSES は、crate でない静的リンクの部品（Rust 標準ライブラリ・musl libc・
+      # LLVM の libunwind と crtbegin/crtend）の表示も、scripts/licenses/ の原文のまま含むこと。
+      # COPYRIGHT-library.html（Rust 標準ライブラリのファイルごとの表示）は、原文と同じバイト列であること。
+      # bin/zankyo は arch どおりの ELF で、動的リンカ（PT_INTERP）を要求しない静的リンクであること
+      - name: check the layer zips
+        run: |
+          shopt -s failglob
+          expected=$(printf '%s\n' \
+            '-rwxr-xr-x bin/zankyo' \
+            '-rwxr-xr-x extensions/zankyo' \
+            '-rwxr-xr-x zankyo-wrapper' \
+            '-rw-r--r-- share/licenses/zankyo/LICENSE' \
+            '-rw-r--r-- share/licenses/zankyo/THIRD_PARTY_LICENSES' \
+            '-rw-r--r-- share/licenses/zankyo/COPYRIGHT-library.html')
+          notices=(
+            scripts/licenses/rust-*/COPYRIGHT
+            scripts/licenses/rust-*/LICENSE-APACHE
+            scripts/licenses/rust-*/LICENSE-MIT
+            scripts/licenses/rust-*/LICENSES/Unicode-3.0.txt
+            scripts/licenses/rust-*/library/compiler-builtins/LICENSE.txt
+            scripts/licenses/musl-*/COPYRIGHT
+            scripts/licenses/llvm-*/libunwind/LICENSE.TXT
+            scripts/licenses/llvm-*/compiler-rt/LICENSE.TXT)
+          for pair in x86_64:X86-64 aarch64:AArch64; do
+            arch=${pair%%:*} machine=${pair#*:}
+            z=dist/layer/zankyo-$arch.zip
+            unzip -tq "$z"
+            diff <(echo "$expected") <(unzip -Z "$z" | awk '$3 == "unx" { print $1, $NF }')
+            unzip -q "$z" -d "$RUNNER_TEMP/layer-$arch"
+            node -e '
+              const { readFileSync } = require("node:fs");
+              const [file, ...notices] = process.argv.slice(1);
+              const text = readFileSync(file, "utf8");
+              const missing = notices.filter((n) => !text.includes(readFileSync(n, "utf8").trimEnd()));
+              if (missing.length > 0) {
+                console.error(file + " lacks:\n  " + missing.join("\n  "));
+                process.exit(1);
+              }
+            ' "$RUNNER_TEMP/layer-$arch/share/licenses/zankyo/THIRD_PARTY_LICENSES" "${notices[@]}"
+            cmp scripts/licenses/rust-*/COPYRIGHT-library.html \
+              "$RUNNER_TEMP/layer-$arch/share/licenses/zankyo/COPYRIGHT-library.html"
+            bin=$RUNNER_TEMP/layer-$arch/bin/zankyo
+            if ! readelf -h "$bin" | grep -q "Machine: .*$machine\$"; then
+              echo "$z: bin/zankyo is not $machine" >&2
+              exit 1
+            fi
+            if readelf -l "$bin" | grep -q INTERP; then
+              echo "$z: bin/zankyo is dynamically linked" >&2
+              exit 1
+            fi
+          done
+      # 引数なし・Lambda の外（AWS_LAMBDA_RUNTIME_API なし）では、usage を出して EX_USAGE（64）で終わる
+      - name: smoke-test the x86_64 binary in the zip
+        run: |
+          rc=0
+          "$RUNNER_TEMP/layer-x86_64/bin/zankyo" || rc=$?
+          test "$rc" -eq 64
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: zankyo-layer

.gitignore

@@ -20,4 +20,3 @@ apikey
 
 # Test artifacts
 coverage/
-*.xlsx

.nvmrc

@@ -1 +1 @@
-25
+24

ARCHITECTURE.md

@@ -32,27 +32,68 @@ platform が別プロセスで agent を起動する。in-flight イベントは
 `.inflight` ステージを書き、agent が SHUTDOWN で読んで
 timeout レコードへ変換する。完了した呼び出しのステージは
 proxy が即削除する（残存＝未完の証跡）。
+agent は passthrough 判定でも終了せず、`SHUTDOWN` だけを購読して
+待機する。登録前や `SHUTDOWN` 前に extension が終了すると、
+終了コードに関係なく platform が Init を失敗させるため。
+このとき設定が壊れている場合に備えて、Extensions API の設定
+（`ZANKYO_REGISTER_TIMEOUT_MS`・`ZANKYO_EXT_RETRY_MS`・`ZANKYO_EXT_BODY_KB`・
+`ZANKYO_EXT_MAX_POLL_FAILURES`）は読まず、既定値を使う。
+同じ理由で、register と `/event/next` の一時的な失敗は再試行し、
+`SHUTDOWN` まで終了しない。終了するのは、登録の 4xx 拒否・500
+（公式リファレンスが「回復不能。速やかに終了」と定める）・
+Runtime API への接続不能の継続（`ZANKYO_EXT_MAX_POLL_FAILURES` 回）の
+ときだけで、終了コードは 1 にする。
 
 ## 品質・保守性の不変条件
 
 このプロジェクトは次の不変条件を守る。レビュー・生成コードも同じ基準。
 
-- **設定は env → SSM overlay → 既定値の順で解決**。動作ノブ
-  （上限・タイムアウト・間隔）をコードへ埋め込まない。新しい数値設定は
+- **設定は既定値 → env → SSM overlay の順に重ねて解決**（後が優先）。
+  例外は SSM を読む前に決まるもの。取得に使う `ZANKYO_SSM_PARAM`・
+  `ZANKYO_SSM_TIMEOUT_MS` は env だけで決め、SSM の JSON では上書きしない
+  （`ssm_overlay.rs` の `ENV_ONLY_KEYS`）。env の `ZANKYO_DISABLED` の真と
+  env の設定エラーは、SSM を読まずに passthrough を決める。
+- **利用者が調整する動作ノブ（上限・タイムアウト・間隔）をコードへ
+  埋め込まない**。`ZANKYO_*` で変えられるようにし、新しい数値設定は
   `config.rs` の env 読み取り + `ssm_overlay.rs` の
-  `SSM_NUM_FIELDS` に 1 行で済む。
+  `SSM_NUM_FIELDS` に 1 行で済む。例外は下の「固定の安全上限」に挙げた
+  定数だけで、足すときは名前付きの定数にして表にも載せる。
 - **拡張はデータの 1 エントリ追加で完結**。scrub パターンは
   `scrub_data.rs`、CLI コマンドは `bin.ts` のディスパッチ、
   SSM キーは `SSM_NUM_FIELDS`、build arch は `TARGETS`。
 - **エラーは握り潰さない**。失敗は `ZankyoError`/`Option` でモデル化し、
   捨てる経路はすべて文脈付きの warn で残す。
 - **rerun は冪等**。spill は atomic 書き込み → 数・鮮度上限 →
-  起動時・定期回収 → 全件回収で dir 削除、とライフサイクルが閉じる。
+  起動時・定期回収 → 送れたファイルの削除、とライフサイクルが閉じる。
+  spill dir 自体は消さない（同時に走る書き込みが ENOENT で失敗するため）。
 - **型は緩めない**。TS は strict + noUncheckedIndexedAccess、`as`
   キャストなし（AWS 境界は `ports.ts` の構造的ポート）。Rust は
   `#![forbid(unsafe_code)]` + clippy -D warnings。書式は
   biome / rustfmt で CI 強制。
 
+## 固定の安全上限
+
+次の値は設定で変えず、コードの定数に固定する。どれもプロトコルや実装の都合で
+決まる安全のための上限か、短い待ち時間で、利用者の環境に合わせて変える値ではない。
+変えられる値は README の設定表（`ZANKYO_*`）にある。`proxy/tests/docs_it.rs` が、
+この表と `proxy/src` の定数を突き合わせる。
+
+| 定数 | 値 | 場所 | 役割 |
+|---|---|---|---|
+| `EXT_BODY_TIMEOUT` | 1 秒 | `extension.rs` | Extensions API の応答ヘッダーを受けてから、ボディを読み切るまでの上限。登録では、残り時間の方が短ければ残り時間 |
+| `ERROR_BODY_MAX_BYTES` | 4096 バイト | `extension.rs` | Extensions API のエラー応答のボディを、診断用に読む上限 |
+| `SHUTDOWN_DEADLINE_MARGIN_MS` | 200 ms | `extension.rs` | SHUTDOWN の `deadlineMs` の手前に残す余白。フラッシュ予算は、余白を引いた残り時間と `ZANKYO_FLUSH_BUDGET_MS` の小さい方 |
+| `SHUTDOWN_GRACE_CAP_MS` | 1 秒 | `orchestrate.rs` | 子が先に終了したとき、同じプロセスの extension に SHUTDOWN が届くのを待つ上限（`ZANKYO_FLUSH_BUDGET_MS` との小さい方） |
+| `DRAIN_SLACK_MS` | 1 秒 | `orchestrate.rs` | 終了時に保存の完了を待つ時間枠で、`ZANKYO_PUT_TIMEOUT_MS` に足す余白 |
+| `ACCEPT_BACKOFF` | 50 ms | `proxy.rs` | Runtime API の listen で、accept に失敗したときの再試行間隔 |
+| `DRAIN_POLL` | 10 ms | `proxy.rs` | 終了時に、実行中のハンドラが無くなったかを確かめる間隔 |
+| `PART_ORPHAN_GRACE` | 60 秒 | `spill.rs` | 書きかけの `.part` を、クラッシュ後の残りとみなして消すまでの猶予 |
+| `RECORDED_CAP` | 4096 件 | `inflight.rs` | 記録済みの requestId（二重記録の防止用）を覚えておく件数の上限 |
+
+設定で指定しても効かない場合が 1 つある。記録しない状態の agent は、設定が壊れている
+場合に備えて、Extensions API の 4 つの設定を読まず、既定値（`config.rs` の定数）を使う
+（上の「全体像」）。
+
 ## モジュール対応（proxy/src）
 
 | ファイル | 責務 |
@@ -63,15 +104,15 @@ proxy が即削除する（残存＝未完の証跡）。
 | `proxy.rs` | Runtime API の listen・経路判定・接続管理 |
 | `handlers.rs` | `/next`・`/response`・`/error`・`/init/error` の個別処理 |
 | `upstream.rs` | 上流 Runtime API への転送。hop-by-hop 除去と上限付きボディ読み |
-| `extension.rs` | Extensions API。internal ループと external agent（`.inflight` 変換） |
+| `extension.rs` | Extensions API。internal ループと external agent（`.inflight` 変換・passthrough 時の待機） |
 | `inflight.rs` | `/next`〜確定までのイベント保持（Mutex<HashMap>） |
 | `store.rs` | S3 PutObject とレコード組み立て（scrub 適用） |
 | `spill.rs` | /tmp 退避の管理。書き込み・回収・保持数上限・廃棄 |
 | `record.rs` | 保存レコードのスキーマ生成（serde） |
 | `scrub.rs` / `scrub_data.rs` | PII マスキングの純粋ロジックと判定データ |
 | `config.rs` / `ssm_overlay.rs` | env 設定解決と SSM JSON overlay（キーはテーブル駆動） |
 | `runtime.rs` | 子プロセス起動（passthrough / proxy）と終了コード変換 |
-| `ssm.rs` | SSM Parameter Store 取得（10s timeout、fail-open） |
+| `ssm.rs` | SSM Parameter Store 取得（既定 2s timeout、fail-open） |
 | `error.rs` / `lib.rs` | `ZankyoError` 統一型と公開面 |
 
 ## 拡張ポイント
@@ -80,7 +121,8 @@ proxy が即削除する（残存＝未完の証跡）。
   パターン自体は `scrub_data.rs` に 1 エントリ。
 - **設定項目**: `Config` + env 読み取りに追加。SSM は
   `SSM_NUM_FIELDS` に 1 行（フィールド単位パースで 1 キーの
-  書き損じが全体を壊さない）。
+  書き損じが全体を壊さない）。SSM を読む前に使う値は表に載せず、
+  `ENV_ONLY_KEYS` に足す。
 - **CLI コマンド**: `cli/src/commands/` に 1 ファイル + `bin.ts` に
   1 行。AWS 境界は `ports.ts` の構造的ポートに閉じる。
 - **failure type**: `record.rs` enum・写像・CLI の
@@ -100,7 +142,7 @@ proxy が即削除する（残存＝未完の証跡）。
 3. 失敗時: イベントを scrub → レコード JSON を生成 → /tmp へ先書き
    （write-ahead spill）→ bounded な S3 PutObject を **応答転送の前に**
    完了させる。呼び出し終了で環境が freeze されると非同期 PUT は
-   進まないため、失敗経路だけこの順序を取る（成功経路はコスト 0）。
+   進まないため、失敗経路だけこの順序を取る（成功経路は spill も PUT もしない）。
    PUT が間に合わなければ spill が残り、定期回収・次回 init が拾う。
 4. SHUTDOWN（reason: timeout/failure/spindown）: external extension の
    agent が残った `.inflight` ステージを読み、「応答が返らなかった