Repository navigation
fix(crew-log): carry the lineage scan's fault bit to the dispatch refusal - #12534
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the refusal-site WARNING's per-request cadence is acceptable: cause 2 never clears, so a polling conductor logs one warning per refused read forever. [DESIGN-REVIEWED] 6ff6a74 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (7 items) — 6 justifiedIntent: FIX — a lineage scan that couldn't read part of the store refused a conductor its own child's log with no record anywhere of why; provenance is the added regression test that reddens on base.
[FIRST-PRINCIPLES-REVIEWED] 6ff6a74 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsThe change is purely additive and well-guarded: No findings. [OPUS-REVIEWED] 6ff6a74 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
1dd419e to
143f24d
Compare
|
F1 (GPT 5.6, fenced, I verified the mechanism independently before acting rather than taking the finding on
So The fix, on The rest of the change stands, and the distinction that motivated it is not lost -- it
Tests were retargeted onto what the change now guarantees, rather than left asserting
Mutation-verified on this head: reverting |
143f24d to
363f6c1
Compare
|
Watch item answered: accepted and deferred. I checked all three of its claims against the code at this head rather than reading the finding's shape, and all three hold.
|
|
Item 5 answered: the consumer count is right and the duplication premise is not. Rebutted, with the measurement.
|
363f6c1 to
0f32459
Compare
0afb94b to
04ece28
Compare
|
Item 7 answered for this head. The deletion is declined for the same measured reasons as on
|
…usal site The dispatch scope view was folded from SessionTree.records(), which drops whether the scan faulted, while both of its consumers DECIDE on an edge: the per-unit read door and the unit listing. dispatched_by() answers False for a missing node whatever put it there, so an edge the scan never read and a real absence of lineage were the same answer, and nothing anywhere recorded which one had happened. Three reachable causes set that bit: a unit whose segment stat or head read raises, a unit whose announce record is present and unreadable (cached as a judged fault, and permanent because the log is append-only), and a population past TREE_UNIT_CAP. dispatch_view now reads through SessionTree.reading(), the same accessor ReferenceScanner already uses for this reason, so the fault reaches a decider through one mechanism rather than two spellings of it. TreeReading carries the scan's own records so the sid->slot map, the nodes and the flag all come from one scan under one take of the tree's lock; asking records() separately would be a second scan whose population could differ. DispatchView carries incomplete. The fault is surfaced to the OPERATOR, never to the caller. A caller-visible refusal text would be an existence oracle: the door passes the requested unit as the scan's preferred, a named unit is admitted first, and its own read fault feeds the scan's flag -- so a guessed id that exists and cannot be read would be told apart from one that does not exist, on exactly the boundary _OUT_OF_SCOPE_REFUSAL exists to keep closed. One refusal text for both cases, with a warning at the refusal site naming the incomplete scan. The listing gets no field of its own either. It sets truncated, which every caller already reads as "this is not the whole set" -- the safety property -- and a separate lineage_incomplete key would be a response contract with no consumer in the product. The cause is available to an operator in the refusal door's log. The per-unit re-check is deliberately untouched: it re-folds the target's class and never re-runs dispatched_by, so it has no lineage verdict to word.
GPT 5.6 Review —
|
04ece28 to
6ff6a74
Compare
GPT 5.6 Review —
|
On the subtraction, the position is unchanged and this is its fifth raise. The full argument stands at #12534 (comment) and is not re-argued here. Its shape, once: On the wording, the review is right and I am not disputing it. The sentence at What I am not doing is spending a new head on it this minute. A push re-rolls every review lane, and GPT and Opus are both clean on this head with Design at PASS. This PR's rule is that an advisory finding is answered in a comment while the blocking lanes are clean, and this verdict is advisory by its own statement. The reword rides the next head this PR takes for any other reason; if none arrives it is a one-clause follow-up, recorded here rather than left for the next reader to trip over. Items 1 through 5 and item 7 are marked justified and are not contested. |
buluoray
left a comment
There was a problem hiding this comment.
Verified at head 6ff6a74c. Approving.
A fault bit carried from a scan to a dispatcher has one classic failure -- carried but never acted on -- so I checked what the bit means and what changes when it is set, and the honest answer is split.
The bit means the scan could not READ part of the store, not that the scan found a fault. Three setters accumulate into _records_with_fault: an announce record present but unreadable as an entry (session_tree.py:484-511, the permanent case on an append-only log), a faulted directory listing (:414-416), and over_cap where rows past TREE_UNIT_CAP were never walked. Combined at :545-546 as incomplete = faulted or over_cap, with the outer except at :549 also returning incomplete=True.
At the per-unit refusal door this is observability, not correctness, and the PR says so. On not view.dispatched_by(...) the handler logs a warning (handlers/crew_log.py:1131,1150) and the 403 plus its wire text are byte-identical either way -- deliberate, to avoid an existence oracle. Worth naming plainly: the operator gets the distinction, the caller deliberately does not.
The correctness half is elsewhere and it is real. read.py:697-702 folds lineage_incomplete into "truncated", and read.py:351 makes a failed scan return incomplete=True instead of an empty view that read as "this store holds no lineage." Before the diff, dispatch_view used _TREE.records(), which drops the bit -- so a conductor asking about its own transitively-dispatched grandchild got "out of scope" whether the edge was truly absent or merely unread, and the listing reported truncated: false while the tree was missing an edge. A confident wrong answer worded as a real absence, with nothing logged to explain it. That is a genuine fix, not a nit.
Propagation is fail-closed: every exception arm sets incomplete=True, and the bit is derived at scan time from faulted or over_cap rather than read off a persisted per-record field -- so a legacy on-disk log missing any such field cannot make the scan read clean, which is the concrete "older record shape" case.
Mutations are right, and the non-vacuity one is the one that matters: inverting the bit's meaning (incomplete = not (faulted or over_cap)) still reddens three tests, including the intact-store control. So the tests check what the bit MEANS, not that a field travels. Dropping the propagation reddens test_crew_log_routes.py:1494 and :1586. 40 passed in TestTheDispatchFence.
First Principles' CONCERNS holds and you have already conceded the half worth conceding: SessionTree.records() now has zero product consumers while read.py:337 claims "ONE mechanism rather than two spellings." Declining the deletion on scope is reasonable (~27 test sites for zero behaviour change), and rewording the docstring at the next head closes the part that would mislead a reader.
Both blocking lanes have real verdicts at this head -- [GPT-REVIEWED] 6ff6a74c at 18:46 and [OPUS-REVIEWED] 6ff6a74c at 18:55. There is a stale "review incomplete" straggler for the same SHA from 18:24 that the primary comment's later update supersedes; noting it so nobody reads it as outstanding.
…usal site (kirodotdev#12534) The dispatch scope view was folded from SessionTree.records(), which drops whether the scan faulted, while both of its consumers DECIDE on an edge: the per-unit read door and the unit listing. dispatched_by() answers False for a missing node whatever put it there, so an edge the scan never read and a real absence of lineage were the same answer, and nothing anywhere recorded which one had happened. Three reachable causes set that bit: a unit whose segment stat or head read raises, a unit whose announce record is present and unreadable (cached as a judged fault, and permanent because the log is append-only), and a population past TREE_UNIT_CAP. dispatch_view now reads through SessionTree.reading(), the same accessor ReferenceScanner already uses for this reason, so the fault reaches a decider through one mechanism rather than two spellings of it. TreeReading carries the scan's own records so the sid->slot map, the nodes and the flag all come from one scan under one take of the tree's lock; asking records() separately would be a second scan whose population could differ. DispatchView carries incomplete. The fault is surfaced to the OPERATOR, never to the caller. A caller-visible refusal text would be an existence oracle: the door passes the requested unit as the scan's preferred, a named unit is admitted first, and its own read fault feeds the scan's flag -- so a guessed id that exists and cannot be read would be told apart from one that does not exist, on exactly the boundary _OUT_OF_SCOPE_REFUSAL exists to keep closed. One refusal text for both cases, with a warning at the refusal site naming the incomplete scan. The listing gets no field of its own either. It sets truncated, which every caller already reads as "this is not the whole set" -- the safety property -- and a separate lineage_incomplete key would be a response contract with no consumer in the product. The cause is available to an operator in the refusal door's log. The per-unit re-check is deliberately untouched: it re-folds the target's class and never re-runs dispatched_by, so it has no lineage verdict to word.
…usal site (kirodotdev#12534) The dispatch scope view was folded from SessionTree.records(), which drops whether the scan faulted, while both of its consumers DECIDE on an edge: the per-unit read door and the unit listing. dispatched_by() answers False for a missing node whatever put it there, so an edge the scan never read and a real absence of lineage were the same answer, and nothing anywhere recorded which one had happened. Three reachable causes set that bit: a unit whose segment stat or head read raises, a unit whose announce record is present and unreadable (cached as a judged fault, and permanent because the log is append-only), and a population past TREE_UNIT_CAP. dispatch_view now reads through SessionTree.reading(), the same accessor ReferenceScanner already uses for this reason, so the fault reaches a decider through one mechanism rather than two spellings of it. TreeReading carries the scan's own records so the sid->slot map, the nodes and the flag all come from one scan under one take of the tree's lock; asking records() separately would be a second scan whose population could differ. DispatchView carries incomplete. The fault is surfaced to the OPERATOR, never to the caller. A caller-visible refusal text would be an existence oracle: the door passes the requested unit as the scan's preferred, a named unit is admitted first, and its own read fault feeds the scan's flag -- so a guessed id that exists and cannot be read would be told apart from one that does not exist, on exactly the boundary _OUT_OF_SCOPE_REFUSAL exists to keep closed. One refusal text for both cases, with a warning at the refusal site naming the incomplete scan. The listing gets no field of its own either. It sets truncated, which every caller already reads as "this is not the whole set" -- the safety property -- and a separate lineage_incomplete key would be a response contract with no consumer in the product. The cause is available to an operator in the refusal door's log. The per-unit re-check is deliberately untouched: it re-folds the target's class and never re-runs dispatched_by, so it has no lineage verdict to word.
Problem / Motivation
crew_log.read.dispatch_viewfolded the dispatch scope view fromSessionTree.records(). That accessor says in its own docstring that it "Dropswhether the scan faulted", and names
reading()as the accessor that keeps it. Bothconsumers of the view DECIDE on a lineage edge:
dashboard/handlers/crew_log.py::_read_scope_refusal;read.list_session_units, which drops a row whosedispatched_byanswers False.dispatched_byanswers False for a missing node whatever put it there, so an edgethe scan never read and a genuine absence of lineage were the same answer, and
nothing anywhere recorded which one had happened. A conductor refused its own child's
log got the same account as a stranger, and an operator investigating had nothing to
read.
Three reachable causes set the dropped bit:
statorread_headraises(
session_tree.SessionTree._read, itsreturn None, Truearms);_Head(..., faulted=True). A log is append-only, so those bytes cannot becomereadable: that verdict is re-served on every later scan for the life of the file.
This one never clears.
TREE_UNIT_CAP(over_cap).Why it matters
_read_scope_refusalis the only door a dispatched session has to the crew logs ofthe sessions it created (#12141). Refusing is the safe direction and nothing is
over-granted -- but in cause 2 the refusal is permanent, and with no record of why,
the failure is indistinguishable from a correct scope denial to everyone including
the operator.
The listing has the same shape one level out. A row dropped for a lost edge is dropped
BEFORE it is counted, so
scannednever sees it, andtruncatedreported only the cutthe function itself made: a caller was handed a short list labelled complete.
The sibling module already does this correctly, which is the precedent this change
follows rather than a new judgement.
crew_log/holders.py::ReferenceScanner.holdersreads lineage throughself._tree.reading(preferred_ids)and ORslineage.incompleteinto its answer, andits docstring states the reason in the same terms: "A lineage read that faulted drops
one unit's creator record silently, so a conductor stops being recognised as its
worker's ancestor, the ancestor rule stops dropping it, and the conductor ... is
reported as the holder. That is a confident WRONG owner, not a missing one, and
without the tree's flag the answer would call itself complete."
How our fix solves it
dispatch_viewreads throughSessionTree.reading(), the accessorReferenceScanneralready uses, so the fault bit travels WITH the scan that producedit -- one locked scan serving the nodes, the flag and the records, instead of a second
unlocked call whose answer could disagree with the first. (This is a claim about the
fault bit's path, not about how many accessors the class exposes; an earlier wording
said "ONE mechanism rather than two spellings of it", which reads as the latter and is
corrected here.) Its
exceptarm now reportsincomplete=True: a scan that failed outright is the strongest incompleteness thereis, and it previously read as a store holding no lineage.
TreeReadingcarries the scan's ownrecords. A consumer that places a UNIT needsthe
sid -> slotmap, whichfold_treedrops -- it is keyed by slot and a unit idappears nowhere in its output. Asking
records()for that map separately would be aSECOND scan under a second take of the tree's lock, so its population could differ
from the nodes and the flag, and the ancestor rule would be applied across two
moments. The field defaults to
(), so nothing that constructs aTreeReadingwithout it changes.
DispatchViewcarriesincomplete.same
_OUT_OF_SCOPE_REFUSAL, and the refusal site logs a warning naming theincomplete scan. A caller-visible distinction would be an existence oracle: this door
passes the requested unit as the scan's
preferred(crew_log.py:1132), a named unitis admitted first (
session_tree.py:400), and its own read fault accumulates into thescan's flag (
session_tree.py:422) -- so a guessed id that exists and cannot be readwould be worded differently from one that does not exist, on exactly the boundary
_OUT_OF_SCOPE_REFUSALdocuments itself as protecting. See the review dispositionbelow; this is the shape the first revision got wrong.
truncatedand gets no field of its own. Every caller alreadyreads
truncatedas "this is not the whole set", which is the safety property; aseparate
lineage_incompletekey would be a response contract with no consumer inthe product (grepped: written only, read by nothing in
src/,website/src/,test/or
docs/). The cause is recorded for an operator at the PRODUCER, below, which iswhat covers this path: a caller that only lists reaches no refusal door.
SessionTree._readwarns when an announce record is present and unreadable, namingthe unit. That is the one layer that knows both the cause and which unit carries it,
and because every later scan is served by the head cache without reaching that line,
the operator gets one record per damaged unit rather than one per scan. Being at the
producer, it covers both consumers of the fault bit -- the per-unit door and the
listing -- where a record at either call site covers only that one. The other fault
arms stay silent on purpose: each is transient or re-judged on the next scan, so
logging them would be per-scan noise.
Deliberately unchanged: the post-read re-check (
_unit_recheck_refusal). It re-foldsthe target's CLASS and never re-runs
dispatched_by, so it holds no lineage verdict toword. Its own
_OUT_OF_SCOPE_REFUSALuse is about the scope tuple moving during theread, which is a different fact.
What tests we did
Four new tests in
test/test_crew_log_routes.py::TestTheDispatchFence, three driving theREAL route (
routes.api_crew_log_unit_page) and the fourth the real listing, not ahelper:
test_an_unreadable_middle_log_refuses_as_unknown_lineage_not_out_of_scope-- theregression. A conductor -> child -> grandchild tree where the CHILD's announce record
is replaced on disk with a well-formed JSON object that is not an entry, so the scan
drops that unit's record and the walk finds no node for its slot. The grandchild's own
log is intact and the conductor really did dispatch it transitively. It asserts the
wire carries the ordinary refusal AND that the refusal site logged the incomplete
scan. The damage is planted as BYTES rather than monkeypatched, because cause 2 above
is the non-transient one and a patched read would exercise only the transient case.
test_an_intact_store_logs_no_incomplete_scan_when_it_refuses-- the allow-directioncontrol. Without it, a site that logged on every denial would satisfy the assertion
above while saying nothing true.
test_the_refusal_text_is_identical_whether_the_scan_was_short-- the no-oracle pin.It compares the two response bodies for EQUALITY rather than asserting a phrase, so
re-introducing any caller-visible difference reddens it however it is spelled.
test_a_listing_only_lineage_fault_is_recorded_by_the_producer_once-- the listingconsumer, which reaches no refusal door. It drives the SCOPED listing, because
list_session_unitsbuilds its dispatch view only when a slot is in scope and anunscoped owner listing never consults lineage at all. It asserts the listing still
reports
truncated, and that the producer's record appears exactly ONCE across twoscans naming the unit.
Mutation-verified on this head, in both directions. Reverting
dispatch_viewto_TREE.records(preferred)withincomplete=Falsereddens the regression test on itscaplog assertion (
assert False-- nothing was logged), 333 of 334 green. For theproducer record, deleting the warning reddens the listing test at
assert 0 == 1whileits two
truncatedassertions still pass, so the fixture reached the faulted state andonly the record was missing; moving that same warning to the arm where the head cache is
READ reddens it at
assert 2 == 1. Two mutations failing in opposite directions is whatsays the once-per-unit claim is measured rather than decorative. Both controls hold.
Scoped local run on the pushed tree, serially (
-n0): 334 passed acrosstest_crew_log_routes.py,test_crew_log_session_tree.pyandtest_crew_log_holders.py-- the last because it consumesTreeReading. The twoexisting pins on the listing's
truncatedfield (oneis False, oneis True) bothstill pass, which is what says the fold into that field did not invert an existing
contract. Gates on the final tree, each exit status read on its own: black, isort,
flake8, mypy, comment-history, sync-IO-in-async, loop-bound locks, brand, testpaths
coverage and feature map.
Review disposition
revision returned a distinct refusal when the scan was short, and my code comment
argued
incompletewas a property of the scan rather than the target. That was wrong:I had not traced
preferred. The three call sites above establish it, and the fix isthe uniform refusal plus the operator log.
promised the caller-visible
_LINEAGE_UNREADABLE_REFUSALand quoted a mutationtranscript asserting
'could not be established'on the wire, neither of which existsin the tree. That was a stale body after the security fix, and it is corrected here.
lineage_incompleteresponse key is deleted. I verified the claim rather than takingit on the reviewer's grep: the field had no reader anywhere in the product.
this description and the listing's own comment both claimed "the cause is available to
an operator in the log the refusal door writes", and that the door's log fires only in
_read_scope_refusal. That was false for a caller that only lists: it would seetruncatedlatched by a fault that never clears, with nothing anywhere recording why.I verified the chain before acting rather than treating a restated point as settled.
Fixed at the producer rather than at the second call site, so one record covers both
consumers; the false comment is corrected rather than left beside its correction.
SessionTree.records()at zero product callers) andFirst Principles item 5: the count is right, the duplication premise is not.
Re-measured uncapped: zero callers in
src/, 26 in one test file. Butrecords()isa one-line projection of the same private locked scan
reading()uses, so there is nosecond implementation to drift;
snapshot()is the same shape and does have a productcaller, which is what says the three-projection trio is intended. The docstring
sentence that named a caller it no longer has IS corrected here. Deleting or
privatizing a member of that trio is a change to the module's shape and is not this
change's to make.
read.py:264and:599): accepted and fixed. Two morecomments in this file still described reporting paths this change had already altered --
one said the caller is told "the lineage could not be established", which is the second
refusal text the security fix DELETED, and the other credited the per-unit refusal door
with the listing's record. The first was the worse of the two: a comment describing the
existence oracle as current behaviour is how a later maintainer reinstates it. Both are
rewritten. I also swept the whole diff for every phrasing of that claim rather than only
the two lines named, because this is the third site of one claim and the first fix
addressed only one of them; the remaining occurrences of "refusal door" in
crew_log/are the corrected text saying this path reaches none.
Pattern harvest
Rule candidate: semgrep
Pattern: a decider bound to the fault-DROPPING half of a two-accessor pair over one
scan.
This defect class is not the specific bug.
SessionTreedeliberately exposes twoaccessors over the same scan --
records()drops whether the scan faulted,reading()keeps it -- and the class is any caller that DECIDES on the result whilebound to the first.
holders.pywas bound correctly andread.pywas not, with nomechanical difference between the two call sites for a reviewer to see: both read
plausibly, and the wrong one's consequence surfaces only on a store that could not be
fully read, which no test exercised.
The checkable form is narrow and exact: forbid
\.records\(onkiro_crew.crew_log.session_tree.SessionTreeoutsideSessionTree.readingitself,since
readingis the only legitimate caller left. That is one semgrep rule with nofalse-positive surface, and it retires the class for this pair rather than for this
one call site.
The generalization worth carrying beyond it is a review-prompt line, because the
shape recurs wherever a scan's completeness travels beside its data: when a module
offers a lossy and a lossless reader of one measurement, a caller that acts on the
result takes the lossless one, and the lossy one exists for display. The
TreeReadingdocstring already states that rule in prose; nothing enforced it.A second, smaller pattern this round paid for: a fault-specific REFUSAL TEXT on a door
whose scan admits a caller-named target first is an existence oracle. Worth a
review-prompt line of its own, since the tell is not in the refusal site but in whether
the scan's input is caller-controlled.
Any other suggestions on the work
Found by an audit of the crew log stack, whose remaining findings are advisory and
latent and are not filed: the
usagefold'scontext_by_sourceis the one retained mapin the projection registry with neither a count budget nor the label coercion its
siblings carry (bounded today only by the producer's closed label vocabulary),
approvals'by_decisionhas no count budget, and there is no declared entry-typevocabulary for
KIND_CREWat all, sovalidate_datareturns silently for everycrew-kind entry -- harmless while nothing writes a crew log, and worth knowing before
the first writer does.
Refs #12141.
no linked issue: this came out of a read-only audit of the crew log stack rather than a
filed report, so there is no issue to close.
#12141is the merged PR that introduced thecross-session read door this defect lived on, referenced for context only -- it must not be
reopened or closed by this merge.