Skip to content

feat(policies): deprecate the v11 policy simulation methods - #244

Merged
saurabhjain1592 merged 1 commit into
mainfrom
w3q/java-deprecations
Sep 13, 2026
Merged

saurabhjain1592 merged 1 commit into
mainfrom
w3q/java-deprecations

Conversation

@saurabhjain1592

Copy link
Copy Markdown
Member

Summary

A v11.0.0 platform deprecates POST /api/v1/policies/simulate, /impact-report and /conflicts and removes them in v11.1 (policypath.RemovalRelease, PRD v11 §1.11). Every response from them carries X-AxonFlow-Removed-In: v11.1 and a successor Link naming /api/v1/typed-policies, plus an RFC 9745 Deprecation header once v11.0.0 is tagged. This marks the eight methods that reach those routes @Deprecated with Javadoc saying so, documents the retired per-policy override writes, and proves both against a live stack. It mirrors getaxonflow/axonflow-sdk-go#233 (87042cb3d).

Part of getaxonflow/axonflow-enterprise#3746.

What changes

  • @Deprecated, with a Javadoc @deprecated naming the removal release (v11.1), the successor (/api/v1/typed-policies) and the Deprecation header's arrival at the tag, on all eight methods that reach the three routes: simulatePolicies and simulatePoliciesAsync; getPolicyImpactReport and getPolicyImpactReportAsync; detectPolicyConflicts() and detectPolicyConflicts(String), and both Async forms. Plain @Deprecated, with no since (an SDK version is the release's to name) and no forRemoval (the removal is the platform's; the SDK's own removal is not decided). They keep working until v11.1.
  • createPolicyOverride and deletePolicyOverride document, without being deprecated, that a v11.0.0 platform retires per-policy overrides and refuses both with 409 LEGACY_POLICY_WRITE_FROZEN, thrown as D1's LegacyPolicyWriteFrozenException. The Javadoc quotes the refusal a v11.0.0 platform sends, as measured on the stack below (agent-api's PerPolicyOverrideRetired response):
{"error":{"code":"LEGACY_POLICY_WRITE_FROZEN","message":"Per-policy overrides of system controls are retired in v11: a system control is enabled, disabled or re-actioned in the organization's typed document, in its system_controls section, through the typed authoring route at /api/v1/typed-policies. Session break-glass overrides (ADR-044) are unaffected, and reads on this endpoint are unaffected."}}
  • No wire change and no second report path: D1's hook (AxonFlow.noteRouteDeprecation, called from executeHttp; the record is shared with derived clients) already reports each route once per client family. The wire-shape baseline is unchanged (the diff of tests/fixtures/wire-shape-baseline.json against main is empty, and the validator passes).
  • CHANGELOG ### Deprecated with no version number; a README "v11.0.0 deprecations" section.

The Deprecation header, today and at the tag

policypath.DeprecatedSince is a hand-edited constant that stays empty until v11.0.0 is tagged (platform/shared/policypath/policypath.go:254, guarded by policypath_test.go:383), so today the platform sends only X-AxonFlow-Removed-In: v11.1 and the successor Link. Go #233's live run read exactly that at enterprise 857455033; this PR's run reads it again below. The unit test pins today's shape (no Deprecation, reported null); the leg accepts Deprecation absent or @<unix seconds>, so it passes today and at the tag.

Field-level verification

