Governed Actions

PATCH /issues/123 can describe a technical mutation. It does not say why the issue should change, what policy applies, whether the requester has authority or what evidence was considered. A governed action starts from the business intent instead.

For example, a consumer can request a resolution for an issue. The request is not an instruction to set status = resolved. It is a proposal that the responsible capability evaluates.

Intent creates a decision point

An explicit action gives the system somewhere to apply meaning. It can check whether the issue is in a resolvable state, whether required remediation is complete, whether evidence is present, whether a policy hold applies and whether the actor is entitled to make the request. It can also re-read the state immediately before execution and detect a concurrent change.

This is not ceremony around a field update. It is how the system keeps the business process visible when the caller is no longer a single, known user interface.

The usual public shape is a noun-based action resource: a resolution request, approval request, credit-limit change request or access-revocation request. The wording matters because it makes clear that the consumer is proposing an outcome, not assuming the authority to impose it.

A structured no is part of the contract

Rejection is not an exceptional side effect. It is a normal outcome that a human or agent needs to understand. A useful rejection tells the caller what happened in a stable machine-readable form, whether trying again could help, and—where it is safe—what condition prevented the action.

An invalid state and insufficient authority are normally final for that request. Missing evidence may be recoverable. A concurrent change may require the consumer to re-read context before proposing again. Treating all of these as an opaque failure pushes the missing decision logic back to the caller.

Audit and events belong to the same decision

When a governed action succeeds, its audit record should capture who proposed it, under whose authority, which policy applied, what decision was reached and what state resulted. The event that refreshes downstream context follows the committed decision. That order preserves the distinction between a proposed change and an authoritative one.

The next question is how a consumer learns all of this before calling the action. That is the purpose of a capability contract .