Verification

Master switch. When true (and a db is present) the verification service initialises and its record + flow routes register. Flows never auto-intercept entity writes — the entity record is never mutated; you start a flow explicitly (start / start-for-entity) and apply the outcome yourself when it completes.

Defaults to false — when the key is omitted a rejected flow terminates (the instance is set to status 'rejected' with completed_at, and does not restart). Set true (an explicit opt-in, as in the example above) to auto-restart the flow from step 1 on rejection, keeping a resubmission loop simple — the requester fixes the issue and the flow runs again from the top.

Reserved / not currently wired — a global default is NOT enforced. Signatures are required per-verifier via each verifier's require_signature setting in the flow graph, so set it there rather than expecting this flag to gate decisions.

Reserved / not-yet-implemented as a toggle — diffs are captured unconditionally whenever a `diff` is passed to the decide endpoint, independent of this flag. Leaving it on/off does not change diff behaviour today.

Routes for acting on verifications — list pending items, read status, approve and reject. This is what reviewer UIs talk to. Only basePath is honored — the route family reads config.endpoints?.basePath and mounts unconditionally when verification.enabled is true. The enabled field is NOT currently wired for this family (setting it false is a no-op); use the master verification.enabled switch to turn record routes off.

Routes for managing flow definitions — create and edit the step graphs that drive approvals. The entire group is godmin-only (flow definitions ARE the approval policy). Asymmetry to note: the SERVER mounts these routes unless flowEndpoints.enabled === false (default-on), but the CLIENT generator only emits the FLOW_* actions when flowEndpoints.enabled is explicitly truthy — so omitting the block entirely mounts the routes yet generates no FLOW_* actions. Set flowEndpoints.enabled: true explicitly (as in the example) to get both.

A flow stores three node kinds — step, verifier and notification — plus edges, verifier configs and notification rules/recipients/channels (seven tables in total). saveFlow replaces the whole graph in a single request — deleting the prior steps/edges/verifier configs/notification rows and re-inserting from the payload (not wrapped in a DB transaction); publishFlow flips is_draft off so only published flows can start.

startFlow creates one active instance per entity record (rejecting a second concurrent one), sets current_step_order = 1, then materialises requirements for step 1. Step order comes from the step nodes sorted by step_order.

For each verifier wired into the current step a pending requirement row is created. A role verifier with all_must_approve is expanded into one requirement per user holding that role (so everyone must sign off); otherwise it's a single requirement keyed by user or role.

decide matches the caller to a pending requirement of the current step — directly by user id, or by membership of the required role — then records the decision with an optional free-text reason (persisted as reason || null on the decision row — e.g. a rejection justification), an optional signature_id (when require_signature is set) and the captured before/after diff. When require_signature is set, signature_id must reference a file uploaded by the deciding verifier themselves (files.uploadedBy === user_id): an omitted signature_id is rejected first with 'Signature is required for this verification step', and only a bare or foreign file uuid that fails the ownership lookup is rejected with 'Signature file not found or not owned by the verifier'. all_must_approve aggregates every requirement before the step advances; a rejection ends or (with autoResetOnRejection) restarts the flow.

The engine fires five trigger types across the lifecycle: on_flow_started as the instance starts, on_step_reached as it reaches each step, on_approved / on_rejected on each decision, and on_flow_completed when the flow finishes. For each it fires the notification nodes wired to the relevant step (following edges one or two hops, through verifier nodes) — which is how an approval flow emails or notifies the right reviewers without you writing glue code.

Start a named flow against one entity record — the explicit entry point to the whole feature (writes are never auto-intercepted). Body: flow_id, entity_name, entity_id. Rejects a second concurrent instance for the same record.

Start whichever published flow is configured for that entity type without naming a flow_id — resolves the flow from the entity_name, then starts it exactly like VERIFICATION_START. Body: entity_name, entity_id.

Every record awaiting the current user's decision.

Where a specific record sits in its approval graph. Readable only by the flow's submitter or a godmin (it exposes the approval diff) — but the submitter check is skipped when the instance has a null started_by, so a service-initiated flow with no submitter is readable by any authenticated caller. Flows started via the HTTP API always record a started_by.

The record's full approval decision history — same VerificationStatusResponse shape as STATUS (the verifications list plus current_step / total_steps / is_completed / is_rejected counters). Scoped exactly like STATUS: readable only by the flow's submitter or a godmin, since it exposes each decision's before/after diff — and, exactly like STATUS, the submitter check is skipped when the instance has a null started_by (service-initiated flows), leaving it readable by any authenticated caller.

Operator/reconciliation view listing every record's verification status for an entity type — godmin-only (403 'Forbidden: operator privileges required' for ordinary callers), since each row exposes its approval diff. Query params: status (active | completed | rejected | cancelled), page, limit.

Approve or reject the current step, with an optional signature when required. Body: decision ('approved' | 'rejected'), an optional free-text reason recorded with the decision (e.g. a rejection justification, persisted as reason || null), an optional signature_id, and an optional before/after diff. When require_signature is set, signature_id must reference a file the deciding verifier uploaded themselves — another user's file (or a bare uuid) is rejected.

List the defined flow graphs — optional ?entity_name filter narrows to flows for one entity type. Returns the VerificationFlow rows. Part of the same godmin-only flow-management group.

Read one flow definition, returning { flow, graph } — the flow row plus its full step/verifier/notification graph (what the flow-builder loads to edit). Godmin-only, like the rest of the flow-management group.

Create or edit a flow graph, publish it live, or remove it — the building blocks of an admin flow editor. Together with FLOW_LIST / FLOW_GET these five FLOW_* actions form the whole flow-management group, which is godmin-only.