Make Approval a Durable State, Not a Button

In this chapter

• Model review as an explicit state transition.
• Bind approval to the content the reviewer actually saw.
• Preserve workflow facts across a process restart.

A click is not sufficient evidence

A draft moves through states such as draft, approved, submitting and submitted. Each transition has a responsible actor and permitted precondition. A browser checkbox is not a durable fact: a page can be modified, an old tab can send stale data and a process can restart. Relay Room stores the draft revision and review state on the server. Submission refers to that exact revision, not whatever text happens to be latest.

Approval also has a meaning. The reviewer approves a particular room, category and summary, plus the intended operation. If any of those change, the prior approval no longer covers the new action. A content digest helps bind the record, but a digest alone proves neither who approved it nor whether they were authorized. Record a trusted reviewer identifier and timestamp in a real service, and enforce reviewer permission when the transition is requested.

Persist the transition and its precondition

This local SQLite example writes inside a temporary directory and reopens the database to demonstrate persistence. The approval update checks the expected version. Editing the summary increments that version and removes the approval digest. The final assertion establishes that an old revision cannot be approved after the edit. Run the entire snippet together.

import hashlib
import json
import sqlite3
import tempfile
from contextlib import closing
from pathlib import Path

def digest(body):
    return hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()

with tempfile.TemporaryDirectory() as folder:
    path = Path(folder) / "review.db"
    with closing(sqlite3.connect(path)) as db, db:
        db.execute("CREATE TABLE drafts (id TEXT PRIMARY KEY, version INTEGER, body TEXT, status TEXT, approval TEXT)")
        body = {"room": "Cedar 204", "summary": "Replace missing cable"}
        db.execute("INSERT INTO drafts VALUES (?, ?, ?, ?, ?)", ("d1", 1, json.dumps(body), "draft", None))
    with closing(sqlite3.connect(path)) as db, db:
        changed = db.execute("UPDATE drafts SET status='approved', approval=? WHERE id=? AND version=? AND status='draft'", (digest(body), "d1", 1)).rowcount
        assert changed == 1
        revised = {**body, "summary": "Inspect connector before replacement"}
        db.execute("UPDATE drafts SET body=?, version=version+1, status='draft', approval=NULL WHERE id=? AND version=?", (json.dumps(revised), "d1", 1))
        stale = db.execute("UPDATE drafts SET status='approved' WHERE id=? AND version=?", ("d1", 1)).rowcount
        assert stale == 0
        assert db.execute("SELECT version, status, approval FROM drafts").fetchone() == (2, "draft", None)
print("Persistence and stale-review checks passed")

Distinguish durable review from remote completion

The failure mode is recording submitted before the ticket provider has confirmed anything. Another failure occurs when a provider succeeds but the local database update fails. Do not claim one transaction magically covers two independent systems. Use a stable operation identifier, a persisted attempt record and a reconciliation path for unknown outcomes. A transactional outbox can reliably record work that still needs delivery, but the receiving side must also handle duplicates.

The example demonstrates local review persistence and optimistic version checking, not a complete distributed workflow. Production implementation must add authorization, immutable audit events, expiry policy, atomic transition rules and an idempotent worker. When a stale transition affects zero rows, return a conflict and reload the current draft for the reviewer. Silently accepting it would approve content they may never have seen.

Test the review revision boundary

• Add a second edit and confirm both earlier revision numbers fail the conditional update.
• Reopen the database before checking the final state to ensure the result was committed.
• Write a transition table covering draft, approved, submitting, submitted and delivery-unknown.

Expected checks

• Every content edit removes the prior approval.
• An old revision changes zero rows.
• Delivery-unknown is not displayed as successful submission.

Check your understanding

A user edits a room number after approving a draft. What should happen?

• Keep the existing approval because the change is small.
• Automatically approve the new version if the model considers it harmless.
• Invalidate the approval and require review of the new revision.

Official tools & further reading

• Python SQLite transactions and parameterized queries