Evaluation

Note

Specification: accepted. Implemented in part in the source build. Remaining requirements and external validation are not complete.

Version: shiin.evaluation/v1-draft.1.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

The engine evaluates an action request against a policy snapshot and produces a decision. The engine performs no I/O and is deterministic: the same inputs always produce the same decision (ADR-0009, ADR-0010).

The identity stage currently returns pass; the capability gate requires explicit action/effect-class grants, and Unix approval grants are evaluated by the daemon path in source. Policy, task constraints, risk escalation, unattended denials, and five-stage traces exist in source. Host and cross-platform validation remain open.

Stages

[EVAL-001] The engine MUST run exactly five stages in this fixed order: identity, capability, policy, intent, and risk (ADR-0012).

[EVAL-002] Each stage returns one of allow, deny, pending, or pass.

[EVAL-003] A stage that returns allow is a policy stage; only the policy stage may produce allow.

[EVAL-004] The identity, capability, intent, and risk stages are gates: they may return deny, pending, or pass, but never allow.

Inputs

[EVAL-014] The engine’s inputs MUST be exactly the action request, the policy snapshot, the active task declaration if one exists, the evaluation mode, and the current time.

[EVAL-015] The engine MUST NOT read any other input, so that the same inputs always produce the same decision (ADR-0010).

[EVAL-016] The evaluation mode MUST be either attended, meaning an approver can be reached, or unattended, meaning none can.

[EVAL-017] In unattended mode, a decision that would be pending MUST instead be deny with reason code deny.unattended.

Combining

[EVAL-005] If any stage returns deny, the decision is deny (ADR-0011).

[EVAL-006] Otherwise, if any stage returns pending, the decision is pending, unless a matching grant already covers the action.

[EVAL-007] Otherwise, if the policy stage allows the action, the decision is allow.

[EVAL-008] Otherwise, the decision is the default decision, which is deny.

Fail-closed

[EVAL-009] Any failure inside evaluation MUST produce deny with reason code deny.failure (ADR-0013).

Trace

[EVAL-010] In explain mode, the engine MUST return a trace recording each stage’s result.

[EVAL-011] A trace MUST include the stage name, the result, and the reason code or rule id that produced it.

Policy snapshot

[EVAL-012] The engine MUST evaluate against a single immutable policy snapshot identified by a digest.

[EVAL-013] The snapshot digest MUST be recorded in the action request and the audit event.

Examples

{
  "schema": "shiin.evaluation/v1-draft.1",
  "request_id": "0190f3a0-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
  "decision": "allow",
  "reason": "allow.policy",
  "trace": [
    { "stage": "identity", "result": "pass", "reason": "identity.asserted" },
    { "stage": "capability", "result": "pass", "reason": "capability.fs_write" },
    { "stage": "policy", "result": "allow", "reason": "rule:edit-source" },
    { "stage": "intent", "result": "pass", "reason": "intent.no_task" },
    { "stage": "risk", "result": "pass", "reason": "risk.none" }
  ]
}

Revision history

• Accepted on 2026-10-12. Accepted: the ADR-0014 spike implements this pipeline and reproduces all 8 test vectors.
• v1-draft.2 (2026-10-12): Stated the engine’s inputs, and defined attended and unattended evaluation modes (EVAL-014 to EVAL-017).
• v1-draft.1 (2026-10-01): Initial draft.