docs(examples): v11 examples and the platform notes [skip-runtime-e2e]

[saurabhjain1592]

Summary

The documentation and examples step of the v11 SDK train for the Python SDK, under the same rulings as the Go and TypeScript SDKs'. It adds two runnable examples for the v11 surfaces, says in the README what each surface needs from the platform, corrects the handshake's documentation where it called an absent declaration neutral, and removes two overview lines that a v11.0.0 platform, or this SDK, cannot honour. It changes no code (its one axonflow/ edit is a module docstring) and bumps no version.

Changes

• examples/typed_policies.py reads what the deployment may author, validates a typed document and prints every finding, and shows the document in force. It publishes and activates only when AXONFLOW_TYPED_POLICY_PUBLISH=1, since that changes the organization's active policy, and reports a TypedPolicyRefusal with its status, reason and findings.

• examples/pep_handshake.py declares an enforcement point's capabilities for the client, overrides them for one call, and prints each verdict with the platform's reasons. It also shows a declaration the platform would refuse failing at construction with PEPHandshakeError, before anything is sent.

• Both exit non-zero when a step fails. The integration workflow's examples job compiles and imports them, beside the four examples it already checks.

• examples/pep_handshake.py's docstring says: 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 typed policy example activates such a document when asked to publish.

• The README gains a "v11.0.0 platform" section naming what each surface needs from the platform. These minimums were measured against the platform's own tags, not assumed:

  • decision provenance, the frozen legacy policy writes, the route deprecation stamps and typed policy authoring need v11.0.0; none of them is in v10.4.0;
  • the PEP capability handshake is read from v10.4.0. What v11.0.0 changes is the cost of not sending one: an organization's redact override on decide refuses a caller that does not declare redaction.

  The handshake chapter's first sentence now says v10.4.0 accordingly.

• The handshake's documentation stops calling an absent declaration neutral. The README's "There is no default" and "What a declaration changes" bullets, the module docstring in axonflow/pep_handshake.py and the handshake's CHANGELOG entry each said, or implied, that a client sending no declaration meets the platform as before. From v11.0.0, in every edition, decide under an organization's redact override refuses a caller that does not declare redaction, and they now say so.

• The README's feature overview no longer shows list_policies(), which this SDK does not have, or create_dynamic_policy, a write a v11.0.0 platform refuses with 409 LEGACY_POLICY_WRITE_FROZEN. It shows typed authoring in their place.

• examples/indonesia_compliance.py keeps its list_static_policies read, which still answers on a v11.0.0 platform, and says that the platform deprecates the route and removes it in v11.1, that the client reports it once through PlatformRouteDeprecationWarning, and names its successor.

• The CHANGELOG states under [Unreleased], with no version number, that the first release carrying these entries is the first to send the handshake and reach /api/v1/typed-policies, and why to upgrade the SDK before the platform: from v11.0.0, decide refuses a client that does not declare redaction wherever the organization has a redact override. It also adds an entry for the examples.

Follow-up: the reference to the platform's retired per-policy override error is a one-line change after getaxonflow/axonflow-enterprise#4221 merges.

Testing

• Live, on a community stack: both examples, run with this tree's SDK against the platform at 857455033 in community mode on the application database role. The agent image was sha256:131037e9998ecb88b798b419c9100195a0a0fdab41c5099e68399b9cec7a9a25 and the orchestrator image sha256:d3f67781672cfec08565ec114490000f414330f03d08704da4cd951fb44265dc. Every step of every run printed ok, and each run exited 0:
  • typed_policies.py with the runtime-e2e client, reading only: root=organization max_documents=20 persistence=database, success=True on validate, and nothing is active on the fresh stack;
  • typed_policies.py with the runtime-e2e client and AXONFLOW_TYPED_POLICY_PUBLISH=1: published sha256:8286448a7df581af60c53cba4254bd1c9119104b513b11a6f648746ceb1fab19 (version 1), activated, then 1378 signed characters; document_id=org-baseline;
  • pep_handshake.py, with no credentials (its community default): verdict=allow obligations=0 reasons=[] with the client's declaration, verdict=allow obligations=0 reasons=[] with a per-call one, and 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.
• The local round: every step of every pull-request workflow that runs without a stack: ruff check and format, mypy, the falsey-clobber lint against its baseline, the AuthZEN regeneration check, the no-mocks lint, version alignment, the wire-shape contract, the contract tests, the examples' compile and import checks (the new two included), the full suite (1601 passed, 30 skipped, 85.56% coverage), the build and twine check. After the round, the tree changes exactly this PR's 7 files.
• No mutants: D5 changes no code; its one axonflow/ edit is a docstring.

Skip-runtime-e2e justification

examples/ and axonflow/ count as user-facing, and this PR adds no runtime-e2e/ leg because the change is two runnable programs and a docstring. Both programs were run against a real stack, as recorded under Testing. The SDK surfaces they call are proved by the runtime legs of the handshake (#252) and typed policy (#255) PRs.

Integration tests are unchanged in what they run against. The integration job runs against the community mirror's main, which is the v10 platform until the v11.0.0 tag, so this PR's runtime proof is the local stack above.