Workflows & human approval

What can execute today

Reusable workflows support only case.assign, case.set_priority and case.add_note. Definitions have 1–20 typed steps. Assignee is nonempty and at most 128 UTF-8 bytes; notes are nonempty and at most 4096 bytes; priority is low, medium, high or critical. No scripts, network URLs, external tickets or cloud containment. This is real local case management, not a simulated cloud action.

Create a bounded workflow

POST /api/v1/workflows using a cookie session and the same-origin/CSRF/JSON protocol. Review the returned workflow id/version before preview.

{
  "name": "Escalate for review",
  "definition": {"steps": [
    {"action": "case.set_priority", "parameters": {"priority": "high"}},
    {"action": "case.add_note", "parameters": {"note": "Human review requested"}}
  ]}
}

Preview has no case effects

POST /api/v1/workflows/{id}/preview with {case_id:...} creates a persisted plan, not an action on the case. The response includes plan_id/id, digest, steps, case_version, workflow_version, policy_version, expires_at and status:awaiting_approval. Plans expire after ten minutes. The digest binds the exact preview; do not reconstruct or guess it.

Human approval is a separate decision

An authenticated human operator checks the evidence, intended effects, current case revision and expiry before POST /api/v1/actions/{id}/approve with digest and expected_version (the preview case_version). The server rechecks case/workflow/policy versions, authority, expiry and state inside the transaction. Missing/stale revision or mismatched digest fails with 409; preview again after reviewing changes. POST /actions/{id}/reject requires digest and operator role.

No blind retry on timeout

GET /api/v1/actions lists persisted plans and receipts; locate the plan by id. There is no GET /actions/{id}. Repeated identical approval does not execute twice; an opposite decision conflicts. A verified receipt records committed outcome, actor, digest and resulting case revision. After timeout, reconcile the persisted action before resubmitting; outcome_unknown means uncertainty, not success or permission to create another plan. Inference/model output cannot approve.

Case editing is versioned too

PATCH /api/v1/cases/{id} requires expected_version. Allowed fields are title, status, assignee, priority and note. open↔investigating, open/investigating→closed and closed→open are supported; closed→investigating is not. Missing/stale versions return 409. Read again and review concurrent work; never overwrite by inventing a version.