From f40c19ecf0436f8d81259b28078b6696d967789c Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Sat, 12 Sep 2026 18:13:06 +0700 Subject: [PATCH] fleetd #551 shape sweep: fix stale ATTEMPTED-route javadoc/comments in MessageService MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit hasQueuedDelivery's javadoc, the queuedDeliveries field javadoc, and a code comment in send()'s timeout path all still made two claims that ATTEMPTED (fleetd #551) falsifies: a blanket "the message will not arrive later" across every route, and "the terminal may already hold a partial paste" — but agent.prompt pastes AND submits in one call, so the target may hold a complete, already-submitted turn. Each now names the three Injector.Cancellation routes (CANCELLED, NOT_DELIVERED, ATTEMPTED) and says plainly that only the first two establish the message will not arrive later. Comment/javadoc only. No behaviour change: Injector.java is untouched (sha256 0c689b6cf36275c0da45497a74b2bd4f5a3d80c4dbda77d46670c66004e53b69) and no test was added. mvn -o clean install: BUILD SUCCESS, Tests run: 1754, Failures: 0, Errors: 0 (unchanged from before this commit). --- .../dev/ltms/fleet/msg/MessageService.java | 51 +++++++++++-------- 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/fleetd/src/main/java/dev/ltms/fleet/msg/MessageService.java b/fleetd/src/main/java/dev/ltms/fleet/msg/MessageService.java index 5dc3e92..8773b5d 100644 --- a/fleetd/src/main/java/dev/ltms/fleet/msg/MessageService.java +++ b/fleetd/src/main/java/dev/ltms/fleet/msg/MessageService.java @@ -319,16 +319,18 @@ public final class MessageService { /** * Targets whose last send timed out with {@link Outcome#TIMED_OUT_QUEUED} (CB-640) — {@link * #send} called {@link Injector#cancel} and got back something other than {@code DELIVERED}. - * That covers more than one history: the message may have still been queued and {@code cancel} - * removed it right there, or an earlier attempt may already have failed (the call to the - * target's terminal threw) or been abandoned (the target never became ready, or was torn - * down). What holds on every route: the message will not arrive later, and it is not sitting - * in any queue. What does NOT hold on every route: that the target saw nothing — a failed - * delivery attempt can leave a partial paste behind. Set where {@link #send} already computes - * {@code wasDelivered} for that outcome; no queue is kept here, only the fact that the send - * ended with no confirmed delivery. Cleared the same way as {@link #strandedReplies}: the next - * accepted delivery for the target ({@link #send} opening a fresh waiter) or a teardown - * ({@link #abandon}). + * That covers three histories, not one: {@link Injector.Cancellation#CANCELLED} — the message + * was still queued and {@code cancel} removed it right there; {@link + * Injector.Cancellation#NOT_DELIVERED} — nothing was ever sent, because the target never became + * ready, was torn down, or the call to its terminal failed with a herdr error this codebase + * already treats as a confirmed absence; or {@link Injector.Cancellation#ATTEMPTED} (fleetd + * #551) — the call to the target's terminal was made and its outcome is unknown, so the target + * may already hold a complete, submitted turn. Only the first two mean the message will not + * arrive later and the target saw nothing; on the third it may already have arrived in full. + * Set where {@link #send} already computes {@code wasDelivered} for that outcome; no queue is + * kept here, only the fact that the send ended with no confirmed delivery. Cleared the same way + * as {@link #strandedReplies}: the next accepted delivery for the target ({@link #send} opening + * a fresh waiter) or a teardown ({@link #abandon}). */ private final ConcurrentHashMap queuedDeliveries = new ConcurrentHashMap<>(); private final AtomicLong ticketSeq = new AtomicLong(); @@ -418,14 +420,18 @@ public final class MessageService { * with no confirmed delivery — the caller saw {@link Outcome#TIMED_OUT_QUEUED} (see the * {@code TimeoutException} branch of {@link #send}). Despite the method's name, this is not * proof that a message is sitting in a queue: {@link Injector#cancel} reports this outcome - * either because the message was still queued and got removed right there, or because an - * earlier attempt already failed (the call to the target's terminal threw) or was abandoned - * (the target never became ready, or was torn down). Either way the message will not arrive - * later. It does NOT follow that the target saw nothing — on the failed-attempt route the - * terminal may already hold a partial paste. Distinct from {@link Outcome#TIMED_OUT_WORKING}, - * where delivery already happened and only the reply is outstanding. Cleared the next time - * this target's delivery is accepted or the target is abandoned — see - * {@link #queuedDeliveries}. + * through three routes. {@link Injector.Cancellation#CANCELLED} means the message was still + * queued and got removed right there. {@link Injector.Cancellation#NOT_DELIVERED} means + * nothing was ever sent — the target never became ready, was torn down, or the call to its + * terminal failed with a herdr error this codebase already treats as a confirmed absence. + * Only these two routes mean the message will not arrive later. {@link + * Injector.Cancellation#ATTEMPTED} (fleetd #551) means the call to the target's terminal was + * made and its outcome is unknown: {@code agent.prompt} pastes and submits in one + * call, so on this route the target may already hold a complete, submitted turn and be + * working on it right now — it does NOT follow that the target saw nothing. Distinct from + * {@link Outcome#TIMED_OUT_WORKING}, where delivery already happened and only the reply is + * outstanding. Cleared the next time this target's delivery is accepted or the target is + * abandoned — see {@link #queuedDeliveries}. */ public boolean hasQueuedDelivery(String target) { return target != null && queuedDeliveries.containsKey(target); @@ -980,11 +986,12 @@ public final class MessageService { } log.debug("send to {} timed out (delivered={})", target, wasDelivered); if (!wasDelivered) { - // CB-640: record that delivery did not happen for fleet health (see + // CB-640: record that delivery is not confirmed, for fleet health (see // queuedDeliveries). Whatever injector.cancel() reported above — this call - // removed a still-queued Pending, or an earlier attempt already failed or - // was abandoned — the send ends with no confirmed delivery and will not - // arrive later. + // removed a still-queued Pending (CANCELLED), an earlier attempt already + // failed with a confirmed absence (NOT_DELIVERED), or an earlier attempt was + // made and its outcome is unknown (ATTEMPTED, fleetd #551 — the message may + // already have arrived in full) — the send ends with no confirmed delivery. queuedDeliveries.put(target, Boolean.TRUE); } return recorded(new Reply(