From bfa1c2172376a00a4d0440d83547d5249e6db4fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aur=C3=A9lien=20Sibiril?=
 <81782+aureliensibiril@users.noreply.github.com>
Date: Sun, 26 Apr 2026 16:32:03 +0200
Subject: [PATCH] Document AgentRun.Update checkpoint write split
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update writes every mutable column of agent_runs except checkpoint.
That exclusion is intentional: PGCheckpointer.Save and ClearCheckpoint
are the only paths that touch the column, so a status commit cannot
overwrite an in-flight checkpoint saved between Load and Update.

Surface the rule on the Update method so future readers do not patch
in a checkpoint write thinking it was an oversight.

Signed-off-by: Aurélien Sibiril <81782+aureliensibiril@users.noreply.github.com>
---
 pkg/coredata/agent_run.go | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/pkg/coredata/agent_run.go b/pkg/coredata/agent_run.go
index 89eee4ab0..ba55ace9d 100644
--- a/pkg/coredata/agent_run.go
+++ b/pkg/coredata/agent_run.go
@@ -346,6 +346,11 @@ RETURNING
 	return nil
 }
 
+// Update intentionally does not write the checkpoint column. Status
+// commits and checkpoint persistence are split: PGCheckpointer.Save is
+// the only writer of checkpoint and ClearCheckpoint is the only path
+// to remove it. This prevents a status update from accidentally erasing
+// an in-flight checkpoint saved between Load and Update.
 func (e *AgentRun) Update(
 	ctx context.Context,
 	tx pg.Tx,