Skip to content

docs(examples): v11 examples and the platform notes - #245

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

saurabhjain1592 merged 1 commit into
mainfrom
w3q/java-docs-examples

Conversation

@saurabhjain1592

Copy link
Copy Markdown
Member

Summary

The Java half of the SDK train's D5, mirroring getaxonflow/axonflow-sdk-go#234 (c921833be) as amended: two runnable examples for the v11 platform, a README section with each chapter's platform minimum, the three corrections to D2's docs, and a CHANGELOG preamble for the release that carries the train. No version number and no version bump; the release is cut separately.

Part of getaxonflow/axonflow-enterprise#3746.

What changes

  • examples/pep-handshake declares an enforcement point's capabilities with PEPHandshake.of(...), decides with the client's declaration and with a client derived by withPEPHandshake(...), printing each verdict and its reasons, and shows a declaration the platform would refuse failing in the client at /pep_id.
  • examples/typed-policies reads what the deployment may author, validates a document and prints every finding, publishes and activates it when AXONFLOW_TYPED_POLICY_PUBLISH=1 (a refusal prints the platform's reason and findings), and shows the document in force.
  • Both are Maven projects that CI's Examples Compile job builds (it compiles every examples/*/pom.xml), use AXONFLOW_AGENT_URL, AXONFLOW_CLIENT_ID and AXONFLOW_CLIENT_SECRET as the existing examples do, exit non-zero on a failed step, and carry the sentence: "after a document with an organization-scope constraint is activated, a decide that does not supply the attribute the constraint conditions on is denied fail-closed with reasons ["unknown_constraint"]; supply the attribute or run this example on a fresh stack". The README runs the handshake example before the typed-policies one.
  • README "The v11.0.0 platform" gives each chapter's platform minimum: the PEP capability handshake from v10.4.0; typed authoring, decision provenance, the deprecation stamps and the write freeze from v11.0.0.
  • The three D2 corrections (lines at 2ad7091): CHANGELOG.md:32 called it "the v11.0.0 PEP capability handshake"; README.md:396 and PEPHandshake.java:38-39 said a client that declares nothing is treated "as it did before the handshake existed". The handshake is read from v10.4.0 (measured by W3-P at tag b10d07061: every plane calls resolveAndRecordPEPHandshakeOnce), and from v11.0.0 a decide under an organization's redact override refuses a caller that does not declare redaction, on both editions. The README heading is now "PEP capability handshake (v10.4.0+)".
  • Typed authoring docs name the per-policy override retirement: createPolicyOverride and deletePolicyOverride answer 409 LEGACY_POLICY_WRITE_FROZEN (agent-api's PerPolicyOverrideRetired response, since getaxonflow/axonflow-enterprise#4221), and a system control is changed in the organization's typed document, in its system_controls section.
  • CHANGELOG preamble under [Unreleased], with no version number: "The first Java SDK release carrying these entries sends the PEP capability handshake, which a platform reads from v10.4.0, and reaches /api/v1/typed-policies, which needs a v11.0.0 platform; against an older platform it works unchanged. Upgrade the SDK before the platform: from v11.0.0, Decide under an organization's redact override refuses a caller that does not declare redaction, and only a release that sends the handshake can declare it." Plus an Added bullet for the examples.
  • runtime-e2e/v11_examples builds both examples against this tree and runs them on a live stack in the README's order (below). The runtime-e2e gate's escape hatch is not used: the examples are user-facing, so they get a leg.

Brief corrections (ruled by master)

  • The examples live at examples/pep-handshake and examples/typed-policies, the repository's hyphenated convention (explain-decision, list-decisions), not the brief's Go-style pep_handshake / typed_policies.
  • The live run is a runtime leg rather than a one-off run: definition-of-done.yml's required "Runtime E2E required for user-facing changes" counts examples/ as user-facing, and the escape hatch is not used on a Java PR.

Live stack

Community on the application database role (probe: all main pools on axonflow_app_role), enterprise 6edf47aaf115f9eb2e07b6478305acbcdb8d24fb, SDK 19b255432, a fresh stack.

axonflow-agent sha256:5cb60daa6eef1bd195d720a112b928d4e4c98e039c394648e1baa2c5aa1bbbd5
axonflow-orchestrator sha256:dc9e7d358b4fbd9266618cfb483e8f85737798d061e76c5f7582052f3060716c

The leg (runtime-e2e/v11_examples/run.sh), verbatim. Steps 1 and 2 are asserted; step 3 is the observation the examples' sentence describes (observed: verdict=deny reasons=[unknown_constraint] obligations=0), printed and not pinned, whose missing policy provenance is getaxonflow/axonflow-enterprise#4227:

=== 1. pep-handshake on a fresh stack
  | SLF4J(W): Class path contains multiple SLF4J providers.
  | SLF4J(W): Found provider [org.slf4j.simple.SimpleServiceProvider@3ee0fea4]
  | SLF4J(W): Found provider [ch.qos.logback.classic.spi.LogbackServiceProvider@48524010]
  | SLF4J(W): See https://www.slf4j.org/codes.html#multiple_bindings for an explanation.
  | SLF4J(I): Actual provider is of type [org.slf4j.simple.SimpleServiceProvider@3ee0fea4]
  | === decide with the client's declaration ===
  | verdict=allow reasons=null obligations=0
  | ok
  | === decide with a derived client's declaration ===
  | verdict=allow reasons=null obligations=0
  | ok
  | === a declaration the platform would refuse ===
  | refused at /pep_id: X-Axonflow-PEP-Handshake: /pep_id: "Checkout:Gateway" is not of the form [a-z0-9][a-z0-9._-]* with at most 128 bytes
  | ok
PASS: pep-handshake exits 0 (exit 0)
PASS: the first decide is allowed on a fresh stack (verdict=allow)
PASS: the declaration the platform would refuse fails in the client, at /pep_id, before anything is sent
=== 2. typed-policies: validate, publish and activate
  | SLF4J(W): Class path contains multiple SLF4J providers.
  | SLF4J(W): Found provider [org.slf4j.simple.SimpleServiceProvider@3d3fcdb0]
  | SLF4J(W): Found provider [ch.qos.logback.classic.spi.LogbackServiceProvider@641147d0]
  | SLF4J(W): See https://www.slf4j.org/codes.html#multiple_bindings for an explanation.
  | SLF4J(I): Actual provider is of type [org.slf4j.simple.SimpleServiceProvider@3d3fcdb0]
  | === what this deployment may author ===
  | root=organization max_documents=20 persistence=database
  | ok
  | === validate the document ===
  | success=true
  | ok
  | === publish and activate ===
  | published sha256:d52ef39b68d6d42d5ed2672d7d3bbd4973b6afb7fad0453df0aff95b02b8d91a (version 1)
  | activated
  | ok
  | === the document in force ===
  | 1378 signed characters; metadata={author={kind=principal, local=runtime-e2e, qualifier=axonflow-api-credential, type=Client}, document_id=org-baseline, title=Organization baseline}
  | ok
PASS: typed-policies exits 0 (exit 0)
PASS: the document is published and activated
=== 3. OBSERVATION, not asserted: pep-handshake after the activation
  | SLF4J(W): Class path contains multiple SLF4J providers.
  | SLF4J(W): Found provider [org.slf4j.simple.SimpleServiceProvider@3ee0fea4]
  | SLF4J(W): Found provider [ch.qos.logback.classic.spi.LogbackServiceProvider@48524010]
  | SLF4J(W): See https://www.slf4j.org/codes.html#multiple_bindings for an explanation.
  | SLF4J(I): Actual provider is of type [org.slf4j.simple.SimpleServiceProvider@3ee0fea4]
  | === decide with the client's declaration ===
  | verdict=deny reasons=[unknown_constraint] obligations=0
  | ok
  | === decide with a derived client's declaration ===
  | verdict=deny reasons=[unknown_constraint] obligations=0
  | ok
  | === a declaration the platform would refuse ===
  | refused at /pep_id: X-Axonflow-PEP-Handshake: /pep_id: "Checkout:Gateway" is not of the form [a-z0-9][a-z0-9._-]* with at most 128 bytes
  | ok
  observed: verdict=deny reasons=[unknown_constraint] obligations=0

PASS: v11_examples

Teardown:

containers by label: 0
volumes by label: 0
app-role.env present: no

Local round

Every pull_request workflow's steps, run locally at 19b255432, plus DCO. ALL GATES PASSED.

  • Unit suite: tests=1612 errors=0 skipped=0 failures=0
  • Examples Compile: compiled 7 example(s), including examples/pep-handshake and examples/typed-policies
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 376fb7c): NEEDS-CHANGES.

# Finding Resolution
F1 MEDIUM a Go-only claim copied into Java: "Decide names the client id as the caller's organization ... on Community leave both unset". Java's decide sends the DecideRequest as built (AxonFlow.java has no caller_identity; DecideRequest is NON_NULL with the identity null by default), and the merged runtime-e2e/pep_handshake_planes runs decide on Community with credentials the paragraph removed; the docs say Enterprise uses the organization id and licence and Community accepts any credentials; the leg runs every step with the same credentials. A brief correction, accepted by master; Python's and TypeScript's examples were measured and do not carry the paragraph (they default the client id to community)
F2 the README's credential advice and the leg disagreed resolved by F1
F3 typed-policies exited 0 after a refused publish when publishing was asked for, the refusal fails the step; Go's example returning nil is an item on sdk-go #236
F4 "null" for list getters that read empty "null or empty"
F5 NIT the leg lacked the slf4j-simple binding the other legs use added
F6 NIT mvn -q -DskipTests install still runs the unit suite in this pom -DskipTests -DskipUnitTests=true in both examples and the README, including its existing line
F7 NIT wording "an absent declaration has a consequence"; the examples bullet cites axonflow-enterprise#3746; the preamble kept verbatim (master's words)
F8 NIT the examples never closed the client try-with-resources in both
⭐1 a shared leg build helper filed as #242 on master's ruling

Round 2 (at bde0252c1, confirmed at 30efc6ad5): SHIP-READY. F1-F8 RESOLVED with file:line, and F1 verified on the wire (decision_handler.go:955-968 compares the body's organization only when it is set). Its three nits, folded in: two older Javadocs (PEPHandshakeException, PEPCapability) still dated the handshake to v11.0.0 and now say it is read from v10.4.0; both examples run through google-java-format; a README comment aligned. It re-checked that the strings the leg greps (verdict=, refused at /pep_id: , a bare activated) are unchanged.

Traps met while verifying

  • A slip of mine: Maven runs outside the machine's heavy-job semaphore. Several small runs while preparing this change took no heavy-slot ticket: targeted mvn test -Dtest=... runs, formatter runs, javac compile-checks with mvn compile dependency:build-classpath, one mvn javadoc:javadoc, and the mvn compile in the rebase script. The habit was that a targeted run needs no slot. None overlapped this change's own round, but on a shared machine they were load the semaphore could not see. Every compile and Maven run now takes a ticket.
  • The first local round at this head was killed by the system for low memory, in the heartbeat step, after every earlier step had passed. That round held its ticket (heavy-slot: slot2 -> w3q-d5-gates (run, ...)). The tree, the local Maven repository's 9.3.0 copy and the process table were checked clean after the kill. The round in this body is the full re-run at the same head, not a stitched one.

Two runnable examples for the v11 platform, each a Maven project that
Examples Compile builds: examples/pep-handshake declares an enforcement
point's capabilities and decides with them, printing each verdict and
its reasons; examples/typed-policies reads what the deployment may
author, validates a document and, with AXONFLOW_TYPED_POLICY_PUBLISH=1,
publishes and activates it. The README runs the handshake example
first, because a decide after an organization-scope constraint is
activated is denied fail-closed with reasons ["unknown_constraint"]
unless it supplies the attribute.

The README gains a v11.0.0 platform section with the platform minimum
of each chapter: the PEP capability handshake is read from v10.4.0, and
typed authoring, decision provenance, the deprecation stamps and the
write freeze need v11.0.0. The handshake's docs no longer say a client
that declares nothing is treated as before: from v11.0.0 a decide under
an organization's redact override refuses a caller that does not
declare redaction. The typed authoring docs name the per-policy
override retirement (agent-api's PerPolicyOverrideRetired response).

The runtime leg v11_examples builds both examples against this tree and
runs them on a live Community stack in the README's order: the fresh
decide is allowed and the refused declaration fails in the client at
/pep_id; the document is published and activated; the decide after
the activation is printed as an observation of the by-design deny.

Refs getaxonflow/axonflow-enterprise#3746

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>
@saurabhjain1592
saurabhjain1592 merged commit afdaec6 into main Sep 13, 2026
17 checks passed
@saurabhjain1592
saurabhjain1592 deleted the w3q/java-docs-examples branch September 13, 2026 17:16
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