fix(errors): 403 auth rejections no longer read as policy blocks

[saurabhjain1592]

Release-blocking library fix from the getaxonflow/axonflow-enterprise#2861 release-readiness gate.

Bug

Every agent error envelope carries a literal "blocked" JSON key - a tenant-mismatch rejection is:

{"success":false,"error":"Tenant mismatch","blocked":false}   // HTTP 403

so handleErrorResponse's substring heuristic

case 403:
  if (body.contains("policy") || body.contains("blocked")) {
    throw new PolicyViolationException(errorMessage);
  }

classified every 403 authorization rejection as PolicyViolationException. Callers following the documented pattern (policy block = expected, non-fatal outcome) silently swallowed real auth failures with exit 0 - exactly how examples/basic passed the smoke with a wrong client-id/user-token tenant pairing.

Fix

The 403 branch parses the JSON body (Jackson, already in use) and treats a present blocked boolean as authoritative:

• "blocked":true -> PolicyViolationException
• "blocked":false -> AuthenticationException (HTTP 403)
• unparseable body, or no blocked boolean -> legacy policy-phrase fallback (policy / block_reason; the bare blocked substring no longer counts)

Audited the rest of the method: this was the only substring-classification site - 401 always maps to AuthenticationException; 402/409/429/408/504 key on status code alone.

Tests

• Unit (WireMock): exact live tenant-mismatch envelope -> AuthenticationException with message intact; blocked:true envelope -> PolicyViolationException; unparseable-body fallback in both directions.
• New live-stack leg runtime-e2e/error_classification_403/ (no skip hatch) asserting both directions through proxyLLMCall.

Live runtime-e2e evidence (enterprise stack, platform v9.6.1, agent :8080, original pre-rebase round)

Against this fix:

PASS [tenant-mismatch-403] AuthenticationException: Tenant mismatch
PASS [policy-block-403] PolicyViolationException: Request blocked by policy: Detects stacked DROP TABLE/DATABASE statement
RESULT: PASS (2/2)
EXIT=0

Same leg against the released 8.5.1 jar (proves the bug + the leg's sensitivity):

FAIL: REGRESSION: tenant-mismatch 403 classified as PolicyViolationException (Request blocked by policy: Tenant mismatch) - the "blocked":false envelope must map to AuthenticationException
EXIT=1

Rebase note (2026-08-03, backlog clearance)

Rebased onto main after the 9.0.0 release, #203 (jackson 2.22.1) and #196 (example pins to published 9.0.0). The original 8.5.2 release prep no longer applies and was dropped in the rebase:

• pom.xml stays at main's 9.0.0 - versioning belongs to the next release cut (published 9.0.0 does NOT contain this fix; per the semver policy the operator decides the next version, noting this changes the exception type thrown for 403 auth rejections).
• Example pom pins stay at fix(examples): pin poms to published 9.0.0; fail loud on tenant mismatch [skip-runtime-e2e] #196's published 9.0.0 (they pin published artifacts; pinning an unpublished version would break mvn package for users).
• The CHANGELOG entry now sits under [Unreleased] ### Fixed instead of a [8.5.2] heading.

The library fix, unit tests and runtime-e2e leg are unchanged from the reviewed diff.

Refs getaxonflow/axonflow-enterprise#2861.

[saurabhjain1592]

Backlog-clearance verification (rebased head 0ef9a25):

Rebase onto current main (post 9.0.0 release, #203 jackson 2.22.1, #196 example pins to published 9.0.0). Conflict resolution dropped the stale 8.5.2 release prep: pom.xml stays at main's 9.0.0, example pins stay at #196's published 9.0.0, and the CHANGELOG entry moved under [Unreleased] ### Fixed. The library fix, unit tests and runtime-e2e/error_classification_403/ leg are unchanged from the reviewed diff.

The fix still binds - both discriminating directions run locally on the rebased head (JDK 17):

• shouldHandle403BlockedFalseAsAuthRejection: exact live tenant-mismatch envelope {"success":false,"error":"Tenant mismatch","blocked":false} -> AuthenticationException, not PolicyViolationException. PASS.
• shouldHandle403BlockedTrueAsPolicyViolation: {"success":false,"blocked":true,"block_reason":"Detects stacked DROP TABLE/DATABASE statement"} -> PolicyViolationException. PASS.
• Plus both unparseable-body fallback tests and the pre-existing shouldHandle403PolicyViolation: 5/5 PASS.

Mutation proof: with the fix hunk reverted to the old substring heuristic (if (body.contains("policy") || body.contains("blocked"))), the mutant compiled and the suite ran: shouldHandle403BlockedFalseAsAuthRejection FAILED (misclassified as PolicyViolationException) while shouldHandle403BlockedTrueAsPolicyViolation still passed - the test pins exactly the auth-rejection direction. Fix restored, 5/5 green again, and the full AxonFlowTest class (171 tests) plus the whole suite (1325 tests, 0 failures) pass on the rebased head.

CI: all 17 checks green on 0ef9a25, including Contract Integration (WireMock), real-stack ubuntu/macos/windows, Validate Wire Shape, Validate Version Alignment, CodeQL and DCO: https://github.com/getaxonflow/axonflow-sdk-java/actions/runs/30837069806 https://github.com/getaxonflow/axonflow-sdk-java/actions/runs/30837069865

Note for the next release cut: published 9.0.0 does NOT contain this fix, and the fix changes the exception type thrown for 403 auth rejections (PolicyViolationException -> AuthenticationException), which per the semver policy is the operator's versioning call.

Merging per backlog-clearance brief.