Skip to content

feat(typed-policies): v11 parity: typed members, active(), v11 legs - #248

Merged
saurabhjain1592 merged 3 commits into
mainfrom
feat/3746-d6-v11-parity
Sep 14, 2026
Merged

saurabhjain1592 merged 3 commits into
mainfrom
feat/3746-d6-v11-parity

Conversation

@saurabhjain1592

@saurabhjain1592 saurabhjain1592 commented Sep 14, 2026 •

Copy link
Copy Markdown
Member

Summary

v11 parity for the v11.0.0 SDK train (#247): the typed policy answers carry the nine members #247 names, active() keys on the platform's reason, and the v11 examples say what activation does and run as a six-run live leg from outside the tree. The Go, Python and TypeScript SDKs carry the same shape (getaxonflow/axonflow-sdk-go#239, getaxonflow/axonflow-sdk-python#264, getaxonflow/axonflow-sdk-typescript#290); the cross-SDK rows are on getaxonflow/axonflow-enterprise#4249.

  • The typed answers (TypedPolicyTypes, TypedPolicyRefusalException): the nine members in the table below. TemplateOmissionReport (getOmitted(), getOf(), getMessage(), the platform's shape, platform/decision/activation/restriction.go:217-221) sits beside the activation record, not inside it. TypedPolicySystemControl.getMandatory() now returns a plain boolean, false when the platform omits it or sends null, where it returned a nullable Boolean. Typed authoring is unreleased ([Unreleased] in the CHANGELOG), so no released caller sees the type change. TypedPolicyRefusalException gains a seven-argument constructor carrying policy; the six-argument one stays and names no policy. The platform's spec does not declare these members yet: getaxonflow/axonflow-enterprise#4262.
  • active() is empty only for a 404 whose reason is nothing_active. Any other 404, from a platform before v11.0.0 or an endpoint that is not an agent, throws TypedPolicyRefusalException with status 404. A v11.0.0 platform answers a document store it cannot read with 503 storage_unavailable, which active() throws as a TypedPolicyRefusalException too, and the docs say so, citing getaxonflow/axonflow-enterprise#4255 (closed by getaxonflow/axonflow-enterprise#4266). No SDK release has shipped typed policies, so this is new behaviour, stated as such, with no sentence about an earlier release. Two unit tests changed with it, the intended reading: nothingActive stubbed the reason no_active_policy, which is not the platform's, and aDerivedClientsIdentity stubbed /active with a 404 whose body is {}; both now answer the platform's nothing_active.
  • The examples:
    • examples/typed-policies finds its default document on its classpath (its pom puts tests/fixtures/typed_policy_publish_body.json there), so it runs from any directory; AXONFLOW_TYPED_POLICY_BODY still overrides it. It prints the publication's template-omission report before it activates, and a refused publication or activation it asked for fails the run (exit 1), printing refused: HTTP <status> <reason>: <message> (or activation refused: ...), as the Go, Python and TypeScript examples do;
    • examples/pep-handshake says the engine refuses on every edition, and carries the getaxonflow/axonflow-enterprise#4247 follow-on;
    • the README runs the handshake example first.
  • The README's typed section gains "Activation replaces the organization template" (the publish fixture is minimal and omits the template's controls), getPolicy(), the active() bullet, and "The agent stamps the organization and the author" (on Community the organization is the deployment's).

Closes #247
Part of getaxonflow/axonflow-enterprise#3746

The members, field by field

Member Java Read Unit test (TypedPoliciesTest) Live, runtime-e2e/typed_policies
refusal policy TypedPolicyRefusalException.getPolicy() AxonFlow.typedPolicyRefusal everyRefusalIsTyped (every row asserts getPolicy(); the outage row names none) unit only: a Community stack has no tier ceiling to cross
edition catalog_digest TypedAuthoringEdition.getCatalogDigest() Jackson, @JsonCreator editionVocabulary (present and absent) sha256:8eec9ebc…, asserted present
edition registry_version getRegistryVersion() (Integer) the same the same 2, asserted above 0
edition catalog_fixture getCatalogFixture() (Boolean) the same the same false, asserted
publication template_omissions TypedPolicyPublication.getTemplateOmissions() the same publishCarriesTheOmissionReport; null and omitted: null in nullCollectionsReadAsEmpty 22 of 22: the minimal fixture omits every template control, asserted getOmitted().size() == getOf() > 0
publication template_omissions_unavailable getTemplateOmissionsUnavailable() the same aPublicationWhoseOmissionReportIsUnavailableSaysWhy unit only: the stack reads its template
activation template_omissions TypedPolicyActivation.getTemplateOmissions() the same activationCarriesTheOmissionReport the same 22, asserted equal to the publication's
activation template_omissions_unavailable getTemplateOmissionsUnavailable() the same anActivationWhoseOmissionReportIsUnavailableSaysWhy unit only, as above
control name TypedPolicySystemControl.getName() the same aControlNamesItselfAndIsNotMandatoryWhenUnsaid 118 of 118 controls named, asserted above 0
control mandatory boolean getMandatory() (was Boolean) Boolean.TRUE.equals(...) the same test: absent and null both read false 25 of 118 mandatory, asserted above 0
active() on 404 nothing_active Optional.empty() active(), typedReason nothingActive; anotherActive404IsARefusal (a plain-text 404 and a 404 with another reason) empty before any activation (the platform's 404 nothing_active), in both legs

#247, item by item

  1. The nine members: the table above.
  2. active() keyed on nothing_active, with getaxonflow/axonflow-enterprise#4255 in the javadoc, the README and the CHANGELOG. No departure or earlier-release sentence.
  3. The getaxonflow/axonflow-enterprise#4247 follow-on after every copy of the unknown_constraint sentence, six in all: examples/pep-handshake/.../PepHandshake.java, examples/typed-policies/.../TypedPolicies.java, README.md, the CHANGELOG's examples entry, runtime-e2e/v11_examples/README.md and run.sh. runtime-e2e/v11_examples/README.md cited getaxonflow/axonflow-enterprise#4227 as open ("That deny names no evaluated policy"); #4247 closed it, and the README now carries the follow-on and "A stack built before getaxonflow/axonflow-enterprise#4247 shows only the bare ["unknown_constraint"]."
  4. The omission report before activation, and the README sentence that activating a document that omits the organization template's controls removes them for the organization, count-free, with the fixture described as minimal.
  5. The handshake example first: the README's runnable block and ordering sentence, and both runtime READMEs.
  6. The legs: runtime-e2e/v11_examples extended from three runs to six, and runtime-e2e/typed_policies asserting the members live. See Live legs.
  7. Non-zero exit on a refused publication or activation, asserted by runs 4 and 5.

The route template (the brief's check): this SDK's route-deprecation record already keys on the route template (withRoute tags each id-bearing request; noteRouteDeprecation keys on the tag), with the two-id test and the census of the seven families. This change adds the exact served-request pin to everyIdBearingMethodReportsItsTemplateOnce: the eleven methods, each called with two ids, send exactly the 22 requests in call order, so a method that shares its template with another (updateDynamicPolicy and toggleDynamicPolicy, both PUT /api/v1/dynamic-policies/{id}) is seen to send its own. The mutants below prove each part.

Tests

New tests in TypedPoliciesTest, one per guard, each run by name in the mutant run's baseline below:

  • anotherActive404IsARefusal (a plain-text 404 and a 404 with another reason)
  • editionVocabulary (present, and absent reads as null)
  • publishCarriesTheOmissionReport and aPublicationWhoseOmissionReportIsUnavailableSaysWhy
  • activationCarriesTheOmissionReport (beside the record, not inside it) and anActivationWhoseOmissionReportIsUnavailableSaysWhy
  • aControlNamesItselfAndIsNotMandatoryWhenUnsaid (absent and null both read false, compared by value)

Changed:

  • nothingActive stubs the platform's reason nothing_active; it stubbed no_active_policy, which is not the platform's reason and now reads as a refusal. aDerivedClientsIdentity stubbed /active with a 404 whose body is {}; it now answers nothing_active. Both are the intended reading, not a regression.
  • everyRefusalIsTyped: the tier row carries policy, every row asserts getPolicy() (the outage row names none), and the table gains the active read's 503 storage_unavailable (getaxonflow/axonflow-enterprise#4255) through a new active case in the table's call helper.
  • nullCollectionsReadAsEmpty gains template_omissions: null (no report) and omitted: null (empty).
  • V11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOnce pins the 22 requests the eleven methods send with two ids, in call order, from WireMock's serve events.

Local round

Every step at the head 4fa4bd9, each under its own build-slot ticket with one Maven thread, mirroring the required contexts. Before each step the round checks that the head is unchanged and the tree clean.

Step Required context Command rc
lint lint scripts/verify-formatting-gate.sh, scripts/mutation-gate.sh, mvn com.spotify.fmt:fmt-maven-plugin:check 0
build Build Summary (the Java 17 build a pull request runs) mvn clean compile, mvn test (1619 run, 0 failures, 0 errors), mvn jacoco:report, mvn jacoco:check (all coverage checks met) 0
no mocks Lint — no mocks in runtime-e2e/ scripts/lint-no-mocks-in-runtime-e2e.sh 0
runtime-e2e gate Runtime E2E required for user-facing changes the change touches src/main/java/ and examples/ and, beside them, runtime-e2e/, which is the gate's condition 0
examples Examples Compile (not required) every example (7) and the typed_policies driver compiled with javac against target/classes 0

One deviation, stated: CI's Examples Compile installs the SDK into the local Maven repository and compiles each example with its pom. This round does not overwrite the shared local copy of a released version, so it compiles the same sources with javac against this tree's classes. The files are formatted with google-java-format 1.28.0 (the version the plugin pins) on the named files only, and the plugin's own check passes.

Mutants

Each mutant replaces one occurrence of a string in the source (the k-th of exactly n, where n is asserted), restored from saved bytes after every mutant, never with git checkout. Each runs mvn test -Dtest=Class#method with one thread; it counts as KILLED only when its named testcase ran and its JUnit report holds a <failure> or <error>, INVALID when the mutant does not compile, and ERROR when the named testcase is absent. The unmutated baseline must pass every named testcase first: 13 named tests, all passed. Before running, the harness prints the token each mutant changes and the line it lands on, and before each mutant it checks that the head is unchanged and the tree clean. 22 of 22 KILLED at 45c2ad4, the tree restored clean at the same head. The head, 4fa4bd9, changes nothing in src/ since 520859e (git diff --name-only 520859e 4fa4bd9 -- src/ is empty), so every mutated line is the head's.

A harness note. The first run stopped at its baseline on a harness bug, not the tests: it passed surefire a per-run reports directory with -Dsurefire.reportsDirectory, but that parameter has no command-line property (the plugin's descriptor gives it no expression), so the override was ignored and the harness read a directory that was never written; the tests themselves had passed. The harness now reads target/surefire-reports, accepts a report only when it was written at or after the run's start, and copies it as evidence; a planted self-check asks for the same fresh report with a start time after it was written and requires "not run", so a stale report can never count as a pass or a kill.

Mutant Change Killed by
active-any-404-is-empty every 404 reads as nothing active anotherActive404IsARefusal
active-wrong-reason the reason compared is no_active_policy nothingActive
reason-read-from-error the reason is read from error nothingActive
refusal-policy-dropped the refusal is built without policy everyRefusalIsTyped
refusal-policy-not-kept TypedPolicyRefusalException stores null for policy everyRefusalIsTyped
edition-digest-not-kept the edition stores null for catalog_digest editionVocabulary
edition-registry-not-kept the edition stores null for registry_version editionVocabulary
edition-fixture-not-kept the edition stores null for catalog_fixture editionVocabulary
publication-omissions-not-kept the publication stores null for template_omissions publishCarriesTheOmissionReport
publication-unavailable-not-kept the publication stores null for template_omissions_unavailable aPublicationWhoseOmissionReportIsUnavailableSaysWhy
activation-omissions-not-kept the activation stores null for template_omissions activationCarriesTheOmissionReport
activation-unavailable-not-kept the activation stores null for template_omissions_unavailable anActivationWhoseOmissionReportIsUnavailableSaysWhy
report-omitted-null-not-empty omitted is kept as sent, so null stays null nullCollectionsReadAsEmpty
report-of-dropped the report stores null for of publishCarriesTheOmissionReport
report-message-dropped the report stores null for message publishCarriesTheOmissionReport
control-name-not-kept the control stores null for name aControlNamesItselfAndIsNotMandatoryWhenUnsaid
mandatory-unboxes-null mandatory is unboxed from the sent Boolean, so absent or null fails aControlNamesItselfAndIsNotMandatoryWhenUnsaid
route-key-ignores-template the record keys on the concrete path V11DeprecationsTest.aStampedRouteWithAnIdIsReportedOnceNotOncePerId
a-site-drops-its-template getStaticPolicyVersions builds its request without withRoute V11DeprecationsTest.everyConcatenatedStampedPathCarriesItsTemplate
versions-template-wrong the {id}/versions template loses /versions V11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOnce
toggle-dynamic-sends-patch toggleDynamicPolicy sends PATCH V11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOnce
toggle-sends-a-fixed-id toggleDynamicPolicy sends a fixed id instead of its own (its template, and so the reported set, is unchanged: only the served-request pin sees it) V11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOnce

Live legs

Both legs ran at the head 4fa4bd9, each on its own fresh Community stack. The stacks were built from axonflow-enterprise 857455033, with the agent and orchestrator on the application database role (the boot probe passed 3 of 3, with every pool on axonflow_app_role). Neither used an enterprise licence or secret. Each stack was torn down by its compose project label, leaving 0 containers and 0 volumes by label.

runtime-e2e/typed_policies: PASS, 23 assertions, 0 failed. What it read live:

  • active() is empty before anything is activated: the platform's 404 nothing_active.
  • The edition names its vocabulary: catalog_digest=sha256:8eec9ebc…, registry_version=2, catalog_fixture=false.
  • system() returns 118 controls: 118 named, 25 mandatory.
  • The publication reports template omissions: 22 of 22, and the activation reports the same 22.
  • The document in force is the one just activated, carrying the published policies; its source is the signed source, and the platform signed the author as Client / axonflow-api-credential / runtime-e2e, not the name in the request.
  • Re-activating the active digest: 409 activation_refused ("refusing to promote version 1 over active version 1").
  • Publishing with no fixtures: 422 publication_refused.
  • An unregistered action: a rejecting ACTION_NOT_REGISTERED finding on validate, and 422 document_refused carrying it on publish.

runtime-e2e/v11_examples: PASS, 13 assertions, 0 failed, after the curl precondition read 404 nothing_active (the leg first waits for /health). The examples were compiled from this tree's sources against this tree's build, and typed-policies' default document came only from the example's own resources phase (its pom's <resources>), so run 2 passing also proves that path. Every example ran from a temporary directory, outside the tree, with no body file and the credentials unset:

  • Run 1, pep-handshake: exit 0. The first decide was verdict=allow, and the declaration the platform would refuse failed in the client, at /pep_id, before anything was sent.
  • Run 2, typed-policies without publishing: exit 0, nothing is active.
  • Run 3, with AXONFLOW_TYPED_POLICY_PUBLISH=1: exit 0. It printed template omissions: 22 of 22 template controls: ... before activated.
  • Run 4, a document with an unregistered action: exit 1, refused: HTTP 422 document_refused: ....
  • Run 5, the same document published again: published sha256:193c2e3b... (version 1), then activation refused: HTTP 409 activation_refused: authoring: refusing to promote version 1 over active version 1; ..., exit 1.
  • Run 6, observed, not asserted: verdict=deny reasons=[unknown_constraint]. The stack is built from 857455033, which predates getaxonflow/axonflow-enterprise#4247, so the deny carries only the bare code.

R3

Two rounds by a read-only reviewer that built and ran nothing, each reading only the committed content (git show at the sha, because a mutation run and a local round were using the working tree), checked against the platform source (axonflow-enterprise at 857455033, and main at 8a1e2d312) and against the Go, Python and TypeScript SDKs' equivalents (getaxonflow/axonflow-sdk-go#239, getaxonflow/axonflow-sdk-python#264, getaxonflow/axonflow-sdk-typescript#290).

Round 1, at 520859e: NOT-SHIP-READY, with one medium item and three low ones, all folded at 45c2ad4. It verified the other requirements by file and line, and found that none of the TypeScript change's review findings repeats here (the #4255 wording, the member claim, the bounded health wait, the cleared environment).

  • Medium: the leg never exercised the example's own build. runtime-e2e/v11_examples/run.sh compiled the examples with javac and put tests/fixtures on the classpath itself, so the <resources> block in examples/typed-policies/pom.xml, which the README's mvn command relies on, was untested: a wrong path there would have passed every run. The leg now runs that pom's resources phase alone (compiling with it would resolve the released SDK, not this tree's), checks the document landed in its target/classes, and puts that directory on the classpath.
  • Run 3's check matched any template omissions: line; it now requires a report, template omissions: N of M template controls: .
  • javac exits 2 on a usage error, and the leg keeps exit 2 for its precondition; every build failure now exits 1.
  • A comment said line_of returns 0 when nothing matches; it returns an empty string.

Round 2, at 45c2ad4: SHIP-READY, with one low item, folded at 4fa4bd9. It verified each round-1 fold by file and line, including from the Maven plugin descriptors that the resources goal resolves no dependencies (so the released SDK is never fetched) and that the pom's ../../tests/fixtures resolves against the example's own directory under -f. The low item: Maven skips a missing resource directory without an error, and target/ is ignored, so after one run the copied document stayed behind and a wrong pom path would have passed every later run. The leg now clears that output before the resources phase, so a wrong path fails the leg before any run.

Items not modified

  • TypedPolicySystemControl control and dynamic. At axonflow-enterprise main, each system control also carries control (always) and dynamic (omitted when false), from getaxonflow/axonflow-enterprise#4221, which landed after 857455033, the build the legs run on. They are outside this change's nine members; unknown members are ignored, so nothing breaks, and the CHANGELOG names the members rather than claiming every one.
  • runtime-e2e/typed_policies/run.sh still finds the SDK jar with a glob (ls target/axonflow-sdk-*.jar | ... | head -1), which a jar left by an earlier build can satisfy: one of the sites runtime-e2e legs pick the SDK jar by glob after a build without clean; a leftover jar is selected silently #242 lists, left to it. The v11_examples leg names its jar by the pom's version.

CI notes

All four required contexts are green by name at 4fa4bd9: lint (run 34819581304), Lint — no mocks in runtime-e2e/ (run 34819581140), Runtime E2E required for user-facing changes (run 34819581140) and Build Summary (run 34819581304). Every other completed check at the head passed (build (17), Examples Compile, Contract Integration (WireMock, JDK 17), real-stack ubuntu-latest, CodeQL and its three analyses, DCO, Validate Version Alignment, Validate Wire Shape); Live Integration (Community Stack) reported skipped, and package, which is not required, was still running when this was written.

The typed answers carry the refusal's policy (getPolicy(), through a
new seven-argument constructor; the six-argument one names no policy);
the edition's catalog_digest, registry_version and catalog_fixture;
template_omissions (TemplateOmissionReport) and
template_omissions_unavailable on the publication and the activation;
and the system control's name. TypedPolicySystemControl.getMandatory()
returns a plain boolean, false when the platform omits it or sends null.

active() is empty only for a 404 whose reason is nothing_active; any
other 404 is a TypedPolicyRefusalException with status 404, and so is a
503 storage_unavailable (getaxonflow/axonflow-enterprise#4255).

The examples: typed-policies finds its default document on its
classpath, prints the template-omission report before it activates, and
exits non-zero when a publication or activation it asked for is
refused. The handshake example runs first everywhere, and every
unknown_constraint sentence carries the
getaxonflow/axonflow-enterprise#4247 follow-on.

runtime-e2e/v11_examples makes six runs from outside the tree with no
body file; runtime-e2e/typed_policies asserts the new members live.
V11DeprecationsTest pins the exact 22 requests the id-bearing methods
send.

Closes #247

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>
runtime-e2e/v11_examples compiled the examples with javac and put
tests/fixtures on the classpath itself, so it never exercised the
resource block in examples/typed-policies/pom.xml that the README's mvn
command relies on. The leg now runs that pom's resources phase alone
(compiling with it would resolve the released SDK, not this tree's) and
puts its target/classes on the classpath, so a wrong path in the pom
fails run 2.

Run 3's check requires a report ("template omissions: N of M template
controls"), not only the prefix. A javac or mvn failure exits 1: javac
exits 2 on a usage error, and the leg keeps exit 2 for its
precondition.

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>
Maven skips a missing resource directory without an error, and target/
is ignored, so after one run of runtime-e2e/v11_examples the document
the example's resources phase copied stays behind, and a wrong path in
examples/typed-policies/pom.xml would pass the check on every later
run. The leg now clears that output before the resources phase, so a
wrong path fails the leg before any run (not run 2, as the previous
commit's message says).

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>
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.

D6: v11 parity (v11.0.0 SDK train)

1 participant