Repository navigation
feat(typed-policies): v11 parity: typed members, active(), v11 legs - #248
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.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 plainboolean,falsewhen the platform omits it or sendsnull, where it returned a nullableBoolean. Typed authoring is unreleased ([Unreleased]in the CHANGELOG), so no released caller sees the type change.TypedPolicyRefusalExceptiongains a seven-argument constructor carryingpolicy; 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 isnothing_active. Any other 404, from a platform before v11.0.0 or an endpoint that is not an agent, throwsTypedPolicyRefusalExceptionwith status 404. A v11.0.0 platform answers a document store it cannot read with 503storage_unavailable, whichactive()throws as aTypedPolicyRefusalExceptiontoo, 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:nothingActivestubbed the reasonno_active_policy, which is not the platform's, andaDerivedClientsIdentitystubbed/activewith a 404 whose body is{}; both now answer the platform'snothing_active.examples/typed-policiesfinds its default document on its classpath (its pom putstests/fixtures/typed_policy_publish_body.jsonthere), so it runs from any directory;AXONFLOW_TYPED_POLICY_BODYstill 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), printingrefused: HTTP <status> <reason>: <message>(oractivation refused: ...), as the Go, Python and TypeScript examples do;examples/pep-handshakesays the engine refuses on every edition, and carries the getaxonflow/axonflow-enterprise#4247 follow-on;getPolicy(), theactive()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
TypedPoliciesTest)runtime-e2e/typed_policiespolicyTypedPolicyRefusalException.getPolicy()AxonFlow.typedPolicyRefusaleveryRefusalIsTyped(every row assertsgetPolicy(); the outage row names none)catalog_digestTypedAuthoringEdition.getCatalogDigest()@JsonCreatoreditionVocabulary(present and absent)sha256:8eec9ebc…, asserted presentregistry_versiongetRegistryVersion()(Integer)2, asserted above 0catalog_fixturegetCatalogFixture()(Boolean)false, assertedtemplate_omissionsTypedPolicyPublication.getTemplateOmissions()publishCarriesTheOmissionReport;nullandomitted: nullinnullCollectionsReadAsEmptygetOmitted().size() == getOf() > 0template_omissions_unavailablegetTemplateOmissionsUnavailable()aPublicationWhoseOmissionReportIsUnavailableSaysWhytemplate_omissionsTypedPolicyActivation.getTemplateOmissions()activationCarriesTheOmissionReporttemplate_omissions_unavailablegetTemplateOmissionsUnavailable()anActivationWhoseOmissionReportIsUnavailableSaysWhynameTypedPolicySystemControl.getName()aControlNamesItselfAndIsNotMandatoryWhenUnsaidmandatoryboolean getMandatory()(wasBoolean)Boolean.TRUE.equals(...)nullboth readfalseactive()on404 nothing_activeOptional.empty()active(),typedReasonnothingActive;anotherActive404IsARefusal(a plain-text 404 and a 404 with another reason)404 nothing_active), in both legs#247, item by item
active()keyed onnothing_active, with getaxonflow/axonflow-enterprise#4255 in the javadoc, the README and the CHANGELOG. No departure or earlier-release sentence.unknown_constraintsentence, 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.mdandrun.sh.runtime-e2e/v11_examples/README.mdcited 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"]."runtime-e2e/v11_examplesextended from three runs to six, andruntime-e2e/typed_policiesasserting the members live. See Live legs.The route template (the brief's check): this SDK's route-deprecation record already keys on the route template (
withRoutetags each id-bearing request;noteRouteDeprecationkeys on the tag), with the two-id test and the census of the seven families. This change adds the exact served-request pin toeveryIdBearingMethodReportsItsTemplateOnce: 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 (updateDynamicPolicyandtoggleDynamicPolicy, bothPUT /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)publishCarriesTheOmissionReportandaPublicationWhoseOmissionReportIsUnavailableSaysWhyactivationCarriesTheOmissionReport(beside the record, not inside it) andanActivationWhoseOmissionReportIsUnavailableSaysWhyaControlNamesItselfAndIsNotMandatoryWhenUnsaid(absent andnullboth readfalse, compared by value)Changed:
nothingActivestubs the platform's reasonnothing_active; it stubbedno_active_policy, which is not the platform's reason and now reads as a refusal.aDerivedClientsIdentitystubbed/activewith a 404 whose body is{}; it now answersnothing_active. Both are the intended reading, not a regression.everyRefusalIsTyped: the tier row carriespolicy, every row assertsgetPolicy()(the outage row names none), and the table gains the active read's 503storage_unavailable(getaxonflow/axonflow-enterprise#4255) through a newactivecase in the table's call helper.nullCollectionsReadAsEmptygainstemplate_omissions: null(no report) andomitted: null(empty).V11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOncepins 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.lintscripts/verify-formatting-gate.sh,scripts/mutation-gate.sh,mvn com.spotify.fmt:fmt-maven-plugin:checkBuild 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)Lint — no mocks in runtime-e2e/scripts/lint-no-mocks-in-runtime-e2e.shRuntime E2E required for user-facing changessrc/main/java/andexamples/and, beside them,runtime-e2e/, which is the gate's conditiontyped_policiesdriver compiled withjavacagainsttarget/classesOne 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
javacagainst 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 runsmvn test -Dtest=Class#methodwith 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 at45c2ad4, the tree restored clean at the same head. The head,4fa4bd9, changes nothing insrc/since520859e(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 readstarget/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.anotherActive404IsARefusalno_active_policynothingActiveerrornothingActivepolicyeveryRefusalIsTypedTypedPolicyRefusalExceptionstores null forpolicyeveryRefusalIsTypedcatalog_digesteditionVocabularyregistry_versioneditionVocabularycatalog_fixtureeditionVocabularytemplate_omissionspublishCarriesTheOmissionReporttemplate_omissions_unavailableaPublicationWhoseOmissionReportIsUnavailableSaysWhytemplate_omissionsactivationCarriesTheOmissionReporttemplate_omissions_unavailableanActivationWhoseOmissionReportIsUnavailableSaysWhyomittedis kept as sent, sonullstays nullnullCollectionsReadAsEmptyofpublishCarriesTheOmissionReportmessagepublishCarriesTheOmissionReportnameaControlNamesItselfAndIsNotMandatoryWhenUnsaidmandatoryis unboxed from the sentBoolean, so absent ornullfailsaControlNamesItselfAndIsNotMandatoryWhenUnsaidV11DeprecationsTest.aStampedRouteWithAnIdIsReportedOnceNotOncePerIdgetStaticPolicyVersionsbuilds its request withoutwithRouteV11DeprecationsTest.everyConcatenatedStampedPathCarriesItsTemplate{id}/versionstemplate loses/versionsV11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOncetoggleDynamicPolicysendsPATCHV11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOncetoggleDynamicPolicysends a fixed id instead of its own (its template, and so the reported set, is unchanged: only the served-request pin sees it)V11DeprecationsTest.everyIdBearingMethodReportsItsTemplateOnceLive legs
Both legs ran at the head
4fa4bd9, each on its own fresh Community stack. The stacks were built from axonflow-enterprise857455033, with the agent and orchestrator on the application database role (the boot probe passed 3 of 3, with every pool onaxonflow_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's404 nothing_active.catalog_digest=sha256:8eec9ebc…,registry_version=2,catalog_fixture=false.system()returns 118 controls: 118 named, 25 mandatory.template omissions: 22 of 22, and the activation reports the same 22.Client/axonflow-api-credential/runtime-e2e, not the name in the request.409 activation_refused("refusing to promote version 1 over active version 1").422 publication_refused.ACTION_NOT_REGISTEREDfinding on validate, and422 document_refusedcarrying it on publish.runtime-e2e/v11_examples: PASS, 13 assertions, 0 failed, after thecurlprecondition read404 nothing_active(the leg first waits for/health). The examples were compiled from this tree's sources against this tree's build, andtyped-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:pep-handshake: exit 0. The first decide wasverdict=allow, and the declaration the platform would refuse failed in the client, at/pep_id, before anything was sent.typed-policieswithout publishing: exit 0,nothing is active.AXONFLOW_TYPED_POLICY_PUBLISH=1: exit 0. It printedtemplate omissions: 22 of 22 template controls: ...beforeactivated.refused: HTTP 422 document_refused: ....published sha256:193c2e3b... (version 1), thenactivation refused: HTTP 409 activation_refused: authoring: refusing to promote version 1 over active version 1; ..., exit 1.verdict=deny reasons=[unknown_constraint]. The stack is built from857455033, 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 showat the sha, because a mutation run and a local round were using the working tree), checked against the platform source (axonflow-enterprise at857455033, and main at8a1e2d312) 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 at45c2ad4. 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).runtime-e2e/v11_examples/run.shcompiled the examples withjavacand puttests/fixtureson the classpath itself, so the<resources>block inexamples/typed-policies/pom.xml, which the README'smvncommand 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 itstarget/classes, and puts that directory on the classpath.template omissions:line; it now requires a report,template omissions: N of M template controls:.javacexits 2 on a usage error, and the leg keeps exit 2 for its precondition; every build failure now exits 1.line_ofreturns 0 when nothing matches; it returns an empty string.Round 2, at
45c2ad4: SHIP-READY, with one low item, folded at4fa4bd9. 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/fixturesresolves against the example's own directory under-f. The low item: Maven skips a missing resource directory without an error, andtarget/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
TypedPolicySystemControlcontrolanddynamic. At axonflow-enterprise main, each system control also carriescontrol(always) anddynamic(omitted when false), from getaxonflow/axonflow-enterprise#4221, which landed after857455033, 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.shstill 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. Thev11_examplesleg 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) andBuild 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, andpackage, which is not required, was still running when this was written.