From ef82a05a3a745a4ef89f4c3b3287abcae4b8e91a Mon Sep 17 00:00:00 2001 From: acamilo Date: Tue, 22 Sep 2026 19:05:58 +0000 Subject: [PATCH] docs: which replies permit a subset, and which do not The sweep behind this branch found one check demanding an exact match where the contract permits a short answer, and four that were right to demand one. The question that separates them belongs where the next check gets written, not only in a run report: is the far side reporting what it did, or being held to a requirement? Worker.Acknowledge is the only reply of the first kind here, because ipc-v1 section 5 makes it idempotent. The commit and batch checks are the second kind and are named so nobody loosens them later in the name of tolerance; they are what make a partial commit and an incomplete batch fail. --- services/flysim/crates/fly-session/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/services/flysim/crates/fly-session/README.md b/services/flysim/crates/fly-session/README.md index 8e114e2..1d3b0ae 100644 --- a/services/flysim/crates/fly-session/README.md +++ b/services/flysim/crates/fly-session/README.md @@ -178,6 +178,22 @@ harness.shutdown().await; event ids derived from epoch, source step, rule and ordinal. - **Executors.** The stateless identity executor only, as v1 specifies. +## Before you add a check to a reply + +Ask which kind of reply it is. Is the far side **reporting what it did**, in which case a +subset or an empty answer is permitted and must be accepted? Or is it **being held to a +requirement**, in which case exactness is the rule and must be enforced? `Worker.Acknowledge` +is the only reply of the first kind in this crate, because `ipc-v1` section 5 explicitly makes +it idempotent -- "Already released/unknown IDs are ignored" -- so a second one legitimately +releases nothing, and the section 6 resolution turns any slow Acknowledge into exactly that +second one. Demanding the whole list back there fenced healthy sessions until +`an_acknowledge_that_releases_nothing_is_not_a_failure` was written. + +The commit and batch checks are the second kind and must stay exact: `commit_all` requires +every agent (`step-v1` section 3 phase D, section 7) and `check_batch` requires every declared +port (`workers-v1` section 3). Loosening those in the name of tolerance is the same mistake +pointing the other way -- they are what make a partial commit and an incomplete batch fail. + ## Where this crate narrows or adds to the contract crate - **Required views.** `WorldObservation::validate_against` checks the views a result carries