# Approval Engine Foundation

## Purpose

The Approval Engine is a separate governance domain. It does not replace authentication,
RBAC, scope checks, or business rules.

The intended execution flow is:

Authentication
-> Permission
-> Scope
-> Business Rule
-> Approval Engine
-> Domain Action
-> Audit

## Data model

### `approvals.policies`
Defines:
- tenant ownership
- action code
- tenant/company/branch scope
- optional JSONB conditions for future business-rule compilation
- approval quorum
- self-approval rule
- expiry window
- lifecycle status

### `approvals.requests`
Captures:
- immutable requested action identity
- subject reference
- request payload snapshot
- requester
- organization scope
- pending/final state
- expiry

### `approvals.decisions`
Append-only decision records:
- approver
- approve/reject
- comment
- timestamp

One user may decide a given request only once.

## Decision semantics

- default state: `pending`
- any `reject` finalizes request as `rejected`
- approvals accumulate until `required_approvals` is reached
- reaching quorum finalizes request as `approved`
- expired requests cannot be decided
- self approval is rejected unless explicitly allowed by policy

## API

- `GET /api/v1/approvals/requests`
- `POST /api/v1/approvals/requests`
- `POST /api/v1/approvals/requests/{id}/decisions`

## Permissions

- `approvals.view`
- `approvals.request`
- `approvals.decide`
- `approvals.manage`

Policy administration API is intentionally deferred; `approvals.manage` is reserved for it.

## Important boundary: manager PIN

Manager PIN / supervisor PIN is not the Approval Engine.
It is a separate fast in-person authorization mechanism that can later satisfy specific
business rules where configured. It must be independently authenticated and audited.

## Next integration

Future domains will call the Approval Engine only after normal permission/scope/business-rule
evaluation says approval is required. Approval is therefore an additional gate, never a
replacement for permission.