security: require exact pool-count scalar types

[seonghobae]

Purpose

Reconstruct the exact connection-count scalar boundary on the current method, timeout-policy, and connection-pool-policy stack without transferring historical acceptance evidence.

This PR is intentionally stacked on #221. Its unique delta is limited to the connection-count normalizer plus focused tests and security/migration documentation after the exact policy-object boundaries are established.

Exact stack identity

• protected main ancestor: 7faf7a3b8a47980113982914000e724ab6a6cda5;
• security: reconstruct exact HTTP method strings on protected main #204 method-policy predecessor: ab51ef1725bd20c898a3e3df82994b576e675e7b;
• security: reject timeout-policy subclasses on the current policy stack #220 timeout-policy predecessor: b0e9b43d4b3c8701e8b6af7a93f1e82a0e9030c7;
• exact PR base / security: reject connection-pool policy subclasses on the current policy stack #221 connection-pool-policy predecessor: f97084256922f7085b94096f6c20e4a613fac738;
• integer-subclass RED: 753c8bb38bbdb8952bf95baf2f8e9410b7e8934f;
• integer-boundary GREEN: 21d61428791b6f7a807a3ec412156b598bbcfbbe;
• string-subclass test-only RED: 8bac04eb7d2b65e5d05f662ec937fc7b1492ed3c;
• string-boundary GREEN: dbce33d31d9bf5839214341e129f1d1347caa9df;
• exact current documented head: 9836caa81b3b49d2e6a965830cf9a96242b0a097;
• stale historical security: reconstruct exact connection-count values on current pool-policy stack #187 head: dd8bc0e044fac96d355f3c46b57b4fc3f12bb1ae.

Test-first repairs

Integer subclasses

The first immutable RED required both max_connections and max_keepalive_connections to reject int subclasses while retaining exact integers and reviewed ASCII decimal strings. Hosted CI reproduced those failures before the production boundary changed to exact built-in int handling.

String subclasses

A later audit found that the same normalizer still accepted arbitrary str subclasses through isinstance(value, str) and could dispatch subclass-controlled isascii() / isdecimal() before trusted count state was frozen. Test-only head 8bac04e... requires both count fields to reject a hostile str subclass with a stable field-specific TypeError before polymorphic string inspection. Production head dbce33d... closes that boundary by allowing the decimal-string path only for exact built-in str values.

The final documentation/tests align the public migration guidance with that exact-scalar contract.

Preserved behavior

The current tree preserves:

• exact built-in integer count values;
• exact built-in ASCII decimal strings used by environment-style configuration;
• positivity and zero allowances already defined by each field;
• total-vs-keepalive relational validation;
• normalized built-in integer outputs;
• existing public policy signatures and finite connection-pool resource limits; and
• the preceding exact method, timeout-policy, and connection-pool-policy object boundaries.

It adds no network, credential, release, reviewer, repository-write, or bypass authority.

Exact-current-head evidence

On unchanged 9836caa81b3b49d2e6a965830cf9a96242b0a097:

• repository CI run 31878987348: terminal success;
• package wheel/sdist build, archive verification, checksums and installed-wheel smoke: success;
• Python 3.10, 3.11, 3.12, 3.13 and 3.14 jobs: success;
• each Python lane completed exact checkout verification, hash-locked CI dependency install, Ruff, full pytest coverage execution/reporting, product-guard self-test and compileall successfully;
• formal reviews: none at the latest exact-head refetch;
• unresolved review threads: none at the latest exact-head refetch.

Because this is a stacked non-default-base Draft, full default-branch SAST/Security/Dependency Review/Strix and protected-merge evidence are not inferred from the native CI result and predecessor evidence does not transfer.

Merge contract

Keep Draft behind #221, #220 and #204. Do not merge until every predecessor is integrated on an accepted protected tree; this unique delta is retargeted/reconstructed on the resulting exact protected base without transferring historical checks/reviews; every then-live CI/SAST/Dependency Review/Strix and organization-required workflow is substantively terminal-success; every current valid finding is addressed; qualifying independent approvals satisfy live policy; and exact head/base/ancestry/rulesets are revalidated immediately before normal protected integration.

Progresses #120. Supersedes #187 after the successor stack is safely integrated.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: db888bfe-8c5c-4124-abea-cda970c000a7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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]

@coderabbitai review

Please review exact head 89d9012af9a6bda7fc13169173f6476459bccc24, including hosted RED run 31784721661, the minimal exact-int GREEN change, migration documentation, and exact-head 100% production statement/branch coverage.

[coderabbitai]

Rate Limit Exceeded

@seonghobae have exceeded the limit for the number of chat messages per hour. Please wait 49 minutes and 3 seconds before sending another message.

[seonghobae]

@opencode-agent

Please perform a fresh exact-head semantic review of 89d9012af9a6bda7fc13169173f6476459bccc24. Validate the RED→GREEN lineage, exact built-in integer boundary, retained decimal-string compatibility, migration guidance, and stacked-base merge contract. Submit a formal current-head verdict.

[seonghobae]

@cwl-noema-review

Please independently review exact head 89d9012af9a6bda7fc13169173f6476459bccc24 after a qualifying current-head OpenCode verdict. Confirm the exact-int restriction is proportionate, documented, and preserves the supported exact-integer and ASCII-decimal configuration paths.