Skip to main content

Typed Policy Authoring (Preview)

:::info Enterprise, preview, off by default

The typed policy editor is an Enterprise surface, is off for every organization until a platform operator turns it on, and is a preview: documents and published versions live in the portal process and do not survive a restart. The Policies page described in Managing Policies is unchanged and remains the enforced authoring surface.

:::

The typed editor is a different way to write policy from the Policies list. Instead of rows with conditions and actions, you author one versioned document for your organization, the platform validates it against the actions your deployment actually registers, compiles it, tests it against cases you declare, signs it, and only then can somebody else make it live.

Grants and ceilings​

The editor works with four kinds of policy. Two of them have friendly names, and two deliberately do not.

KindCalledWhat it does
PermissionGrantAllows an action when it matches. Grants compose by union, so a grant can only ever widen what is allowed.
ConstraintCeilingDenies or narrows an action that something else allowed. A matched ceiling overrides every grant, so a ceiling can only ever narrow.
RequirementRequirementAttaches a mandatory obligation, such as an approval or a quota reservation.
InspectionInspectionSelects content controls. It can never grant: a detector can only report that nothing looked wrong, which is a different claim from "this request is legitimate".

Grants and ceilings are separate sections with separate buttons and separate forms, and the forms use opposite words on the same controls: a grant says Allow when, a ceiling says Deny when. That is not decoration. On your organization's own document the two carry the same fields, and their effects are opposite, so an interface that told them apart by one dropdown value would hide the most consequential fact about a policy.

Two consequences worth knowing before you start:

  • A grant cannot deny, and a ceiling cannot attach an obligation. If you need an approval or an audit record, that is a Requirement, not a ceiling with an extra field. The editor refuses the combination by not offering it.
  • Your ceilings cannot be broken by break-glass. Break-glass is declared by whoever owns the constraint, and an organization document cannot declare it. A ceiling you write is unbreakable by construction; if you need an exception, write one into the ceiling's Except when clause, where it is visible and versioned.

Turning it on​

The flag is per organization and is a platform-operator setting. A tenant cannot enable it for itself.

An operator with the admin API key runs:

curl -X PUT "https://<portal-host>/api/v1/admin/organizations/<org-id>/identity-settings" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"typed_authoring_enabled": true}'

The response echoes the stored row, including typed_authoring_enabled. Turning it off again is the same call with false, and the surface closes on the next request rather than at the next portal restart.

Two things have to be true on the deployment before the editor is usable:

RequirementWhat happens without it
Enterprise migration 154 appliedThe write is refused with 409 naming the migration, rather than answering 200 without storing anything.
AXONFLOW_TYPED_AUTHORING_CATALOG set to a recognised valueThe editor loads and every action that needs the policy vocabulary answers 503 naming the variable. It does not fall back to an empty vocabulary, because that would refuse every policy you write for naming an action that "is not registered" - a deployment problem rendered as your typo.

The one recognised catalog value today is conformance, the ADR-065 evaluation vocabulary. An unrecognised value registers no editor routes at all and says so in the portal log.

Writing and publishing a document​

Once the flag is on, a Policy Authoring entry appears under Governance and the editor lives on its own page. The Policies page carries a short card pointing to it and is otherwise unchanged - it remains the surface your deployment enforces until the typed model replaces it.

  1. Add grants and ceilings. Each one needs an identifier, the principals it applies to (your whole organization, or named groups), the registered actions it reaches, and its condition. Only actions your deployment has registered can be named, and a group is chosen from the realms your deployment declares rather than typed - a realm that is not declared is refused, so it is not something to have to remember.
  2. Validate. The platform checks the document against twenty-seven declared rules and returns every finding at once, in the order you should read them, each with a code, a plain-language summary and the specific value that caused it. Rejections block; warnings describe a policy that is well formed and can never match.
  3. Compare with live. A diff against the version currently in force, before you commit to anything.
  4. Publish. This is one operation that does five things in order: validate, compile, run the publication gates against the bundle it just compiled, sign, and admit. It needs two things from you:
    • an approver who is not you, because activation requires separation of author and approver duties; and
    • at least one test case, because a document nobody tested has not been shown to do anything. The dialog opens a builder with one row per attribute your policies read; you supply the value and say what each policy should return for it (MATCH, NO_MATCH or UNKNOWN). Every verdict starts at not asserted on purpose - a pre-filled one would be the tool asserting the behaviour on your behalf, and with placeholder values it would pass and prove nothing. The provenance, version and timestamp of each attribute are not asked for: they are decided by the attribute's namespace and the platform refuses any other answer. An Edit as JSON view is one click away for anything the builder does not express.
  5. Promote. Publishing does not put anything in force. A published version becomes live when an approver of that version promotes it, and the author of a version cannot be the one who promotes it. That refusal is not a configuration you can turn off; on a version you published, the promote and roll-back controls are shown disabled with the reason rather than failing after the click.
  6. Roll back. A rollback returns to a digest that was activated before, so the thing you return to has already been through the whole pipeline once. It records a reason, because an unexplained reversal of policy is what an audit trail exists to prevent.

What "rendered back without loss" means​

Every published version has a Source view showing the exact bytes that were signed. Those bytes parse back into the document you wrote, re-render identically, and recompile to the module being enforced - all three were proven before the signature and are proven again every time the version is loaded.

That matters for a reason worth stating plainly: an operator reading policy source in a portal has no other way to know that what they are reading is what is being enforced.

Limits of the preview​

LimitDetail
Nothing persistsDocuments and published versions are held in the portal process. A restart or a redeploy loses them.
One authority rootThe editor writes your organization's document. Platform-wide constraints belong to the platform and cannot be authored here.
Requirements and inspections are read-onlyThe editor lists them and keeps them through publication unchanged, but authoring an obligation is not part of this preview.
Not the enforced surfaceThe Policies list remains what your deployment enforces. The typed document is compiled and signed, and this preview does not switch enforcement onto it.
Existing policies are not convertedNothing imports the policies you already have into a typed document, so the two surfaces describe different rules until you re-author them. The editor says so, and the Policies list is the one that enforces.
Last updated on