test: enforce private production rustdoc contract

[seonghobae]

Refs #103.

Private-production rustdoc contract

This quality lane owns compiler-enforced private-production rustdoc only. It does not change gateway routing/auth/business authority, runner selectors, documentation/coverage denominators, dependencies, or release semantics.

Historical repair through 42e76fca398d15c5e1ec664d0e95afa72eb92389 documented private production items exposed by the compiler contract without broad allow, warning suppression, filler rustdoc, or runtime semantic changes. #16 and then refused-origin successor #119 were adopted through ordinary two-parent reconciliation.

#18 integration and current reconciliation — 2026-09-20

Previous exact 7d576d2ceb7d4b7f6159d0795aa638ac37cf2ac3 had already reached Supply Chain 35449295385 SUCCESS and CI 35449295421 had oci-runtime and load-contract SUCCESS while test was in coverage execution. Those receipts became historical as soon as parent #18 normally integrated as c78a296a87972845f8f9724e2cf2072d95a7df34; they do not transfer to the current ancestry.

The parent movement was repaired without force-push or destructive rebase. Two-parent commit 1b8c34ffe43c89faeb4520a33e5b6ff9811b44a3 records prior #104 as first parent and integrated #18 as second parent. Its tree takes current #18 as baseline and reapplies only the fifteen production Rust documentation blobs. Ordinary follow-up commits semantically compose CHANGELOG.md and TEST_STRATEGY.md, preserving #18 read-stall evidence while retaining the private-rustdoc quality contract.

Current exact is 9e5d897e0b7b643dc9e93986c2349edc6106f255. Fresh compare against base c78a296a87972845f8f9724e2cf2072d95a7df34 is ahead 34 / behind 0, merge-base exactly c78a296..., with the same intended 17-file effective scope: CHANGELOG.md, TEST_STRATEGY.md, and fifteen production Rust files. Rust changes remain documentation-only plus non-test #![deny(clippy::missing_docs_in_private_items)] enforcement; executable semantics are unchanged. Parent read-stall fixtures are inherited by ancestry and do not enter this lane.

The changelog keeps the compiler-enforced private-production documentation receipt: the first hosted enforcement exposed 78 private production gaps and the repair documents purpose, invariants, authority boundaries, security/privacy constraints, and performance-sensitive state. TEST_STRATEGY.md keeps the distinction between warnings-denied public rustdoc and clippy::missing_docs_in_private_items; test-only helpers remain excluded by cfg(test), and broad suppression/generated filler text is not acceptable evidence.

No predecessor GREEN transfers. Current exact must independently reacquire formatting, locked compile/test, strict Clippy including private-doc enforcement, warnings-denied rustdoc, 100% owned-production coverage, load, dual-profile OCI runtime, Supply Chain and current-range review evidence. Do not perturb runner acquisition with freshness-only commits or blind reruns.

#102/#106 remain separate semantic owners. No force push, destructive rebase, self-approval, gate weakening, protected merge, immutable release, canary/shadow, rollback, cutover or legacy-removal credit is claimed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 06942491-60b0-459f-9781-469e3cf638c4

📥 Commits

Reviewing files that changed from the base of the PR and between 38dab48 and 8970bd8.

📒 Files selected for processing (15)

• src/bin/cwl-pingora-gateway.rs
• src/bin/cwl-pingora-pg-erd-migration.rs
• src/edge_routing.rs
• src/forwarding_policy.rs
• src/gateway_proxy.rs
• src/http_policy.rs
• src/lib.rs
• src/migration_admin.rs
• src/migration_delivery.rs
• src/migration_plan.rs
• src/migration_proxy.rs
• src/observability.rs
• src/pingora_delivery.rs
• src/runtime_isolation.rs
• src/startup.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

비테스트 빌드에 비공개 항목 문서화 린트를 추가했습니다. 여러 게이트웨이, 마이그레이션, 런타임 항목에 RustDoc 주석을 추가했습니다. EdgeMigrationPlan에 response_headers 필드를 선언했습니다.

Changes

문서화 및 린트 적용

Layer / File(s)	Summary
린트 설정과 시작 지점 문서화 src/lib.rs, src/bin/*	비테스트 빌드에서 clippy::missing_docs_in_private_items를 거부하도록 설정했습니다. 게이트웨이 시작 함수와 오류 종료 함수에 문서를 추가했습니다.
게이트웨이 계약 문서화 src/edge_routing.rs, src/forwarding_policy.rs, src/gateway_proxy.rs, src/http_policy.rs, src/pingora_delivery.rs, src/startup.rs	라우팅 경로, 전달 컨텍스트, 프록시 필드, HTTP 정책, 인증서 번들, 설정 경로의 의미를 문서화했습니다. 코드 재배치와 공백 조정 외에 동작 변경은 없습니다.
마이그레이션 및 런타임 문서화 src/migration_*.rs, src/observability.rs, src/runtime_isolation.rs	마이그레이션 설정과 전달 계획, 요청 처리 헬퍼, 관찰성 항목, 런타임 격리 타입에 문서를 추가했습니다. EdgeMigrationPlan에 response_headers: ResponseHeaderPolicy 필드를 선언했습니다.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 8970b

The repair adds documentation and lint coverage without changing runtime behavior or introducing a concrete merge-blocking risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 97.14% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 35 functions across 15 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 프로덕션 코드의 비공개 Rustdoc 문서화 계약을 강제하는 이번 변경의 핵심을 정확하고 간결하게 설명합니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch quality/private-rustdoc-contract-v1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Exact-head technical review of the RED-only contract: comparison against parent 38dab48f... is ahead-only, behind 0, and exactly three production crate-root paths. The delta only enables clippy::missing_docs_in_private_items under not(test); it does not change gateway runtime behavior, test-fixture scope, product/security authority, runner selectors, or existing gates. Current CI/Supply runs are Draft-skipped, so no executed RED or GREEN is claimed. Keep Draft behind #15. After parent terminal integration, obtain the compiler RED first, then repair only the documented production items and reacquire exact-head evidence. This COMMENT is technical evidence, not self-approval.

[seonghobae]

Current-exact execution-admission review after the Ready transition. The source comparison is unchanged: exactly three production crate roots and no runtime semantic delta. Ready was used only because this repository's CI/Supply jobs are explicitly suppressed while Draft; it produced fresh exact runs CI 34898762263 and Supply 34898762330. All materialized jobs are still pre-checkout with no runner identity/steps, so the intended private-rustdoc compiler RED has not executed and no GREEN exists. Preserve exact head. If the test job produces the expected missing_docs_in_private_items RED, return the PR to Draft before causal rustdoc repair. This COMMENT supersedes the predecessor process note that said to keep Draft throughout evidence acquisition; it is technical state evidence, not approval or merge authority.

[seonghobae]

@coderabbitai review

Please review current exact 8970bd89ad9fd85b5ef846be315f5d78244c56b7, including the complete 7fdffbf78241b52bb8847c28700db864bc98df3e..8970bd89ad9fd85b5ef846be315f5d78244c56b7 repair range. This is a documentation-contract repair after hosted Clippy exposed 78 private-production rustdoc gaps; please flag any semantic drift, filler documentation, missing private production item, inaccurate invariant, or gate weakening.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

base="7fdffbf78241b52bb8847c28700db864bc98df3e"
head="8970bd89ad9fd85b5ef846be315f5d78244c56b7"

echo '== checked-out HEAD =='
git rev-parse HEAD
echo '== requested commits =='
git rev-parse "$base" "$head"
echo '== ancestry and range =='
git merge-base --is-ancestor "$base" "$head" && echo "base-is-ancestor=yes"
git rev-list --count "${base}..${head}"
git log --oneline --decorate "${base}..${head}"

echo '== diff stat =='
git diff --stat "$base" "$head"
echo '== changed paths and status =='
git diff --name-status "$base" "$head"
echo '== complete repair diff =='
git diff --no-ext-diff --unified=80 "$base" "$head"

echo '== repository config/workflow paths =='
fd -H -t f -E .git '(^Cargo\.toml$|^clippy\.toml$|^rustfmt\.toml$|\.ya?ml$)' . \
  | sort \
  | sed -n '1,240p'

echo '== crate roots and lint declarations at head =='
rg -n -C 5 --glob '*.rs' \
  'missing_docs_in_private_items|cfg_attr\s*\(\s*not\s*\(\s*test\s*\)|#!\[warn|#!\[deny|#!\[allow' \
  .

echo '== production Rust source inventory =='
fd -t f -e rs . | sort

echo '== changed Rust file outlines =='
git diff --name-only "$base" "$head" -- '*.rs' | while IFS= read -r f; do
  echo "--- $f ---"
  ast-grep outline "$f" --items all --view expanded || true
done

echo '== private production doc-candidate declarations at head =='
rg -n --glob '*.rs' \
  '^\s*(pub\s*\([^)]*\)\s+)?(struct|enum|union|trait|type|const|static|fn|mod)\b|^\s*(async\s+)?fn\b|^\s*impl\b' \
  . \
  | sed -n '1,1200p'

Length of output: 155079

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

base="7fdffbf78241b52bb8847c28700db864bc98df3e"
head="8970bd89ad9fd85b5ef846be315f5d78244c56b7"

echo '== whitespace errors =='
git diff --check "$base" "$head"

echo '== numstat and word diff =='
git diff --numstat "$base" "$head"
git diff --word-diff=porcelain "$base" "$head" -- '*.rs'

echo '== compare non-comment, non-blank Rust source =='
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
git diff --name-only "$base" "$head" -- '*.rs' | while IFS= read -r f; do
  git show "$base:$f" > "$tmpdir/base.rs"
  git show "$head:$f" > "$tmpdir/head.rs"
  python3 - "$tmpdir/base.rs" "$tmpdir/head.rs" <<'PY'
import re, sys
def normalize(path):
    text = open(path, encoding="utf-8").read()
    # Repair range only adds line rustdoc. Remove line comments and whitespace to compare code tokens.
    text = re.sub(r'(?m)^\s*//.*$', '', text)
    return ''.join(text.split())
a, b = map(normalize, sys.argv[1:])
print("same-non-line-comment-tokens=" + ("yes" if a == b else "NO"))
PY
done

echo '== all production root source =='
for f in src/lib.rs src/bin/cwl-pingora-gateway.rs src/bin/cwl-pingora-pg-erd-migration.rs; do
  echo "--- $f ---"
  cat -n "$f"
done

echo '== CI and documentation/coverage contract definitions =='
for f in .github/workflows/ci.yml .github/workflows/supply-chain.yml tests/documentation_contract.rs tests/coverage_contract.rs; do
  echo "--- $f ---"
  cat -n "$f"
done

echo '== undocumented-looking declarations in src (heuristic; excludes cfg(test) blocks) =='
python3 <<'PY'
from pathlib import Path
import re

decl = re.compile(
    r'^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?'
    r'(?:fn|struct|enum|union|trait|type|const|static|mod)\b'
)
skip_attrs = re.compile(r'^\s*#\[')
for path in sorted(Path("src").rglob("*.rs")):
    lines = path.read_text().splitlines()
    test_depth = 0
    brace_depth = 0
    pending_test_mod = False
    documented = [False] * len(lines)
    for i, line in enumerate(lines):
        if line.lstrip().startswith("///") or line.lstrip().startswith("//!"):
            documented[i] = True
    for i, line in enumerate(lines):
        # An approximate cfg(test) region filter.
        if re.match(r'^\s*#\s*\[\s*cfg\s*\(\s*test\s*\)\s*\]', line):
            pending_test_mod = True
        if pending_test_mod and re.match(r'^\s*(?:pub\s+)?mod\s+tests\b', line):
            test_depth = brace_depth + line.count("{") - line.count("}")
            pending_test_mod = False
        if test_depth and brace_depth >= test_depth:
            pass
        elif decl.match(line):
            j = i - 1
            while j >= 0 and (not lines[j].strip() or skip_attrs.match(lines[j])):
                j -= 1
            if j < 0 or not lines[j].lstrip().startswith("///"):
                print(f"{path}:{i+1}: {line.strip()}")
        brace_depth += line.count("{") - line.count("}")
        if test_depth and brace_depth < test_depth:
            test_depth = 0
PY

echo '== exact changed source with line numbers =='
git diff --name-only "$base" "$head" -- '*.rs' | while IFS= read -r f; do
  echo "--- $f ---"
  cat -n "$f"
