Admin Approvals Example

A multi-step approval workflow with formal audit guarantees, self-approval prevention, and human-review-only safe edit zones.

The Problem

Enterprise systems frequently need multi-step approval workflows: deploying to production, changing user roles, modifying access policies, or deleting sensitive resources. These workflows have strict integrity requirements — no one should approve their own request, audit logs must be immutable, and certain steps must always require human review regardless of automation level.

In traditional codebases, these rules live in scattered middleware, service layers, and database triggers. An AI agent modifying the approval flow has no way to know which constraints are safety-critical versus which are merely conventional. SysMARA makes every constraint explicit, machine-readable, and compiler-enforced.

System Structure

Modules

identity — User accounts, roles, and authentication state
approvals — Approval requests, multi-step workflows, and escalation logic
audit — Immutable audit logging and compliance trail
resources — Protected resources that require approval for modification

Entities

Entity	Module	Description
`user`	identity	A system user with role, status (active/deactivated), and credentials
`approval_request`	approvals	A request for approval, containing the action, requester, and current status
`approval_step`	approvals	An individual step in a multi-step approval chain, with assignee and decision
`audit_log`	audit	An immutable record of an action taken in the system
`protected_resource`	resources	A resource that requires approval before modification or deletion

Capabilities

The system defines 14 capabilities across its four modules, covering the full lifecycle of approval requests, audit logging, and resource protection. Key capabilities include:

create_approval_request — Submit a new request for approval
assign_approval_step — Assign a specific approver to a step
approve_step — Record an approval decision on a step
reject_step — Record a rejection decision on a step
escalate_request — Escalate a timed-out request to a higher authority
create_audit_entry — Write an immutable audit log entry
get_audit_trail — Retrieve the full audit trail for an entity
lock_resource — Place a protection lock on a resource pending approval
unlock_resource — Release a protection lock after approval completes
deactivate_user — Deactivate a user account
change_user_role — Modify a user's role (requires approval)

Critical Invariants

All 8 invariants in this system are marked as critical. This is intentional — in an approval and audit system, every constraint is a security boundary.

Invariant	Description
`no_self_approval`	A user cannot approve a request they submitted. The requester and approver must be different users. This prevents privilege escalation through self-service approval.
`sequential_step_completion`	Approval steps must be completed in order. Step N cannot be approved or rejected until step N-1 has a final decision. This ensures the approval chain is followed as designed.
`auto_escalation_on_timeout`	If an approval step is not acted on within its configured timeout, the system must automatically escalate to the next level. No step can remain pending indefinitely.
`audit_log_immutable`	Once an audit log entry is created, it cannot be modified or deleted. No capability in the system may perform an update or delete operation on the audit_log entity.
`role_change_requires_approval`	Any change to a user's role must go through the approval workflow. Direct role modification without an approved request is prohibited.
`deactivated_user_cannot_approve`	A user whose status is "deactivated" cannot be assigned as an approver or act on any approval step.
`two_person_rule`	Sensitive operations (production deployments, role changes) require approval from at least two distinct individuals. A single approver is not sufficient.
`admin_deployment_requires_approval`	Even system administrators must submit deployment actions through the approval workflow. Admin privileges do not bypass the approval requirement for deployments.

The Approval Workflow Flow

The primary flow defines the lifecycle of an approval request:

create_approval_request — A user submits a request, specifying the target action and resource
lock_resource — The target resource is locked to prevent concurrent modifications
assign_approval_step — Approvers are assigned to each step in the chain
approve_step / reject_step — Each step is acted on sequentially
escalate_request — Triggered automatically if a step times out
create_audit_entry — Every decision is recorded in the audit log
unlock_resource — On final approval, the resource lock is released and the action proceeds

If any step results in rejection, the flow terminates, the resource is unlocked, and the rejection is logged.

Human-Review-Only Zones

The audit module uses human-review-only safe edit zones. This means:

AI agents can read and reference audit specs but cannot modify them
Any change to audit infrastructure — log format, retention policy, immutability enforcement — requires human review and manual application
The SysMARA compiler flags any change plan that touches audit specs as requiring human approval

This is critical for compliance. Audit infrastructure is the foundation of trust in the system. If an AI agent could silently modify audit log behavior, the entire compliance trail becomes unreliable.

# specs/audit/module.yaml
name: audit
safe_edit_zones:
  - zone: audit_infrastructure
    type: human-review-only
    description: "Audit log schema, retention, and immutability rules require human review"
    covers:
      - entities: [audit_log]
      - invariants: [audit_log_immutable]

Policy Priority Layering

The 8 policies create a layered access control system:

system_audit_write (priority: 100) — Only the system itself can write audit entries
admin_manage_users (priority: 95) — Admins can deactivate users and initiate role changes
approval_chain_authority (priority: 90) — Assigned approvers can act on their steps
resource_owner_request (priority: 80) — Resource owners can submit approval requests
manager_escalation (priority: 70) — Managers can escalate timed-out requests
audit_read_compliance (priority: 60) — Compliance officers can read full audit trails
user_view_own_requests (priority: 30) — Users can view their own approval requests
deny_deactivated_users (priority: 200) — Deny all actions for deactivated users (highest priority deny rule)

Note that deny_deactivated_users has the highest priority. This ensures that no other policy can override the restriction on deactivated accounts — a common pattern for deny-first security rules.

CLI Commands

Validate the system

npx sysmara validate

Explain the no_self_approval invariant

npx sysmara explain invariant approvals.no_self_approval

Shows which capabilities are constrained by this invariant and which entities are involved.

Check impact of adding a new approval step type

npx sysmara impact change-plans/add-parallel-approval.yaml

Would flag that sequential_step_completion needs to be revisited if parallel steps are introduced.

View the system graph for the approvals module

npx sysmara graph --module approvals

Outputs the dependency graph showing how approval_request, approval_step, and their invariants connect.

What This Example Demonstrates

All-critical invariant sets for security-sensitive domains
Human-review-only safe edit zones for audit infrastructure
Sequential workflow enforcement through formal flow definitions
Deny-first policy patterns with priority-based layering
Auto-escalation as a system-enforced invariant, not an optional feature