alex/flybrain
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: which replies permit a subset, and which do not

Browse source 
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.
This commit is contained in:
acamilo 2026-09-22 19:05:58 +00:00
parent f6baeb5cfa
commit ef82a05a3a
1 changed files with 16 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
services/flysim/crates/fly-session/README.md
View file

@ -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