Skip to content

feat(crew-log): keyed bus subscriptions with disposers and a late-join baseline - #16149

Merged
chenmingwei23 merged 2 commits into
mainfrom
feat/crew-log-bus-keyed
Oct 2, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
feat/crew-log-bus-keyed

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

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 _subscribed flag so it never subscribes twice, a filter inside its own callback, and a _prime step 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

What changed (motivation → approach → change)

Goal → give the bus the three things a consumer needs, at the bus, once.

  • Disposer. 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.
  • Keyed subscribe. Optional scope=, key=, fold= filters. Subscribers are indexed by (kind, scope, key, fold) with None as 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. 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 a FoldAdvanced, 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.
  • The dashboard WS exporter is the first production user of the filters and the disposer. CrewLogPublisher.subscribe_bus() holds two subscriptions, scope="slot" to on_slot_fold and scope="session" to on_session_fold, and keeps both disposers. A second install_crew_log_publisher in 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_advanced stays as a scope router for direct callers.
  • rfc-crew-log-wake amendment 2026-10-02. Owner decision: eager.py only 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.
  • The eager-fold tests filter with scope= instead of inside their callbacks.
  • docs/system-specs/modules/crew-log-projection.md section 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 returned None, and the one production caller discards the return value.

Tests

  • New 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.py line coverage 95%.
  • test/test_crew_log_routes.py: new test_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.py passes.
  • mypy (bus, eager, dashboard crew-log handler), flake8, black, isort, comment-history gate: clean.

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 _subscribed flag, in-callback filter and _prime store read with the disposer, key=/fold= filters and baseline=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 where baseline=True gets its production caller.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

…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.
@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 2, 2026 11:47
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 2114446e8e0b3b52a9ceb11907424221775f3ba8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Confirm the rfc-crew-log-wake "Owner decision" amendment actually came from the owner — this PR is what records that seam reversal.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 2114446e8e0b3b52a9ceb11907424221775f3ba8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Items 1, 3, 4 — zero consumers: grep bus.subscribe|crew_log_bus.subscribe in src/ finds 2 call sites, both scope=-only; key=, fold= and baseline= (the ~130-line hold/replay/floor machinery, the diff's largest piece) have 0 production users — the description concedes "that is where baseline=True gets its production caller" (feat(crew-log): make the conductor pull-forward a keyed bus subscriber #16076, a draft). The deleted pin "a surface with no caller to justify it" is thus still literally true in-tree.
    Clears when: feat(crew-log): make the conductor pull-forward a keyed bus subscriber #16076 or another production subscriber using key=/fold=/baseline= merges.
  • Item 6 — zero consumers: on_fold_advanced kept "for a caller holding an event of either kind" — grep counts 0 production callers, 3 test call sites.
    Subtraction: delete on_fold_advanced; point the three test_crew_log_session_eager.py calls at on_session_fold.
    Clears when: the method is deleted or a production caller is counted.
  • Item 7 — oversized: the reinstall-path subscribe_bus() swap and unsubscribe_bus() (0 production callers) solve a doubling only the swap itself creates — before this PR a reinstall never resubscribed, and the growth listener still follows that once-per-process rule.
    Subtraction: delete unsubscribe_bus and the reinstall subscribe_bus() call; subscribe once on first install.
    Clears when: the deletion is made, or a reinstall path that genuinely re-enters subscription is named.

What this change ships

Inventory (9 items) — 5 justified

Intent: ADDITION — let a crew-log bus consumer listen to one cell, stop listening, and start from the current value.

  1. subscribe() returns a disposer; the "deliberately no unsubscribe" pin removed — zero consumers: merged caller is item 7's manufactured swap; real caller is draft feat(crew-log): make the conductor pull-forward a keyed bus subscriber #16076
  2. Subscriptions filterable by scope= — justified
  3. Subscriptions filterable by key=/fold= — zero consumers: only tests and draft feat(crew-log): make the conductor pull-forward a keyed bus subscriber #16076 use them
  4. baseline=True delivers the current value then higher revisions — zero consumers: production caller is draft feat(crew-log): make the conductor pull-forward a keyed bus subscriber #16076
  5. WS exporter split into two scope-keyed handlers — justified
  6. on_fold_advanced retained as a scope router — zero consumers: only tests call it
  7. A reinstall now swaps the bus pair; unsubscribe_bus() added — oversized: old reinstall path never resubscribed
  8. RFC amendment and spec section 5.2 — justified
  9. Eager tests filter via scope= instead of in-callback — rides along

[FIRST-PRINCIPLES-REVIEWED] 2114446

Description read

[DESCRIPTION-READ] 65135ad6a1375221d712845fc59bbd0cb6001468215899c242339ff3d59de9b5

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 2114446e8e0b3b52a9ceb11907424221775f3ba8 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/crew_log/bus.py:32 -- "registered unfiltered" contradicts the two scope-filtered registrations in subscribe_bus() -> Fix: describe one consumer using two scoped subscriptions and correct the matching spec sentence.
[GPT-REVIEWED] 2114446

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2114446e8e0b3b52a9ceb11907424221775f3ba8: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 2114446e8e0b3b52a9ceb11907424221775f3ba8 — this comment is updated in place on each push.

Review details

Nothing 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 registered unfiltered where the dashboard state exists ... the WS exporter, and subscribe's FILTERS paragraph says A subscription with no filter receives every event of *kind*, which is what the dashboard's WS exporter uses, while the same diff's CrewLogPublisher.subscribe_bus registers two subscriptions each with scope= set — so the module designated as "where does the next consumer go" describes its only consumer with the wrong count and the wrong mechanism (the spec added in the same diff states the opposite: "two scoped subscriptions, one per scope") → Fix: in bus.py say two subscribers registered with scope= filters and pick an actually-unfiltered example for the FILTERS paragraph, and update the two places that still name the no-longer-called bus entry point, CrewLogPublisher's class docstring (dashboard/handlers/crew_log.py:1813, the crew-log bus hands it every fold ... (:meth:on_fold_advanced)) and docs/system-specs/modules/crew-log-projection.md:1130, to on_slot_fold/on_session_fold.

FINDING — src/kiro_crew/crew_log/bus.py:133 — the guard comment asserts Never held while taking ``_lock``'s registry write, but deliver holds self.guard across self.callback(event) and subscribe's own docstring blesses calling it from inside the callback, so the disposer's with _lock routinely runs with the guard held (exercised by test_a_subscriber_can_dispose_itself_from_inside_its_callback) — a false stated lock-order invariant on the one line a future _lock → guard path would be checked against → Fix: restate it as the real rule — the guard is held across the callback, so guard → _lock is the permitted order and nothing may take _lock before a guard.

[OPUS-REVIEWED] 2114446

Verdict parsed from the review's SHA-scoped output markers for commit 2114446e8e0b3b52a9ceb11907424221775f3ba8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2114446e8e0b3b52a9ceb11907424221775f3ba8: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 2, 2026
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.
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) October 2, 2026 15:27
@chenmingwei23
chenmingwei23 merged commit a2bb973 into main Oct 2, 2026
142 of 143 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/crew-log-bus-keyed branch October 2, 2026 16:02
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants