Rate a session result
A governed action produces two different kinds of result. The SDK returns a typed result at the moment the action finishes. A session rating is feedback a person adds later, in the portal, once there is enough evidence to judge how the result performed.
Developers handle the typed result in code. Portal ratings are available to any user whose role can rate the session.
Read the typed result in code
Every core SDK returns the same set of statuses. The names below are the wire values; each language exposes them through its own enum or constant.
| Status | Released value | Meaning |
|---|---|---|
completed | Yes | Policy allowed the input and the output. |
completed_with_warning | Yes | Policy allowed the action and attached a warning. Surface the message to the user. |
transformed | Yes | Policy replaced the input or the output. The result also carries the effective input. |
blocked | No | Policy stopped the input or the output. The portal shows this as Stopped by policy. |
review_required | No | Policy asked for human review. The result carries a checkpoint to save. |
cancelled_by_directive | No | A Stop directive ended the run. |
cancelled_by_caller | No | The application cancelled the run. |
timed_out | No | The run exceeded the SDK’s operation timeout. |
failed | No | The SDK, the runtime, or the protected action failed closed. |
Each result also carries a safe message, an evidenceReference, and, when a rule decided the outcome, the policyAction and reasonCode. Results without a value carry an execution state: not_started, completion_unknown, or result_withheld. Reconcile completion_unknown before retrying an external side effect.
Never release a value from a blocked result. Use the status, message, reason code, and evidence reference to handle a result without a value. The language guides show the exact property names: TypeScript, Python, .NET, Java, Go, and Rust.
When VeriProof pauses changes
During an incident, VeriProof can pause writes across the platform. Every core SDK handles the pause the same way.
- Decisions still fail closed. If VeriProof can’t record the start or policy check, the result is
failedwith reason codeplatform_write_freezeandnot_started, and the protected action doesn’t run. If it can’t record the release decision after the action ran, the result isfailed,platform_write_freeze, andresult_withheld. The message says when to try again. Other outages keep their usual result, so you can tell a pause from an outage. - Evidence waits instead of disappearing. Records of what already happened, such as a failed, timed-out, cancelled, or withheld run, stay in a bounded in-memory queue and are sent again after the
Retry-Aftertime until VeriProof accepts them. Resends use the original request, so VeriProof never records the same run twice. In Edge mode, terminal evidence uses the same queue. - The queue is bounded. It holds 256 items by default (the evidence buffer capacity option). When it is full, the oldest item is dropped and counted. Diagnostics report how many items are queued, how many were dropped, and the last error code. Queued evidence never authorizes an action.
- Shut down cleanly. Shutting down the client tries every queued item once and reports how many could not be sent. Flushing sends the queue now and tells you whether anything is left.
Keep undelivered evidence across a restart
The queue lives in memory, and the SDK never writes evidence to disk. If your process may stop while a pause is still in effect, give the client an undelivered-evidence handler. At shutdown, after the last send attempt, the SDK passes the handler every item it still holds, oldest first. Each item is an opaque JSON text that carries the original request. Store the items wherever you keep evidence, then pass them back to the restore method when the process starts again. The client checks every item, rejects the whole batch if any item is invalid, and sends the rest through the normal queue. Because it sends the original bytes, VeriProof records each run once even if an item was already accepted.
The envelope contains evidence payloads; store it with the same protection as the evidence itself.
| SDK | Handler option | Restore method |
|---|---|---|
| TypeScript | onUndeliveredEvidence | restoreUndeliveredEvidence(items) |
| Python | on_undelivered_evidence | await restore_undelivered_evidence(items) |
| .NET | OnUndeliveredEvidence | RestoreUndeliveredEvidence(items) |
| Java | onUndeliveredEvidence(handler) | restoreUndeliveredEvidence(items) |
| Go | OnUndeliveredEvidence | RestoreUndeliveredEvidence(items) |
| Rust | on_undelivered_evidence | restore_undelivered_evidence(&items) |
When the handler returns normally, shutdown no longer reports those items as undelivered. If it fails, or you don’t set one, shutdown reports the count as before.
Retry the refused action after the pause ends. Diagnostics show platform_write_freeze as the last error code while it lasts. The API reference describes the 503 response.
Rate the session in the portal
Open Sessions, select the session, and use Session Rating in the session detail view.
| Rating | Use when |
|---|---|
| Good | The result met expectations |
| Acceptable | The result met the agreed minimum criteria |
| Bad | The result did not meet expectations |
| Unknown | There is not enough evidence to rate the result |
Select Note to record why you chose the rating, such as a false positive, an accepted exception, or a follow-up action. Saving a rating again replaces the earlier rating and note.
The SDKs do not send ratings. A rating is portal feedback attached to the recorded session after the fact. In sandbox mode the control is read-only and nothing is saved.
Human Review outcomes are different
This page is about a quality rating for a completed or observed session. A Human Review outcome determines what an application may do with a paused, protected action. That flow uses a signed callback, a durable receipt, and a separate application execution acknowledgment. The application owns its checkpoint, worker, and any resumed or revised work.
Use the Human Review callback reference for its outcome names, directives, resume modes, typed responses, cancellation, expiry, replay, and acknowledgment rules.
Review session ratings
Open Sessions, filter by rating when needed, and select a session to review its rating and note. Treat the rating as observed feedback, not as a replacement for the session’s recorded decision or typed result.