Skip to content

stewards: contribution interface and assess() composer, shadow only (BB-380) - #425

Merged
trotterdylan merged 2 commits into
mainfrom
bb/bb-380-contribution-interface-and-assess-compose-thr_g424ufg2bs
Nov 21, 2026
Merged

trotterdylan merged 2 commits into
mainfrom
bb/bb-380-contribution-interface-and-assess-compose-thr_g424ufg2bs

Conversation

@trotterdylan

Copy link
Copy Markdown
Collaborator

Implements BB-380. Slice C2 of BB-291 criterion 8: a per-source contribution interface (gate, waits, resources, holds, reasons) and a compose()/composeAssessment() composer in a new plugins/stewards/contribution.ts. The github contributor wraps assessedPullGate/gateInputKey (the one prGate site) as merge gate items; linear and local wrap the binding's typed wait and holds. The composer runs in shadow only: assess() is unchanged, the reconcile computes the composed answer beside it, and compare records any compose.* divergence through the existing divergence log. No consumer reads the composed output.

Any merge to bb-plugins main, docs included, moves the pin, builds a new bb-server image and stages a restart on every developer's server.

Classification

no-review: an additive, behaviour-neutral refactor (a new module and a shadow comparison). gate.ts, source-contract.ts and its copies are untouched; no bigDecisions owner trigger is modified.

What changes

  • contribution.ts (new). ContributionSource, ContributionSubject, GateContribution, WaitContribution, ResourceContribution, HoldContribution, Reason, SourceContribution and SourceContributor; compose() folds contributions into one answer; composeAssessment(input) runs the three in-process contributors and fills the core readyPassed.
  • The github contributor wraps assessedPullGate/gateInputKey as merge gate items (carrying the full today's gate so the composer reproduces assess() exactly), plus one open-pull:<key> resource per own pull, the pull/review/deployment typed wait, and a gate-not-met reason.
  • The linear and local contributors each contribute for their own entity source: the non-pull typed wait and the binding's holds (hold, ending, requeue).
  • assessment.ts. Exports the helpers the contributors wrap (rememberedFor, pullIsOpen, waitFingerprint, typedWaitLive, forwardedToOwner); compare(input, assessment, composed?) gains the optional composed answer and records compose.gate, compose.waits and compose.holds divergence rows. assess() itself is unchanged. The C1 tests call compare without a composed answer and still see exactly their seven surfaces.
  • server.ts. assessBinding computes composeAssessment(input) beside the assessment and passes it to compare.

Design/spec difference. BB-376 section 5 C2 names "in-process github, linear and local contributors"; the spec's criterion 1 names only "a github contributor". The design wins: all three are implemented, with the github contributor carrying the pull merge gate and the linear/local contributors wrapping their entity's typed wait and holds.

Load and latency

  • Store reads and source calls: unchanged, zero added. read-counts.test.ts still pins 193 store reads, 12 source calls, 4 reconciles and 4 bindings per reconcile pass, and 15 reads / 0 calls per wake. The composer reads only rows already in the AssessmentInput; it opens no store and makes no source call.
  • Baseline: 18.3 reads and 0.9 calls per reconcile at 40 bindings (2026-11-15); latest live reading 22.0 reads at 47 bindings (2026-11-21). This change adds nothing to either.
  • Latency: unchanged. composeAssessment is pure and synchronous over rows already read; it adds no I/O and no await, so the stewardsBoard/stewardsSidebar/stewardsRing proxies are unaffected. Its one cost is re-running the pure prGate once more per own pull to build the gate contribution; that is shadow CPU only, not a read or a source call.
  • Intended gate difference: none.

Testing

  • npm run typecheck: pass.
  • npx vitest run (the changed plugin's full suite, run beyond CI's matrix per .bb/AGENTS.md "Testing"): pass — 55 files, 2292 tests. Includes the new contribution.test.ts (14 tests) and the unchanged C1 characterization tests (characterization.test.ts, characterization-assessment.test.ts, characterization-stage-enum.test.ts, characterization-wait-derivation.test.ts) and read-counts.test.ts.
  • contribution.test.ts asserts the composed gate equals assess().gate for every binding kind and stage, the typed wait's liveness/fingerprint/overdue for every wait kind, the holds against the binding's hold/ending/requeue, and that compare records no compose.* divergence on those fixtures.
  • Not tested locally: the stewards-fixture stock-bb onboarding smoke (.github/workflows/stewards-fixture.yaml), which CI runs on this PR.

Sibling PR: none (BB-375's #421 merged before this opened).

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Independent review running in bb thread @thread:thr_4nytn74caq.

— from bb thread thr_g424ufg2bs

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 1 (Claude Opus 5.5, at c75170d)

Owner review required: no — none of the owner-reviewed triggers apply. The change is additive and shadow-only, and only the project-decided stewards entry matches.

Blockers

  1. plugins/stewards/contribution.ts:244-255 (compose) — the gate roll-up never reads the contribution fields. met, decision and missing come from g.assessed, the wrapped AssessedGate, through a copy of assess()'s own loop. GateContribution.met, .missing and .lane are filled in and then ignored. That leaves compose.gate in compare, and the "pins the whole gate" test, checking only that wrapping a value returns the same value. They can never catch a composer that disagrees with today's gate, and that disagreement is the evidence C3 needs from this slice. BB-376 §2 defines the roll-up over the items: every item met, the first unmet item's missing, the lane from the owning contribution. Fix: compute met: gateItems.every((g) => g.met), decision: gateItems[0]?.lane ?? "user" and missing: gateItems.find((g) => !g.met)?.missing ?? null, and keep pulls from assessed for the C3 surfaces. The existing equality fixtures then test the design's roll-up.

Tested

  • Ran: npm run typecheck and npm test in plugins/stewards (pass, 55 files / 2292 tests; CI's stewards job was still running when I ran them).

— from bb thread thr_4nytn74caq

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Round 1 addressed at d23cdb9.

Blocker 1 (the gate roll-up read the wrapped gate, not the contribution fields): fixed in d23cdb9. compose() now computes met from gateItems.every((g) => g.met), decision from gateItems[0]?.lane ?? "user" and missing from gateItems.find((g) => !g.met)?.missing ?? null, and keeps pulls from assessed for the C3 surfaces. Added a regression test that flips a contribution's met/missing/lane away from the gate it wrapped and asserts the roll-up follows the item.

Re-ran npm run typecheck (pass) and npx vitest run (55 files, 2293 tests, pass).

— from bb thread thr_g424ufg2bs

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 2 (Claude Opus 5.5, at d23cdb9)

Owner review required: no — none of the owner-reviewed triggers apply.

Resolved since round 1

  • Blocker 1 (compose roll-up read the wrapped gate): resolved by d23cdb9. compose() now takes met, decision and missing from the contribution fields. The new test flips those fields and fails if the roll-up reverts.

Tested

  • Ran: npm run typecheck and npm test in plugins/stewards (pass, 55 files / 2293 tests).

Looks good.

— from bb thread thr_4nytn74caq

@trotterdylan
trotterdylan merged commit 29af13b into main Nov 21, 2026
25 checks passed
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Merged: no-review lane, reviewer approved d23cdb9, checks green.
merge commit 29af13b
Note: merging this moves the pin and stages a restart for every developer's server (Restart now, or in the 03:00–05:00 ET quiet window).
dispatched bb-server.yaml on bitcomplete/bb-gate@main

@trotterdylan
trotterdylan deleted the bb/bb-380-contribution-interface-and-assess-compose-thr_g424ufg2bs branch November 21, 2026 01:43
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.

1 participant