Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **`AxonFlowConfig.Builder.onRouteDeprecation(...)`.** When the platform marks a route a call used
as deprecated (`X-AxonFlow-Removed-In` or an RFC 9745 `Deprecation` header, with the successor
from `Link: <...>; rel="successor-version"`), the SDK reports it once per route: to this
listener when it is set, otherwise to the log at WARN. From v11.0.0 the legacy static- and
dynamic-policy reads carry it.
listener when it is set, otherwise to the log at WARN. A route whose path carries an id is
reported once, as its template (`GET /api/v1/static-policies/{id}`), not once per id. From
v11.0.0 the legacy policy routes carry it: the static- and dynamic-policy routes and the policy
simulation routes.
- **The v11.0.0 PEP capability handshake (axonflow-enterprise#3746).** An enforcement point
declares the obligation types and schema versions it can discharge with `PEPHandshake.of(...)`
and `PEPCapability.of(...)`, presented as `X-Axonflow-PEP-Handshake` on every call to a plane
Expand All @@ -49,6 +51,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
its own namespace. Rolling back and withdrawing are customer portal operations the agent does
not proxy, so the SDK has no method for either.

### Deprecated

- **The v11.0.0 policy simulation routes (axonflow-enterprise#3746).** `simulatePolicies`,
`getPolicyImpactReport` and `detectPolicyConflicts`, and their `Async` forms, are deprecated: a
v11.0.0 platform deprecates `/api/v1/policies/simulate`, `/impact-report` and `/conflicts` and
removes them in v11.1, and stamps every response with `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), which `AxonFlowConfig.Builder.onRouteDeprecation` reports once per route.
They keep answering until then, 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`.

### Fixed

- **A static-policy read no longer fails on a category the SDK does not know
Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -416,6 +416,14 @@ TypedPolicySystemCorpus system = typed.system(); // the platform's own controls
- **Refusals are typed.** Every refusal is a `TypedPolicyRefusalException` with the HTTP status, the platform's reason (such as `publication_refused`, `activation_refused` or `tier_limit`), any findings, and `getRetryAfter()` when the refusal is retryable; a 401 is the client's `AuthenticationException`. On an edition with separation of duties, publishing refuses with the finding code `APPROVER_IS_AUTHOR`: the route names no approver, and such a deployment approves in the customer portal.
- **The document is the authoring model itself,** a `Map<String, Object>` rather than Java types, so a field the policy vocabulary gains is authorable without an SDK release. A null fixtures list sends none; an empty one sends `[]`. `validate` answers identically on every edition; the edition's boundary is applied when you publish.

## v11.0.0 deprecations

A v11.0.0 platform deprecates its legacy policy routes and removes them in v11.1. 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, and the client reports each such route once through `AxonFlowConfig.Builder.onRouteDeprecation` (or logs it once at WARN when that is unset). A client derived with `asUser` shares that record, so a route is reported once per client family, and a route whose path carries an id is reported as its template, such as `POST /api/v1/static-policies/{id}/override`.

- **Policy simulation.** `simulatePolicies`, `getPolicyImpactReport` and `detectPolicyConflicts`, and their `Async` forms, are `@Deprecated` and 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; policy is authored and tested through `client.typedPolicies()` (see [Typed policy authoring](#typed-policy-authoring-v1100)).
- **The other legacy policy routes.** The SDK's other methods on `/api/v1/static-policies` and `/api/v1/dynamic-policies` reach routes the platform stamps and removes the same way (it stamps its other legacy families too). The client reports each at runtime; those methods are not marked `@Deprecated` in this release.
- **Per-policy overrides.** A v11.0.0 platform retires them: `createPolicyOverride` and `deletePolicyOverride` throw a `LegacyPolicyWriteFrozenException` (409, `LEGACY_POLICY_WRITE_FROZEN`) whose message names the typed policy route, where a system control is changed in the organization's typed document.

## Reading decisions: who is asking decides what comes back

`explainDecision` and `listDecisions` — and the audit reads — are scoped to the
Expand Down
30 changes: 30 additions & 0 deletions runtime-e2e/v11_deprecations/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# v11_deprecations

Real-stack proof of the v11.0.0 deprecations through the SDK. `V11DeprecationsTest.java` calls the three policy simulation methods the SDK marks `@Deprecated` (`simulatePolicies`, `detectPolicyConflicts` and `getPolicyImpactReport`) and the two retired override writes against a real v11 agent and orchestrator, and reads what `AxonFlowConfig.Builder.onRouteDeprecation` reports. Nothing is mocked.

## What it proves

| Step | Expected |
|---|---|
| `simulatePolicies`, `detectPolicyConflicts` | keep answering; each route reported exactly once, with `X-AxonFlow-Removed-In: v11.1` and the successor exactly `/api/v1/typed-policies` from the `Link` |
| `getPolicyImpactReport` | a non-2xx refusal (see below), reported once the same way |
| the RFC 9745 `Deprecation` header | absent, or `@<unix seconds>`: the platform adds it once v11.0.0 is tagged and omits it until then |
| a second call of each, and a call from a client derived with `asUser` | nothing new reported: once per route per client family |
| `createPolicyOverride`, `deletePolicyOverride` | `LegacyPolicyWriteFrozenException`, 409 `LEGACY_POLICY_WRITE_FROZEN`, whose message names `/api/v1/typed-policies`; the leg prints the platform's message |
| two static policies read by id | reported once, as `GET /api/v1/static-policies/{id}`; no report names a concrete id |
| a wrong secret | refused with the SDK's `AuthenticationException` (401), not swallowed |

## Why the impact report is proved on its signal, not on a result

The platform evaluates the named policy from the organization's tenant policies. A fresh organization has none, and a v11 platform refuses to create one (the legacy write freeze), so on a fresh v11 stack the call names a policy that cannot exist. The leg asserts only that the platform refuses it with a non-2xx (today a `500`, tracked in getaxonflow/axonflow-enterprise#4223), so a fix to that status leaves this leg green. The deprecation is stamped whatever the handler answers, and that is what this leg proves for the route. On an organization that still holds legacy tenant policies, the call returns its report until v11.1.

## Run

The simulation routes are registered from the Evaluation licence up, so boot an enterprise stack from the platform's main (`scripts/setup-e2e-testing.sh production-posture`). Then, from the repository root, with the credentials that script writes:

```
set -a; source /tmp/axonflow-e2e-env.sh; set +a
AXONFLOW_AGENT_URL=http://localhost:8080 ./runtime-e2e/v11_deprecations/run.sh
```

It exits non-zero on any failed assertion. It writes nothing the platform keeps: both override writes are refused.
278 changes: 278 additions & 0 deletions runtime-e2e/v11_deprecations/V11DeprecationsTest.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,278 @@
// Copyright 2026 AxonFlow
// SPDX-License-Identifier: MIT

import com.getaxonflow.sdk.AxonFlow;
import com.getaxonflow.sdk.AxonFlowConfig;
import com.getaxonflow.sdk.PlatformRouteDeprecation;
import com.getaxonflow.sdk.exceptions.AuthenticationException;
import com.getaxonflow.sdk.exceptions.AxonFlowException;
import com.getaxonflow.sdk.exceptions.LegacyPolicyWriteFrozenException;
import com.getaxonflow.sdk.simulation.ImpactReportInput;
import com.getaxonflow.sdk.simulation.ImpactReportRequest;
import com.getaxonflow.sdk.simulation.PolicyConflictResponse;
import com.getaxonflow.sdk.simulation.SimulatePoliciesRequest;
import com.getaxonflow.sdk.simulation.SimulatePoliciesResponse;
import com.getaxonflow.sdk.types.policies.PolicyTypes.CreatePolicyOverrideRequest;
import com.getaxonflow.sdk.types.policies.PolicyTypes.OverrideAction;
import com.getaxonflow.sdk.types.policies.PolicyTypes.StaticPolicy;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.function.Consumer;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

/**
* Real-stack proof of the v11.0.0 deprecations through the SDK.
*
* <p>Drives the built SDK against a live v11 agent and orchestrator on the Evaluation licence or
* above and asserts:
*
* <ol>
* <li>{@code simulatePolicies} and {@code detectPolicyConflicts} keep answering, and {@code
* getPolicyImpactReport} is refused with a non-2xx on a fresh v11 organization (never pinned
* to one status: getaxonflow/axonflow-enterprise#4223).
* <li>Each of the three routes is reported exactly once through {@code onRouteDeprecation}, with
* {@code X-AxonFlow-Removed-In: v11.1}, the successor exactly {@code /api/v1/typed-policies},
* and a {@code Deprecation} header absent or {@code @<unix seconds>}.
* <li>A second call of each, and a client derived with {@code asUser}, report nothing new.
* <li>{@code createPolicyOverride} and {@code deletePolicyOverride} throw {@code
* LegacyPolicyWriteFrozenException} (409) naming the typed route; the platform's message is
* printed.
* <li>Two static policies read by id are reported once, as {@code GET
* /api/v1/static-policies/{id}}, and no report names a concrete id.
* <li>A wrong secret is refused with the SDK's {@code AuthenticationException} (401).
* </ol>
*
* <p>Nothing is mocked, and nothing the platform keeps is written: both override writes are
* refused. Run with {@code run.sh}.
*/
@SuppressWarnings("deprecation")
public class V11DeprecationsTest {

static final String AGENT =
System.getenv().getOrDefault("AXONFLOW_AGENT_URL", "http://localhost:8080");
static final String SUCCESSOR = "/api/v1/typed-policies";
static final Pattern DEPRECATION = Pattern.compile("@[0-9]+");
static final String[] ROUTES = {"simulate", "conflicts", "impact-report"};
static final List<String> FAILURES = new ArrayList<>();

static void check(boolean ok, String description) {
System.out.println((ok ? "PASS: " : "FAIL: ") + description);
if (!ok) {
FAILURES.add(description);
}
}

static String env(String name) {
String value = System.getenv(name);
return value == null || value.isEmpty() ? null : value;
}

static AxonFlow client(
String clientId, String clientSecret, Consumer<PlatformRouteDeprecation> listener) {
return AxonFlow.create(
AxonFlowConfig.builder()
.endpoint(AGENT)
.clientId(clientId)
.clientSecret(clientSecret)
.onRouteDeprecation(listener)
.build());
}

static SimulatePoliciesRequest simulate() {
return SimulatePoliciesRequest.builder()
.query("Transfer $50,000 to external account")
.requestType("execute")
.build();
}

/** The impact report a fresh v11 organization refuses; returns the answer's status. */
static int impactStatus(AxonFlow client) {
try {
client.getPolicyImpactReport(
ImpactReportRequest.builder()
.policyId("sys_sqli_drop_table")
.inputs(List.of(ImpactReportInput.builder().query("DROP TABLE customers").build()))
.build());
return 200;
} catch (AxonFlowException e) {
return e.getStatusCode();
}
}

static void expectFrozen(String label, Runnable write) {
try {
write.run();
check(false, label + " was accepted; a v11.0.0 platform refuses it");
} catch (LegacyPolicyWriteFrozenException e) {
System.out.println(" platform message: " + e.getMessage());
check(
e.getStatusCode() == 409
&& LegacyPolicyWriteFrozenException.CODE.equals(e.getErrorCode())
&& e.getMessage().contains(SUCCESSOR),
label
+ " throws LegacyPolicyWriteFrozenException ("
+ e.getStatusCode()
+ ", "
+ e.getErrorCode()
+ ") naming "
+ SUCCESSOR);
} catch (AxonFlowException e) {
check(
false,
label
+ " threw "
+ e.getClass().getSimpleName()
+ " ("
+ e.getStatusCode()
+ ", "
+ e.getErrorCode()
+ "): "
+ e.getMessage());
}
}

public static void main(String[] args) {
String clientId = env("AXONFLOW_CLIENT_ID");
String clientSecret = env("AXONFLOW_CLIENT_SECRET");
String userToken = env("AXONFLOW_USER_TOKEN");
System.out.println("agent: " + AGENT);
if (clientId == null || clientSecret == null || userToken == null) {
System.out.println(
"FAIL: set AXONFLOW_CLIENT_ID, AXONFLOW_CLIENT_SECRET and AXONFLOW_USER_TOKEN"
+ " (source the stack's env file)");
System.exit(2);
}
List<PlatformRouteDeprecation> reported = Collections.synchronizedList(new ArrayList<>());
AxonFlow client = client(clientId, clientSecret, reported::add);

try {
// 1. The two routes that still answer, and the one a fresh organization refuses.
SimulatePoliciesResponse simulated = client.simulatePolicies(simulate());
// Reaching this check means the call answered 2xx: a refusal throws, and the outer catch
// records it as a FAIL.
check(
true,
"simulatePolicies() returned (allowed="
+ simulated.isAllowed()
+ ", "
+ simulated.getTotalPolicies()
+ " policies evaluated)");
PolicyConflictResponse conflicts = client.detectPolicyConflicts();
check(
true,
"detectPolicyConflicts() returned ("
+ conflicts.getConflictCount()
+ " conflicts in "
+ conflicts.getTotalPolicies()
+ " policies)");
int status = impactStatus(client);
check(
status >= 400,
"getPolicyImpactReport() is refused with a non-2xx on a fresh v11 organization ("
+ status
+ ")");

// 2. Each route reported exactly once, with the platform's own signal.
for (String route : ROUTES) {
String key = "POST /api/v1/policies/" + route;
List<PlatformRouteDeprecation> matches =
reported.stream().filter(d -> key.equals(d.getRoute())).collect(Collectors.toList());
check(matches.size() == 1, key + " is reported exactly once (" + matches.size() + ")");
if (matches.isEmpty()) {
continue;
}
PlatformRouteDeprecation d = matches.get(0);
System.out.println(" reported: " + d);
check(
SUCCESSOR.equals(d.getSuccessor()),
key + ": the successor is exactly " + SUCCESSOR + " (" + d.getSuccessor() + ")");
check("v11.1".equals(d.getRemovedIn()), key + ": removed in v11.1 (" + d.getRemovedIn() + ")");
check(
d.getDeprecation() == null || DEPRECATION.matcher(d.getDeprecation()).matches(),
key + ": Deprecation absent or @<unix seconds> (" + d.getDeprecation() + ")");
}
check(reported.size() == ROUTES.length, "nothing else is reported (" + reported.size() + ")");

// 3. Once per route per client family: a second call, and a derived client, add nothing.
int before = reported.size();
client.simulatePolicies(simulate());
client.detectPolicyConflicts();
impactStatus(client);
AxonFlow derived = client.asUser(userToken);
derived.simulatePolicies(simulate());
derived.detectPolicyConflicts();
impactStatus(derived);
check(
reported.size() == before,
"a second call of each, and a client derived with asUser, report nothing new ("
+ (reported.size() - before)
+ " new)");

// 4. The retired per-policy override writes.
expectFrozen(
"createPolicyOverride",
() ->
client.createPolicyOverride(
"sys_sqli_drop_table",
CreatePolicyOverrideRequest.builder()
.actionOverride(OverrideAction.WARN)
.overrideReason("runtime-e2e v11_deprecations")
.build()));
expectFrozen(
"deletePolicyOverride", () -> client.deletePolicyOverride("sys_sqli_drop_table"));

// 6. A stamped route that carries an id is reported once, as its template: two real static
// policies read by id add one report, and no report names a concrete id.
List<StaticPolicy> listed = client.listStaticPolicies();
check(listed.size() >= 2, "listStaticPolicies() returned policies to read by id (" + listed.size() + ")");
if (listed.size() >= 2) {
List<String> ids = List.of(listed.get(0).getId(), listed.get(1).getId());
for (String id : ids) {
try {
client.getStaticPolicy(id);
} catch (AxonFlowException e) {
System.out.println(" getStaticPolicy(" + id + ") answered " + e.getStatusCode());
}
}
long byTemplate =
reported.stream().filter(d -> "GET /api/v1/static-policies/{id}".equals(d.getRoute())).count();
check(
byTemplate == 1,
"two static policies read by id are reported once, as GET /api/v1/static-policies/{id} ("
+ byTemplate
+ ")");
check(
reported.stream().noneMatch(d -> ids.stream().anyMatch(id -> d.getRoute().contains(id))),
"no report names a concrete id");
}

// 5. An auth failure stays observable: a wrong secret is the SDK's AuthenticationException.
try {
client(clientId, "not-the-licence", d -> {}).simulatePolicies(simulate());
check(false, "a wrong secret was accepted");
} catch (AuthenticationException e) {
check(
e.getStatusCode() == 401,
"a wrong secret is refused with AuthenticationException " + e.getStatusCode());
} catch (AxonFlowException e) {
check(
false,
"a wrong secret threw "
+ e.getClass().getSimpleName()
+ " ("
+ e.getStatusCode()
+ "), not AuthenticationException");
}
} catch (Exception e) {
check(false, "the run threw " + e.getClass().getSimpleName() + ": " + e.getMessage());
}

if (!FAILURES.isEmpty()) {
System.out.println("\nFAIL: v11_deprecations (" + FAILURES.size() + " assertion(s))");
System.exit(1);
}
System.out.println("\nPASS: v11_deprecations");
}
}
Loading
Loading