docs(proto-gtpv2c): make per-container PCO failure policy explicit

[VerifiedOrganic]

Summary

Document the per-container failure disposition for adopted PCO container
handlers as an explicit, stable contract so consumers cannot mistake
accidental use of error propagation for a protocol decision.

Changes

• Add a Per-container failure policy table to the
  decode_network_contents_correlated rustdoc, citing the basis for each
  class: configuration-atomicity (address containers), TS 24.008 §10.5.6.3
  (Link MTU ignore, unknown skip), and RFC 1661 §5.3 (IPCP unit-local
  discard).
• Add inline Failure policy: annotations at every match arm in
  decode_network_contents_correlated so the policy is visible at the
  decision point, not only in the doc comment above.
• Cross-reference the policy table from decode_network_contents.
• Pin the configuration-atomicity contract with a new test proving valid
  siblings are discarded when any address container is malformed.
• Pin the deliberate asymmetry with a contrast test: same value shape,
  IPCP malformed → siblings survive; address malformed → whole value
  rejected; Link MTU malformed → ignored.

Verification

• cargo fmt --all --check ✓
• cargo clippy --workspace --all-targets --all-features -- -D warnings ✓
• cargo test -p opc-proto-gtpv2c --all-features ✓ (56 pco tests)
• RUSTDOCFLAGS="-D warnings" cargo doc -p opc-proto-gtpv2c --no-deps ✓
• Adversarial review: spec/acceptance SHIP, boundary/security BLOCKER
  (rustdoc anchor) reproduced and fixed.

Refs #587

[VerifiedOrganic]

Current-main release-reconciliation evidence for the pushed candidate (not an independent-review certification):

Coordinates

• Frozen pre-reconciliation PR head: 62caa12cf830cc15a5bbda91a00c0057eace90cb
• Frozen pre-reconciliation PR tree: 80e1f7e4ab92f4f45e0eb29d456025a83c73f35a
• Fresh reconciled base origin/main: 9b85ae1f8a98f5fe9f9f77225f72e5364840b5b1
• Base tree: 4cb0806bd910c32a3693dfa4f3237360c0f4385e
• Pushed candidate head: 7530b8fe75fc8788f8edb6341b8f5f76eb97893d
• Candidate tree: 9f6fece610638a37cd1186e9a2c1ebf84ff2cfc2
• Merge parents, in order: 62caa12cf830cc15a5bbda91a00c0057eace90cb 9b85ae1f8a98f5fe9f9f77225f72e5364840b5b1

origin/main was merged normally with --no-ff (never rebased), without conflicts, using VerifiedOrganic <verifiedorganic@sent.com> for both author and committer and with the matching Signed-off-by. The update was pushed normally to fix/587-pco-failure-policy without force. The current-main PR delta remains exactly two files, 127 insertions and 29 deletions:

• crates/opc-proto-gtpv2c/src/pco.rs
• crates/opc-proto-gtpv2c/tests/pco.rs

Scope/policy audit

• Preserved whole-value rejection for corrupt outer framing and wrong fixed lengths for P-CSCF/DNS container IDs 0x0001, 0x0003, 0x000c, and 0x000d.
• Preserved unit-local ignore/discard with sibling survival for malformed MTU 0x0010 and IPCP 0x8021, including extra IPCP parameters.
• Preserved skip behavior for unknown well-framed containers.
• The reconciliation introduced no new runtime semantic fix and no unrelated protocol cleanup; the PR remains documentation/test compatibility coverage over the adopted runtime behavior. Therefore a new semantic-fix RED/fix-removal/adversarial-mutation triplet was not triggered.

Local verification

• opc-heavy cargo test --locked -p opc-proto-gtpv2c --all-features --test pco — 56 passed, 0 failed.
• opc-heavy env 'RUSTDOCFLAGS=-D warnings' cargo doc --locked -p opc-proto-gtpv2c --no-deps --all-features — passed.
• python3 scripts/check-management-plane-policy.py --self-test and --check — passed.
• python3 crates/opc-proto-diameter/fuzz/generate_corpus.py --self-test — passed.
• python3 ci/test-shards.py verify — passed: 6 shards / 7 lanes, total and disjoint over 266 integration targets.
• cargo fmt --all --check and git diff --check — passed.
• opc-heavy cargo clippy --locked -p opc-persist --all-targets --no-default-features -- -D warnings — passed.
• opc-heavy cargo test --locked -p opc-persist --no-run — passed.
• opc-heavy cargo test --locked -p opc-persist --test break_glass_tests --test security_policy_tests --test security_policy_stress_tests --test security_policy_empirical_tests -- --test-threads=1 — 38 passed, 0 failed.
• opc-heavy cargo clippy --workspace --all-targets --all-features -- -D warnings — passed.
• opc-heavy cargo test --workspace --all-features --quiet -- --test-threads=4 — complete rerun passed. In particular, the 46-case mTLS multiprocess target was 44 passed / 2 repository-declared ignored / 0 failed in 914.21s, and the five-case qualification target was 5 passed / 0 failed in 75.13s.
• Under the same successful opc-heavy ownership: /usr/local/go/bin/go vet ./..., /usr/local/go/bin/go test ./... using Go 1.26.6, and kubectl kustomize operators/sdk-reference-operator/config/default — passed.

Transient diagnosis disclosed: the first complete workspace-test attempt had one LeaderFailoverReadiness 30-second deadline in real_three_and_five_process_openraft_sqlite_stop_restart_foundation (node 0, empty stderr), outside this two-file PCO delta. The corrected exact focused command with --all-features --exact --nocapture --test-threads=1 passed 1/1 in 52.45s, and the subsequently repeated complete workspace gate passed the same case as part of its 5/5 target. No code was changed for that transient.

Hosted workflows have materialized for exact head 7530b8fe75fc8788f8edb6341b8f5f76eb97893d and are being polled to terminal. Final disposition remains reserved for a fresh independent exact-head adversarial review; this comment does not self-certify it.

[VerifiedOrganic]

Final hosted-check reconciliation for exact candidate head 7530b8fe75fc8788f8edb6341b8f5f76eb97893d / tree 9f6fece610638a37cd1186e9a2c1ebf84ff2cfc2:

• CI run 31929221850: success
• Fuzz run 31929221843: success
• Security run 31929221833: success
• GTP-U privileged run 31929221842: success
• Exact-head check-run aggregate: 44 terminal; 43 success, 1 expected Scheduled fuzz skip, 0 adverse conclusions.

A final prune-fetch confirms origin/main is still the reconciled base 9b85ae1f8a98f5fe9f9f77225f72e5364840b5b1 / tree 4cb0806bd910c32a3693dfa4f3237360c0f4385e. The remote PR branch and local candidate still match exactly at the head/tree above. PR #618 remains open, ready/non-draft, CLEAN, and MERGEABLE. No merge or ready-state mutation was performed.

Next action remains a fresh independent exact-head adversarial review of this bounded adopted-PCO malformed-container policy/documentation-runtime boundary. This is a request for independent review, not self-certification and not authorization to merge.