feat(sensitive): settle failed handle-use reservations

[seonghobae]

Partial implementation of #10, stacked on PR #55.

Buyer/security gap

The active sensitive-handle stack can reserve an authoritative use before protected-value resolution, but a reservation must be compensatable only when the trusted broker proves that disclosure failed before any protected value left the broker boundary. A blind counter decrement would be unsafe because concurrent callers could compensate the wrong reservation, replay stale compensation against a later use, or try to settle a reservation against a different state instance with identical policy scope.

Dependency

This Draft is stacked on unchanged exact PR #55 head 8d3ccf0a3b99fd9789210dd9798b422431fab7d8 and must remain Draft while #55/#53/#46 are active.

TDD / RCA sequence

Test-only exact head 63798d38a35fa14e9b7f899f638eb8fdcf077d46 established the missing tracked-reservation contract. The first production implementation used a monotonically increasing u64 reservation sequence plus a synthetic None exhaustion state. Exact predecessor head add3599bee784c58dfaa4275d17c477eaed781a9 passed repository contracts, formatting, workspace tests, strict Clippy and rustdoc but failed exact coverage at branches=495/496, lines=3666/3667, regions=4575/4576.

The uncovered production branch was the private next_reservation_sequence == None path. Normal public use could exercise only the opposite branch; a private unit test could manufacture exhaustion, but LLVM instrumented that unit-test copy separately from the integration-test production copy. Keeping a synthetic unreachable production state merely to satisfy coverage would preserve the wrong design.

The root-cause repair therefore removed the finite caller-independent sequence space. Reservations now use allocation-bound, non-copyable in-process identities. The state retains one strong reference while a reservation is outstanding and the returned token retains another. A surviving stale token therefore keeps its original allocation live, so a later reservation cannot alias it after compensation; if the stale token is dropped, it cannot be replayed. No caller-controlled identifier or serializable sequence is introduced.

Exact head 17bc00790e75424afd97c8a73800d9b16c766300 then passed CI run 31451682170. Current exact head aa46d982b2bf786fe297744ac99f88b6c4c5f4cf additionally proves a reservation token from one SensitiveHandleUseState cannot commit or compensate another state instance even when both carry the same policy scope.

Exact-head evidence

On unchanged exact head aa46d982b2bf786fe297744ac99f88b6c4c5f4cf against unchanged prerequisite #55 head 8d3ccf0a3b99fd9789210dd9798b422431fab7d8:

• CI run 31451963178: success;
• repository Python contracts: success;
• canonical Rust formatting: success;
• locked workspace/all-target check: success;
• full workspace tests: success;
• strict Clippy: success;
• rustdoc/API documentation: success;
• exact owned production function/line/region/branch coverage: success;
• CodeRabbit exact-head status: success; and
• GitHub reports the Draft mergeable against its exact prerequisite base.

No predecessor-head result is transferred to the current head.

Implemented contract

• one allocation-bound reservation identity per authorized tracked use;
• exact compensation of an undisclosed reservation restores one unit of capacity;
• a stale compensated reservation cannot affect a later reservation;
• a token cannot settle a different state instance;
• a committed reservation remains consumed and becomes non-compensatable;
• multiple outstanding reservations settle independently by identity;
• denied/revoked attempts create no reservation; and
• revocation does not prevent cleanup compensation of a reservation known not to have disclosed a value.

Truth boundary

This lane does not resolve protected values, prove whether disclosure occurred, derive authenticated workload identity, provide cross-process/database transactionality, persist handle state, perform KMS/encryption, or create a complete trusted broker. Allocation identity is intentionally an in-process primitive, not a durable broker token. The future trusted broker must supply the authoritative fact that compensation is valid only before disclosure and place reserve/recheck/disclose/settle inside its own transactional or locking boundary.

[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: c15f3d72-a900-46f7-99a7-688dc294103b

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.}