done

Length of output: 208842

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== CanonicalIpAuthority source context =='
sed -n '235,325p' src/edge_contract.rs

echo '== process_health and runtime_policy source =='
cat -n src/process_health.rs
cat -n src/runtime_policy.rs

echo '== private declarations without immediately preceding rustdoc, excluding cfg(test) modules and trait implementation members =='
python3 <<'PY'
from pathlib import Path
import re

decl = re.compile(r'^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:fn|struct|enum|union|trait|type|const|static|mod)\b')
attribute = re.compile(r'^\s*#\[')
test_attr = re.compile(r'^\s*#\s*\[\s*cfg\s*\(\s*test\s*\)\s*\]')
for path in sorted(Path("src").rglob("*.rs")):
    lines = path.read_text().splitlines()
    test_pending = False
    test_start_depth = None
    depth = 0
    impl_depths = []
    for i, line in enumerate(lines):
        if test_attr.match(line):
            test_pending = True
        is_test = test_start_depth is not None and depth >= test_start_depth
        if not is_test and decl.match(line) and not (impl_depths and depth >= impl_depths[-1]):
            j = i - 1
            while j >= 0 and (not lines[j].strip() or attribute.match(lines[j])):
                j -= 1
            if j < 0 or not lines[j].lstrip().startswith("///"):
                print(f"{path}:{i+1}: {line.strip()}")
        opens = line.count("{")
        closes = line.count("}")
        if test_pending and re.match(r'^\s*(?:pub(?:\([^)]*\))?\s+)?mod\s+tests\b', line):
            test_start_depth = depth + opens - closes
            test_pending = False
        if re.match(r'^\s*impl\b', line):
            impl_depths.append(depth + opens - closes)
        depth += opens - closes
        while impl_depths and depth < impl_depths[-1]:
            impl_depths.pop()
        if test_start_depth is not None and depth < test_start_depth:
            test_start_depth = None
PY

echo '== exact-head GitHub PR and checks =='
gh pr view 104 --repo ContextualWisdomLab/pingora-gateway \
  --json number,state,isDraft,headRefOid,baseRefOid,statusCheckRollup,url \
  --jq '{number,state,isDraft,headRefOid,baseRefOid,url,statusCheckRollup:[.statusCheckRollup[]|{name,conclusion,status,detailsUrl,workflowName}]}'

echo '== GitHub check runs for the requested exact head =='
gh api --paginate \
  "repos/ContextualWisdomLab/pingora-gateway/commits/8970bd89ad9fd85b5ef846be315f5d78244c56b7/check-runs?per_page=100" \
  --jq '.check_runs[] | {name,status,conclusion,details_url,started_at,completed_at}'

Length of output: 15713

---

@seonghobae I found no review findings in 7fdffbf78241b52bb8847c28700db864bc98df3e..8970bd89ad9fd85b5ef846be315f5d78244c56b7.

• HEAD matches the requested exact commit 8970bd89ad9fd85b5ef846be315f5d78244c56b7.
• The base commit is an ancestor. The repair is a 13-commit fast-forward.
• All 13 changed files have identical non-comment Rust tokens before and after the repair. The only non-rustdoc edit is one blank-line deletion in src/gateway_proxy.rs.
• The added rustdoc describes concrete purpose, authority boundaries, state, limits, and fail-closed behavior. I found no filler documentation or inaccurate invariant in the reviewed additions.
• Static inspection found no missed production private item that requires rustdoc. The local CanonicalIpAuthority enum in src/edge_contract.rs is function-local and is outside the lint’s documented-item scope.
• The repair does not alter CI, Supply Chain, OCI, load, coverage, test, formatting, public rustdoc, or Clippy gate definitions.
• The exact-head checks are queued. They remain required evidence for this repaired head: test, load-contract, oci-runtime, and Supply Chain candidate-evidence.

This is a clean static review. It is not a claim that the queued exact-head gates have passed or that the stacked PR is ready to merge.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

Current-exact technical review for 42e76fca398d15c5e1ec664d0e95afa72eb92389 after integrated-parent reconciliation.

The branch is now based on integrated #15 840b03873d8e25ebd960438183884ea609b173ff, with merge-base exactly that commit and compare ahead 26 / behind 0. Effective delta is 17 files, +88/-3. Production Rust changes are documentation-only plus the non-test crate-root clippy::missing_docs_in_private_items enforcement attribute; CHANGELOG/TEST_STRATEGY changes describe that compiler contract. No forwarding/Via/TRACE/Max-Forwards/admission/runtime-isolation behavior, test/coverage denominator, dependency, runner selector, release, or authority boundary is changed.

Eleven non-overlapping historical rustdoc files were restored only where the integrated parent was byte-for-byte identical. The six historical overlap paths were semantically composed on current parent content rather than replayed wholesale, preserving #15's later source and evidence repairs. The temporary #117 merge-oracle was closed unmerged after reporting conflicts and contributes no delta or promotion credit.

There are no unresolved review threads. Fresh formatting, all-target compile/test, private-rustdoc compiler enforcement, strict Clippy, warning-denied public rustdoc, 100% owned-production line+region coverage, load/OCI, Supply Chain and exact-head review receipts must still settle on this exact head before merge. This COMMENT is technical evidence only, not approval or governance credit.

[seonghobae]

Current-exact hosted-evidence review. CI 35413287741 has real runner evidence now: OCI 105816956566 is GREEN; test 105816956614 passed exact checkout, native deps, Rust 1.98.0 formatting, full compile/test, strict Clippy and warning-denied rustdoc before entering owned-production coverage. Load-contract 105816956433 is cancelled before Rust build/k6/traffic because hosted apt package retrieval consumed the full 15-minute job budget: azure.archive.ubuntu.com stalled, archive.ubuntu.com fallback began, then the runner cancelled while still in native-dependency installation. This is runner/package-fetch runtime evidence, not a rustdoc or p95 source RED. Central owner .github#712 has the exact log specimen for a bounded reusable bootstrap repair. Leave this leaf source/ref unchanged; do not inflate the load budget, change runner selector, or no-op-push. COMMENT only; the cancelled load gate and queued Supply prevent merge credit.

[seonghobae]

Current-exact technical review after #16 reconciliation: live-base compare is ahead 27 / behind 0 with merge-base exactly bf38bc571dbb7c75e651bcaccdc66904c8c92dab; effective delta remains the same 17 private-rustdoc-owned paths and #16 runtime-isolation docs/fixture are inherited by ancestry. Production Rust changes remain documentation-only plus the non-test missing-private-docs lint. I do not find a new executable semantic or authority regression in the reconciled range. This COMMENT is review evidence only, not self-approval; fresh exact CI/Supply/load/OCI/coverage evidence is still required.

[seonghobae]

Current-exact technical review on 7d576d2ceb7d4b7f6159d0795aa638ac37cf2ac3 (COMMENT only; not approval). Integrated #119 40e10607601bf9722d642d4a4bb18f02806c20cc is now the exact merge-base with behind 0. Effective delta is again 17 files: two docs plus fifteen production Rust files, with executable semantics unchanged. Refused-origin fixture is inherited unchanged and docs preserve both parent evidence and the private-rustdoc compiler contract. No runner selector, dependency, routing/auth/business authority, Keyverse/Wardnet/EgressWeave authority, #61 baseline, or TRACEABILITY change is introduced. Prior 437a2119... in-progress checks do not transfer; current CI 35449295421 and Supply 35449295385 are queued.

[seonghobae]

Current-exact terminal evidence review on 9e5d897e0b7b643dc9e93986c2349edc6106f255: CI 35468276852 is fully GREEN across test, oci-runtime, and load-contract; formatting, compile/test, strict Clippy including missing_docs_in_private_items, warnings-denied rustdoc, owned-production 100% line/region coverage, exact dependency-lock verification, dual-profile OCI runtime, and k6 loopback all completed successfully. Supply Chain 35468276846 is also terminal SUCCESS. The PR remains ahead-only/behind 0 on integrated #18, mergeable, with no review threads; the 17-file effective delta is still documentation-only in production Rust plus the non-test private-rustdoc lint contract and does not change executable gateway semantics or authority boundaries. COMMENT only, not self-approval.