[texastony]

Issue #, if available:

Description of changes:

Implements the Cache Guard and Negative Cache Entries from examples/src/multi_tenant/negative_caching.md (#3), mainly Design Questions 4.3 and 5. CI passes.

This PR was opened with the interface stubbed (NotImplementedError), so the tests could be reviewed before the implementation. It now contains the implementation, squashed into one commit.

examples/src/multi_tenant/negative_cache.py (no MPL import; the Tenant KMS Client will record Denials through it)

• DENIAL_ERROR_CODES: the eight codes from Design Question 5. is_denial(error) is true only for a botocore ClientError with one of them. error_code(error) returns the code.
• BranchKeyNegativeCache(branch_key_id, negative_ttl=300, clock=time.monotonic): the Negative Cache Entry, if any, of one Branch Key ID, with record, get, and clear.
  • One lock is held across checking expiry and discarding, so get() never erases a Denial recorded concurrently.
  • It rejects an empty Branch Key ID and a non-positive or NaN Negative TTL.
• record() logs one warning: "AWS KMS Denied Branch Key ID … (code); failing its requests for N seconds: …", with the error's full text.

examples/src/multi_tenant/cache_guard.py

• CacheGuard(delegate, negative_cache), an ICryptographicMaterialsCache. While Denied, it raises OpaqueWithTextError(obj=error, obj_message=str(error)) before consulting the shared cache; otherwise it delegates.
• Why OpaqueWithTextError. All eight Denial codes were compared through a real Hierarchical Keyring:
  • It keeps the original error, the same object, and its code, for 8 of 8 codes.
  • A ComAmazonawsKms error keeps neither for the four KMS errors the MPL models (Disabled, KMSInvalidState, NotFound, IncorrectKey).
  • Raising the error itself left an empty str().
  • A new wrapper per raise also stops the error's traceback growing on every raise, which was measured as 2 frames per raise.
• The outermost str() never names the code. The MPL generates OpaqueWithTextError with an empty message, so the warning log is where an operator sees the code.
• The first Denial carries less. A real cache miss, confirmed against DynamoDB Local, loses the code of the four modeled KMS errors entirely, and never keeps the original error.

Tests (pytest.mark.local; 103 offline tests pass in CI)

• Denial classification, expiry, replacement, logging, and validation (including NaN).
• A deterministic expiry race test: a clock hook runs record() on a second thread inside get()'s discard window. An unlocked implementation fails it.
• Thread safety stress tests, including the guard's final state.
• The guard's delegation, and its refusal of a cached hit while Denied.
• End to end, a real Hierarchical Keyring on the Cache Guard, seeded with the specification's cache identifiers. While Denied, encrypt and decrypt fail with zero DynamoDB and KMS calls, and the original error is reachable (on decrypt, within the ESDK's error). Clearing the Denial restores both.

Not yet: the Tenant KMS Client does not record Denials yet, and the Tenant Keyring Factory does not exist yet; the tests call record() themselves.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Check any applicable:

• Were any files moved? Moving files changes their URL, which breaks all hyperlinks to the files.

🤖 Generated with Claude Code

[texastony]

I think I approve... squash and merge with a reasonable commit message.