Field / state Test
X-AxonFlow-Removed-In: v11.1 present on each of the three routes theSimulationMethodsWorkAndEachRouteIsReportedOnce (mocked at 857455033's shape); leg step 2 (live)
successor Link present, exactly /api/v1/typed-policies the same unit test; leg step 2 asserts the exact target string
Deprecation absent (today) the unit test reports it null; leg step 2 accepts absent
Deprecation present as @<unix seconds> (from the tag) leg step 2 accepts ^@[0-9]+$; D1's routeDeprecationIsReportedOncePerRoute reports a present value
a route reported once per client: second call, async forms, a derived asUser client the unit test (9 conflicts calls, 5 each of the others, 3 reports); leg step 3 (live)
impact-report refused (non-2xx, never pinned to 500) and still reported leg steps 1 and 2
@Deprecated on all eight methods, plainly (no since, no forRemoval), none on the override writes everyMethodReachingTheSimulationRoutesIsDeprecated (a census over every public method by name)
override create/delete: 409 LEGACY_POLICY_WRITE_FROZEN as LegacyPolicyWriteFrozenException, message naming the typed route, not retried theRetiredOverrideWritesThrowTheFrozenException; leg step 4 (live)
a wrong secret: the SDK's AuthenticationException (401) leg step 5 (live)

Mutants

14/14 killed, each by a named test that compiles and fails (a mutant that does not compile would be INVALID; none was). Each mutant is one textual change; the targeted suite runs; the file is restored from its saved bytes.

# Mutation Verdict Killed by
1 public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesReque -> public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesReque KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
2 public CompletableFuture<SimulatePoliciesResponse> simulatePoliciesAsy -> public CompletableFuture<SimulatePoliciesResponse> simulatePoliciesAsy KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
3 public ImpactReportResponse getPolicyImpactReport(ImpactReportRequest -> public ImpactReportResponse getPolicyImpactReport(ImpactReportRequest KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
4 public CompletableFuture<ImpactReportResponse> getPolicyImpactReportAs -> public CompletableFuture<ImpactReportResponse> getPolicyImpactReportAs KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
5 public PolicyConflictResponse detectPolicyConflicts() { -> public PolicyConflictResponse detectPolicyConflicts() { KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
6 public PolicyConflictResponse detectPolicyConflicts(String policyId) { -> public PolicyConflictResponse detectPolicyConflicts(String policyId) { KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
7 public CompletableFuture<PolicyConflictResponse> detectPolicyConflicts -> public CompletableFuture<PolicyConflictResponse> detectPolicyConflicts KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
8 public CompletableFuture<PolicyConflictResponse> detectPolicyConflicts -> public CompletableFuture<PolicyConflictResponse> detectPolicyConflicts KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
9 public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesReque -> public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesReque KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
10 public PolicyConflictResponse detectPolicyConflicts(String policyId) { -> public PolicyConflictResponse detectPolicyConflicts(String policyId) { KILLED everyMethodReachingTheSimulationRoutesIsDeprecated
11 (template != null ? template.path : request.url().encodedPath()) -> request.url().encodedPath() KILLED aStampedRouteWithAnIdIsReportedOnceNotOncePerId, everyIdBearingMethodReportsItsTemplateOnce
12 return request.newBuilder().tag(RouteTemplate.class, new RouteTemplate -> return request; KILLED aStampedRouteWithAnIdIsReportedOnceNotOncePerId, everyIdBearingMethodReportsItsTemplateOnce
13 "/api/v1/static-policies/{id}/versions" -> "/api/v1/static-policies/{id}" KILLED everyIdBearingMethodReportsItsTemplateOnce
14 "/api/v1/static-policies/{id}") -> buildPatchRequest("/api/v1/static-policies/" + policyId, body) KILLED everyConcatenatedStampedPathCarriesItsTemplate, everyIdBearingMethodReportsItsTemplateOnce

Live stack

Production posture (Enterprise licence, application database role), enterprise 6edf47aaf115f9eb2e07b6478305acbcdb8d24fb, the leg run at SDK ccc545139.

axonflow-agent sha256:9e0b2346eb912db49409334d93aa677c9f1368aa9dde39ca623418d5bcadc1c3
axonflow-orchestrator sha256:a1541250d789aa1307eb56ac2cce1a899adcfbea6f973bbad9daacf3be60e737

Raw responses (curl, the leg's credentials):

simulate: HTTP/1.1 200 OK
  Link: </api/v1/typed-policies>; rel="successor-version"
  X-Axonflow-Removed-In: v11.1
  body: {"allowed":true,"applied_policies":[],"risk_score":0,"required_actions":[],"processing_time_ms":0,"total_policies":15,"dry_run":true,"simulated_at":"2026-09-13T15:48:51.978443635Z","tier":"Enterprise","segments_resolved":false}
conflicts: HTTP/1.1 200 OK
  Link: </api/v1/typed-policies>; rel="successor-version"
  X-Axonflow-Removed-In: v11.1
  body: {"conflicts":null,"total_policies":15,"conflict_count":0,"checked_at":"2026-09-13T15:48:51.99814076Z","tier":"Enterprise"}
impact: HTTP/1.1 500 Internal Server Error
  Link: </api/v1/typed-policies>; rel="successor-version"
  X-Axonflow-Removed-In: v11.1
  body: {"code":"INTERNAL_ERROR","error":"INTERNAL_ERROR","message":"Failed to evaluate input 0"}
override-create: HTTP/1.1 409 Conflict
  Link: </api/v1/typed-policies>; rel="successor-version"
  X-Axonflow-Removed-In: v11.1
  body: {"error":{"code":"LEGACY_POLICY_WRITE_FROZEN","message":"Per-policy overrides of system controls are retired in v11: a system control is enabled, disabled or re-actioned in the organization's typed document, in its system_controls section, through the typed authoring route at /api/v1/typed-policies. Session break-glass overrides (ADR-044) are unaffected, and reads on this endpoint are unaffected."
override-delete: HTTP/1.1 409 Conflict
  Link: </api/v1/typed-policies>; rel="successor-version"
  X-Axonflow-Removed-In: v11.1
  body: {"error":{"code":"LEGACY_POLICY_WRITE_FROZEN","message":"Per-policy overrides of system controls are retired in v11: a system control is enabled, disabled or re-actioned in the organization's typed document, in its system_controls section, through the typed authoring route at /api/v1/typed-policies. Session break-glass overrides (ADR-044) are unaffected, and reads on this endpoint are unaffected."

The leg (runtime-e2e/v11_deprecations/run.sh), verbatim:

agent: http://localhost:8080
17:49:01.606 [main] INFO com.getaxonflow.sdk.AxonFlow -- AxonFlow client initialized for http://localhost:8080
PASS: simulatePolicies() returned (allowed=true, 15 policies evaluated)
PASS: detectPolicyConflicts() returned (0 conflicts in 15 policies)
17:49:01.690 [main] WARN com.getaxonflow.sdk.util.RetryExecutor -- Attempt 1/3 failed for getPolicyImpactReport, retrying in 1000ms: INTERNAL_ERROR
17:49:02.709 [main] WARN com.getaxonflow.sdk.util.RetryExecutor -- Attempt 2/3 failed for getPolicyImpactReport, retrying in 2000ms: INTERNAL_ERROR
17:49:04.728 [main] ERROR com.getaxonflow.sdk.util.RetryExecutor -- All 3 attempts failed for getPolicyImpactReport
PASS: getPolicyImpactReport() is refused with a non-2xx on a fresh v11 organization (500)
PASS: POST /api/v1/policies/simulate is reported exactly once (1)
  reported: POST /api/v1/policies/simulate is deprecated by the AxonFlow platform; use /api/v1/typed-policies instead; it is removed in v11.1.
PASS: POST /api/v1/policies/simulate: the successor is exactly /api/v1/typed-policies (/api/v1/typed-policies)
PASS: POST /api/v1/policies/simulate: removed in v11.1 (v11.1)
PASS: POST /api/v1/policies/simulate: Deprecation absent or @<unix seconds> (null)
PASS: POST /api/v1/policies/conflicts is reported exactly once (1)
  reported: POST /api/v1/policies/conflicts is deprecated by the AxonFlow platform; use /api/v1/typed-policies instead; it is removed in v11.1.
PASS: POST /api/v1/policies/conflicts: the successor is exactly /api/v1/typed-policies (/api/v1/typed-policies)
PASS: POST /api/v1/policies/conflicts: removed in v11.1 (v11.1)
PASS: POST /api/v1/policies/conflicts: Deprecation absent or @<unix seconds> (null)
PASS: POST /api/v1/policies/impact-report is reported exactly once (1)
  reported: POST /api/v1/policies/impact-report is deprecated by the AxonFlow platform; use /api/v1/typed-policies instead; it is removed in v11.1.
PASS: POST /api/v1/policies/impact-report: the successor is exactly /api/v1/typed-policies (/api/v1/typed-policies)
PASS: POST /api/v1/policies/impact-report: removed in v11.1 (v11.1)
PASS: POST /api/v1/policies/impact-report: Deprecation absent or @<unix seconds> (null)
PASS: nothing else is reported (3)
17:49:04.747 [main] WARN com.getaxonflow.sdk.util.RetryExecutor -- Attempt 1/3 failed for getPolicyImpactReport, retrying in 1000ms: INTERNAL_ERROR
17:49:05.768 [main] WARN com.getaxonflow.sdk.util.RetryExecutor -- Attempt 2/3 failed for getPolicyImpactReport, retrying in 2000ms: INTERNAL_ERROR
17:49:07.780 [main] ERROR com.getaxonflow.sdk.util.RetryExecutor -- All 3 attempts failed for getPolicyImpactReport
17:49:07.796 [main] WARN com.getaxonflow.sdk.util.RetryExecutor -- Attempt 1/3 failed for getPolicyImpactReport, retrying in 1000ms: INTERNAL_ERROR
17:49:08.806 [main] WARN com.getaxonflow.sdk.util.RetryExecutor -- Attempt 2/3 failed for getPolicyImpactReport, retrying in 2000ms: INTERNAL_ERROR
17:49:10.820 [main] ERROR com.getaxonflow.sdk.util.RetryExecutor -- All 3 attempts failed for getPolicyImpactReport
PASS: a second call of each, and a client derived with asUser, report nothing new (0 new)
  platform message: Per-policy overrides of system controls are retired in v11: a system control is enabled, disabled or re-actioned in the organization's typed document, in its system_controls section, through the typed authoring route at /api/v1/typed-policies. Session break-glass overrides (ADR-044) are unaffected, and reads on this endpoint are unaffected.
PASS: createPolicyOverride throws LegacyPolicyWriteFrozenException (409, LEGACY_POLICY_WRITE_FROZEN) naming /api/v1/typed-policies
  platform message: Per-policy overrides of system controls are retired in v11: a system control is enabled, disabled or re-actioned in the organization's typed document, in its system_controls section, through the typed authoring route at /api/v1/typed-policies. Session break-glass overrides (ADR-044) are unaffected, and reads on this endpoint are unaffected.
PASS: deletePolicyOverride throws LegacyPolicyWriteFrozenException (409, LEGACY_POLICY_WRITE_FROZEN) naming /api/v1/typed-policies
PASS: listStaticPolicies() returned policies to read by id (20)
PASS: two static policies read by id are reported once, as GET /api/v1/static-policies/{id} (1)
PASS: no report names a concrete id
17:49:10.871 [main] INFO com.getaxonflow.sdk.AxonFlow -- AxonFlow client initialized for http://localhost:8080
PASS: a wrong secret is refused with AuthenticationException 401

PASS: v11_deprecations

Teardown:

containers by label: 0
volumes by label: 0
axonflow-* containers: 0
env file present: no; generated .env present: no (a prior .env: no)

The stack ran at ccc545139; this head c0f56a6b5 differs from it only in comments (master's ruling). The one change is the measured refusal body quoted in createPolicyOverride's Javadoc. The runtime leg and every test are byte-identical. git diff --stat ccc545139 c0f56a6b5:

src/main/java/com/getaxonflow/sdk/AxonFlow.java | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

A script over every diff hunk:

diff ccc545139..c0f56a6b5: 1 file(s): src/main/java/com/getaxonflow/sdk/AxonFlow.java
2 hunk(s), 10 changed line(s) checked against ^\s*(\*|/\*\*|/\*|\*/|//)
VERDICT: comment lines only

Local round

Every pull_request workflow's steps, run locally at c0f56a6b5, plus DCO and new-code coverage. ALL GATES PASSED.

  • Unit suite: tests=1612 errors=0 skipped=0 failures=0
  • New-code line coverage: new-code executable lines: 33, covered 33, 100.0%
0  ci build: mvn clean compile
0  ci build: mvn test
0  ci build: jacoco:report
0  ci build: jacoco:check
0  new-code coverage >= 80%
0  examples: mvn install
0  examples: pin every example to 9.3.0
0  examples: compile every example
0  lint: verify the formatting gate can fail
0  lint: verify the mutation gate still kills its mutant
0  lint: fmt check
0  package: mvn package -DskipTests
0  wire-shape: pin guard (no spec-pin-bump label)
0  wire-shape: snapshot self-test
0  wire-shape: check snapshot
0  wire-shape: compile + classpath
0  wire-shape: validate
0  wire-shape: baseline unchanged vs main
0  dod: lint no mocks in runtime-e2e
0  dod: runtime-e2e required for user-facing changes
0  integration: mvn verify -DskipUnitTests=true
0  version alignment
0  heartbeat real-stack (linux leg)
0  dco + no AI trailer

R3

Two rounds, each by an independent general-purpose agent reading the committed tree through git, per MASTER_TRACKER_PLAYBOOK.md §"Master's R3 review protocol".

Round 1 (at dc0b721): NEEDS-CHANGES, text only; the mechanism, the tests and the leg were sound.

# Finding Resolution
1 MAJOR "keeps working until v11.1" over-claimed: on a v11.0.0 platform the simulate route answers from the legacy engine (enterprise policy_simulation_handler.go ~:140-175 calls EvaluateDynamicPolicies; PRD v11 §1 items 2 and 10) master ruled the wording for all four SDKs: "keeps answering until v11.1; on a v11.0.0 platform its result comes from the legacy engine, which no longer decides, so it does not predict what the platform enforces", in the three Javadocs, the README and the CHANGELOG; the other SDKs' copies are items on sdk-go #236, sdk-python #260 and sdk-typescript #286
2 "the typed simulate on /api/v1/typed-policies, which ships with the v11 series": no such route exists on enterprise main dropped (master's ruling); the simulate note points at typedPolicies(), as the other two do
3 the README read as a complete list one bullet on the SDK's other static- and dynamic-policy methods, which reach routes the platform stamps the same way and are not @Deprecated in this release
4 the census is keyed on method names, not routes its comment states the gap; a no-op isPublic filter removed
5 NIT two leg checks could not fail replaced by an honest comment: a refusal throws and the outer catch records a FAIL
6 NIT a third copy of the leg build prelude declined here; filed as #242 on master's ruling, with the leftover-jar hazard it hides
7 NIT new deprecation warnings in PolicySimulationTest @SuppressWarnings("deprecation") on the class
8 the once-per-route record (D1's hook) keyed on the concrete path, so a stamped route carrying an id was reported once per id master ruled: fix here. The eleven id-bearing call sites tag their request with the route template, and the record keys on it; three tests (two ids on the override route give one report; all eleven methods give exactly the ten template keys; a source census fails an untagged new call site) and four mutants guard it. The other SDKs' per-id keys are measured on #236, #260 and #286

Round 2 (at 8625055, confirmed at 8108239): SHIP-READY. All eight round-1 findings RESOLVED with file:line; the tag survives the retry executor, interceptors and the auth builder, and OkHttp 4.12.0 has the typed Request.tag(Class). Its own nits, all folded in: the route's template form documented in PlatformRouteDeprecation and onRouteDeprecation and the README; the CHANGELOG's "now reported once" removed, because per-id reporting never shipped (D1's hook is itself unreleased), with the template behaviour folded into D1's Added entry; the README names only the families the SDK calls; the census comment states its blind spot (String.format, StringBuilder, HttpUrl.Builder); the prose says "keep answering"; and the leg gained a live step reading two real static policies by id and asserting one {id} report. ⭐ Highlights it recorded: the template rides on the Request into the single existing choke point, with no second report path and no signature change; the every-method test asserts the exact key set; the census covers the platform's full deprecated families and pins an exact count.

A v11.0.0 platform deprecates /api/v1/policies/simulate, /impact-report
and /conflicts and removes them in v11.1: every response carries
X-AxonFlow-Removed-In: v11.1 and a successor Link naming
/api/v1/typed-policies, plus an RFC 9745 Deprecation header once v11.0.0
is tagged. simulatePolicies, getPolicyImpactReport and
detectPolicyConflicts, and their Async forms, are now @deprecated with
Javadoc saying so. They keep answering until v11.1, but on a v11.0.0
platform their results come from the legacy engine, which no longer
decides, so they do not predict what the platform enforces.

createPolicyOverride and deletePolicyOverride now document that a
v11.0.0 platform retires per-policy overrides and refuses both with
LegacyPolicyWriteFrozenException.

A stamped route that carries an id is reported once, as its route
template, not once per id: the eleven methods that put an id in
a static- or dynamic-policy path tag the request with its template, and
the once-per-route record keys on it. A source census fails any new
such call site that carries no template.

The runtime leg v11_deprecations drives the deprecations against a live
Evaluation-or-above stack.

Refs getaxonflow/axonflow-enterprise#3746

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>
@saurabhjain1592
saurabhjain1592 merged commit c1e7896 into main Sep 13, 2026
17 checks passed
@saurabhjain1592
saurabhjain1592 deleted the w3q/java-deprecations branch September 13, 2026 16:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant