Repository navigation
feat(crew-log): keyed bus subscriptions with disposers and a late-join baseline - #16149
Conversation
…n baseline subscribe() now returns a disposer, accepts scope, key and fold filters that index the registry so a publish only walks subscribers that can match, and with baseline=True hands a late joiner the current value of its one cell through the projection read path, then only higher revisions.
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Confirm the [DESIGN-REVIEWED] 2114446 Description read[DESCRIPTION-READ] 082be352851670b8c333a56bca12bc8c7bd2a7aa14e9b0b6f7e0f685ce2f976a That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The keyed filters, baseline machinery and disposer ship ahead of their only real consumer, draft #16076; two retained methods have zero callers at all. Not justified as shipped
What this change shipsInventory (9 items) — 5 justifiedIntent: ADDITION — let a crew-log bus consumer listen to one cell, stop listening, and start from the current value.
[FIRST-PRINCIPLES-REVIEWED] 2114446 Description read[DESCRIPTION-READ] 65135ad6a1375221d712845fc59bbd0cb6001468215899c242339ff3d59de9b5 That sha256 names the PR description this verdict read. Recompute it with |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- src/kiro_crew/crew_log/bus.py:32 -- False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsNothing blocks — two prose/code contradictions in the new bus subscription seam. FINDING — src/kiro_crew/crew_log/bus.py:32 — the paragraph this PR edits now reads FINDING — src/kiro_crew/crew_log/bus.py:133 — the [OPUS-REVIEWED] 2114446 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
CrewLogPublisher subscribes once per scope and keeps the disposers, so a re-install swaps the pair. rfc-crew-log-wake records that eager only folds and publishes and the wake subscribes keyed to its board.
Problem / Motivation
Goal: a crew-log bus consumer can listen to one board or session, stop listening, and start from the current value without reading the store itself.
The crew-log bus (
src/kiro_crew/crew_log/bus.py) can only add subscribers. It has no way to remove one, no way to listen to a single (scope, key, fold) cell, and no way for a subscriber that joins late to learn the current value. The first consumer beyond the WS exporter, the conductor wake in draft #16076, had to build all three around the bus: a process-wide_subscribedflag so it never subscribes twice, a filter inside its own callback, and a_primestep that reads board files directly.Why it matters
Each next consumer (conductor wake, summary fold, card trigger) repeats those workarounds differently. A consumer keyed to one board is called for every publish about every other board. A consumer that primes itself from the store and then subscribes can miss an event that lands between the two steps.
Not a goal
FoldAdvanced.What changed (motivation → approach → change)
Goal → give the bus the three things a consumer needs, at the bus, once.
subscribe()returns a callable that removes the subscription. A second call does nothing. It is safe from inside the callback: no registry lock is held while a callback runs, and a publish skips a subscriber disposed after it was collected.scope=,key=,fold=filters. Subscribers are indexed by (kind, scope, key, fold) withNoneas a wildcard, so a publish looks up at most eight buckets and never walks a subscriber keyed to another cell. An unfiltered subscription still gets every event.baseline=True(with all three filters set) registers the subscriber first, then reads the current value through the read path a route serves (read_slot_projection/read_projection), delivers it as aFoldAdvanced, and from then on only passes events with a higher revision. Events published during the read are held and replayed through that floor, so nothing is lost or repeated. The read runs on the caller's thread, never on the append path or the fold worker. A read that raises removes the subscription and propagates.CrewLogPublisher.subscribe_bus()holds two subscriptions,scope="slot"toon_slot_foldandscope="session"toon_session_fold, and keeps both disposers. A secondinstall_crew_log_publisherin one process disposes the old pair before subscribing the new one, so the publisher is never called twice for one event;unsubscribe_bus()drops both.on_fold_advancedstays as a scope router for direct callers.rfc-crew-log-wakeamendment 2026-10-02. Owner decision:eager.pyonly folds and publishes, consumers subscribe. Trigger one's seam moves from a second consumer on the eager drain to a keyed bus subscription (scope="slot",key=<conductor slot>,fold="work",baseline=True, disposer kept for the armed loop's life). Mirrored in the module spec with a two-way link.scope=instead of inside their callbacks.docs/system-specs/modules/crew-log-projection.mdsection 5.2 documents the API.Backwards compatibility
Compatible:
subscribe(kind, callback)keeps its positional signature and delivers the same events in the same order; it now returns a disposer where it returnedNone, and the one production caller discards the return value.Tests
test/test_crew_log_bus.py(16 cases): disposer idempotence; self-dispose inside a callback; a later sibling disposed mid-publish is not called; filter matching across scope/key/fold; registration order across buckets; a 1000-board check that a publish hands exactly one subscriber to delivery; attribute-less and unhashable events; the baseline join race (revisions 4 and 6 published during a read that answers 5 deliver 5 then 6); a failed read removes the subscription; a cross-thread publish during baseline replay stays ordered; real slot and session baselines through the projection read path.test/test_crew_log_bus.py,test/test_crew_log_session_eager.py,test/test_crew_log_fold_eager.py: 91 passed;bus.pyline coverage 95%.test/test_crew_log_routes.py: newtest_a_reinstall_swaps_the_bus_subscriptions_rather_than_doubling_them-- two installs leave exactly two bus subscribers, each scope reaches only its own handler,unsubscribe_bus()is idempotent and leaves zero. With the three files above: 292 passed.test_docs_lint_fact_checks.py,test_conductor_wake.py: 139 passed;scripts/docs_lint.pypasses.Manual verification
N/A — the bus has no UI; the real slot and session baseline tests drive the actual eager folder and projection read path.
Related Issues
Consumer: #16076 (draft) rebases onto this and replaces its
_subscribedflag, in-callback filter and_primestore read with the disposer,key=/fold=filters andbaseline=True.Other suggestions
Moving the conductor wake (trigger one of
rfc-crew-log-wake) onto the keyed bus subscription is #16076's job after it rebases; that is wherebaseline=Truegets its production caller.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement