How We Made Every AI Edit to a CV Undoable

Every mutating tool (create_skills, update_experiences, delete_certificates and the rest) appends to a plain journal table:

chat_checkpoints
  chat_id      → chats.id          ON DELETE CASCADE
  message_id   → chat_messages.id  the user message that caused it
  seq          int     monotonic per message_id
  tool_name    text
  entity_type  enum    profile | skill | experience | user_language
                       | education | certificate | cv_project | cv_extra
  operation    enum    create | update | delete
  entity_ids   jsonb   ids touched
  payload      jsonb   create → {}
                       update → {"before": [...], "after": [...]}
                       delete → {"rows": [full row snapshots]}
  created_at   timestamptz

The payload holds exactly what the inverse needs. A create needs only the new ids, because undoing it is a delete. An update stores the rows as they were before (and after, for auditing). A delete stores the full row, because the only way back from a delete is an insert. entity_ids is JSONB rather than int[] so a future UUID-keyed table can join the journal without a migration.

Tools don't insert journal rows themselves; they call a small writer. Here is the delete path for skills, lightly trimmed:

async def _exec_delete_skills(ctx, payload):
    ids = payload.normalized_ids()
    rows = await fetch_user_skills(ctx.db, ctx.user.id, ids)
    snapshots = [snapshot_skill(r) for r in rows]  # before the delete
    for r in rows:
        await ctx.db.delete(r)
    await ctx.db.flush()
    ctx.writer.record_delete(
        tool_name="delete_skills",
        entity_type=CheckpointEntityType.skill,
        rows=snapshots,
    )
    return {"deleted_skill_ids": [s["id"] for s in snapshots]}

Snapshots are explicit per-table field lists serialized to JSON-safe values: datetimes become UTC ISO strings, enums become their values. On the way back, a small decoder looks up each column's Python type and turns ISO strings back into date, datetime or time.

The edit endpoint does the whole rewind in a single database transaction:

async with session_factory() as db:          # one transaction
    if payload.rollback_state:
        # every inverse, newest first, then delete the replayed rows
        await apply_restore(db, chat_id=chat.id,
                            target_message_id=message_id)
    else:
        # text-only edit: drop the journal for the vanishing messages
        await checkpoints.delete_after(db, chat.id, message_id)
    await messages.delete_after(db, chat.id, message_id)
    await messages.replace_content(db, message_id, payload.content)
    chat.agent_state = None                   # the agent's half-done draft
    run = await runs.create(db, chat_id=chat.id,
                            user_message_id=message_id)
    await db.commit()

If any inverse fails (a constraint, a decoding error, anything), the exception escapes before commit(), the session rolls back, and the CV, the journal and the conversation are exactly as they were. The user sees an error, not a CV that is half old and half new. Before any of this, the endpoint answers 409 agent_busy if a turn is running and takes the chat lock, so the agent can't write into a CV while it is being rewound.

A text-only edit deletes the journal entries without replaying them. Their messages are about to disappear, and a later rollback must never try to undo writes from a conversation that no longer exists. Either way, the edited message then starts a fresh agent run, streamed over the same SSE channel as any other message.

A checkpoint is only useful if it exists exactly when its write does. A write without a journal row can't be undone; a journal row without its write would “undo” something that never happened. So both go through one unit of work per tool call:

@asynccontextmanager
async def tool_context():
    async with session_factory() as db:
        user = await users.get(db, principal_id)
        writer = CheckpointWriter(chat_id=chat_id, message_id=message_id)
        try:
            yield ToolContext(db=db, user=user, writer=writer)
        except Exception:
            await db.rollback()     # the write and its journal row vanish
            raise
        else:
            await writer.flush(db)  # journal rows, same transaction
            await db.commit()

This boundary has moved once, and the move is a real trade-off. The first version of the agent ran all of a turn's writes in one transaction: a separate worker model executed the edits, then either called final_response (commit and flush the journal) or report_blocker (roll back and discard it). All or nothing per turn. That was neat until the agent became a single loop that can take up to 25 model round-trips in one turn, and a transaction held open across all of them would sit idle, holding locks, for minutes.

So today each tool call is its own transaction. The code comment states the cost plainly: a turn that dies halfway keeps the writes it already committed. For a CV builder that's the right trade. Half an entry saved beats nothing, and the journal still undoes the whole message, because every one of those per-call commits carries its checkpoint rows under the same message_id.