Record review decision

Record an explicit human approval or escalation against the exact current review version; it does not sign an agreement.

Access

Requires app_topolo_contracts.workspace:write and the intended authenticated organization and workspace. Select the permitted workspace through the supported resource-binding flow; do not add a workspace id to strict action input. Honor the action’s explicit confirmation requirement, including for a GET export. Any required JSON confirmation value is separate from transport/client confirmation.

Steps

1. Read the current review and its findings, captured policy and coverage.
2. Choose approve or escalate through an authorized human decision and send that exact expectedVersion.
3. Read the review and audit events again; the response supplies the advanced reviewVersion.

Identifiers

• Discover reviewId and version with reviews.list/reviews.get in the verified workspace. Never infer the current version from an old example.

Request

POST /api/reviews/{reviewId}/decisions

Action: app_topolo_contracts.decisions.record.

• reviewId: required, string, at least 1 characters, at most 160 characters.
• decision: required, one of approve, escalate.
• expectedVersion: required, integer.
• note: optional, string, at most 2000 characters.

Response and effects

• Uses a version-conditional update and an audit event in one guarded database batch. Escalation sets status escalated and its legal-review recommendation; approval sets status approved and its approval recommendation. The existing route is preserved for either decision.
• Approval refuses unresolved blocking findings, non-aligned pending findings or incomplete source coverage. Escalation itself does not resolve wording.
• A recorded approval is a workflow decision, not a signature, legal completeness guarantee, provider approval or automatic policy publication.
• The version advances even for an escalation; do not replay a decision after a lost response without readback.

Examples

Example request and response

Request input:

{
  "reviewId": "11111111-1111-4111-8111-111111111111",
  "decision": "escalate",
  "expectedVersion": 1,
  "note": "Documentation-only illustration: request human legal review."
}

Illustrated response:

{
  "decision": {
    "id": "22222222-2222-4222-8222-222222222222",
    "decision": "escalate",
    "recordedAt": "2026-10-21T00:00:00.000Z"
  },
  "reviewVersion": 2
}

HTTP 201 illustration. Hypothetical authorized operation only; inspect the action-specific fields and boundaries below.

Refusal or dependency failure

If: The review currently has version 2, while this request still supplies expectedVersion 1.

Request input:

{
  "reviewId": "11111111-1111-4111-8111-111111111111",
  "decision": "escalate",
  "expectedVersion": 1,
  "note": "Documentation-only illustration: request human legal review."
}

Source error-code excerpt (HTTP 409):

{
  "error": "review_version_conflict"
}

Read the review again and re-plan at its current version.

Refusal or dependency failure

If: No review row for this reviewId is visible in the already authorized organization and workspace.

Request input:

{
  "reviewId": "11111111-1111-4111-8111-111111111111",
  "decision": "escalate",
  "expectedVersion": 1,
  "note": "Documentation-only illustration: request human legal review."
}

Source error-code excerpt (HTTP 404):

{
  "error": "review_not_found"
}

Discover a review in the selected workspace; do not switch organization to chase a guessed id.

Stale-state recovery

If: The review currently has version 2, while this request still supplies expectedVersion 1. For this recovery illustration, the earlier intended write already advanced it to version 2; do not resend the stale write.

Request input:

{
  "reviewId": "11111111-1111-4111-8111-111111111111",
  "decision": "escalate",
  "expectedVersion": 1,
  "note": "Documentation-only illustration: request human legal review."
}

Source error-code excerpt (HTTP 409):

{
  "error": "review_version_conflict"
}

Reconcile current scoped records before another write; this error does not prove earlier effects were absent.

Verify the result

• Confirm the review version advanced and its status/recommendation match the approved decision, while route remains equal to the pre-decision value. Verify the corresponding audit event in the same workspace.

Recovery

• 409 review_version_conflict: Read the review again and re-plan at its current version.
• 409 mandatory_escalation_required: Resolve the blocking clause or explicitly escalate; do not retry approval unchanged.
• 409 review_coverage_incomplete: Investigate missing clauses or unverified quotes before asking for approval.
• 404 review_not_found: Discover a review in the selected workspace; do not switch organization to chase a guessed id.
• 401 authentication_required: Outer authentication/authorization contract: Authenticate again with an entitled Contracts credential. Reconcile uncertain earlier write effects before any retry.
• 403 permission_denied: Outer authentication/authorization contract: Grant workspace:write without changing the organization context. Reconcile uncertain earlier write effects before any retry.
• 429 rate_limited: Outer authentication/authorization contract: Wait for Retry-After when present, then retry without parallel duplicate calls. Reconcile uncertain earlier write effects before any retry.

The decision is auditable and has no automatic undo. Reconcile a lost response via review and audit reads; an already approved review refuses further decisions. Escalation is not cleared merely by resolving a finding.

Source and example limits — 21 October 2026: based on reviewed Contracts source 4bfd49a; current serving association is unverified. All requests, responses, approvals and document specimens shown are fictional and unrun. Offline schema/ZIP/XML checks do not prove application acceptance, legal completeness, provider outcomes or human approval.