Skip to content

feat(runtime): revive ConcurrencyBurst per-instance under ADR 0015 invariants - #57

Merged
ThomasK33 merged 1 commit into
mainfrom
feat/55-concurrency-burst
Aug 27, 2026
Merged

feat(runtime): revive ConcurrencyBurst per-instance under ADR 0015 invariants#57
ThomasK33 merged 1 commit into
mainfrom
feat/55-concurrency-burst

Conversation

@ThomasK33

Copy link
Copy Markdown
Member

Revives ConcurrencyBurst as a standalone, per-instance implementation per ADR 0015's PR #53 outcome, integrated with the merged Admission Bound (#56). This completes ADR 0012's accepted strategy surface; force/steerability stays reserved behind ADR 0015's formal-design bar.

Closes #55

Design

  • BurstWindow (new option, required > 0 under burst): per-scope collection window, anchored at the first member's join — later arrivals never extend it, so a steady sub-window stream cannot starve dispatch. The window is collection time, not execution time.
  • MaxBurstBatch (new option, 0 = uncapped): a window reaching the cap seals immediately with the cap-reaching member as the batch's last member; the next event opens a rolled window. Shaping is delivery-preserving (ADR 0015): boundaries move, no accepted member is ever dropped.
  • One runner goroutine per scope dispatches sealed batches in FIFO seal order (a rolled batch can never overtake its predecessor to the Thread Lock), then retires and deletes the scope entry when idle (no coordinator leak). A join that finds its open window's anchor deadline already passed seals it first, so a late arrival never rides a window it missed.
  • Budgets: the batch's lock wait gets a fresh DetachTimeout starting when it reaches the head of the FIFO (a healthy long predecessor cannot time a successor out); each member runs with its own fresh DetachTimeout.
  • Admission Bound integration (ADR 0015 bounded retention): each parked member occupies a MaxDetached slot from admit() until its terminal disposition; the batch's final member's slot is retained through ReleaseLock so the tail cleanup stays counted. Disposed members' references clear immediately (payloads GC mid-batch).
  • Dispositions (no silent loss): lock-wait exhaustion → all members observably ignored/error + slots freed; mid-batch lease loss → running member preempted (cause ErrPreempted, mirroring runLockedTail), un-started members skipped as ignored — never run unserialized; member handler error → error, batch continues; Runtime Shutdown → parked members drained observably (same abandonment contract as debounce) before the admission drain completes.
  • No preemption surface: OnLockConflict, LockForcer, and the local preemption choreography from PR feat(runtime): ADR 0012 burst + preemption (staged on the #44/#50 design track) #53 are not revived (rejected by ADR 0015).

Hardening-test coverage map (PR #54 burst-lifecycle findings)

Finding (ADR 0015 review history) Dedicated test
Window anchor — no reset on arrivals TestBurstWindowAnchoredAtFirstMemberNotResetByArrivals
Cap-reaching-member ownership / window rollover boundary TestBurstCapReachingMemberSealsItsOwnWindow
Window option validation (positive window, deferred-only) TestBurstConstructionValidation
Lock sequencing — prompt ack, no prelude lock acquisition TestBurstAcknowledgesPromptlyWithoutPreludeLockAcquisition
FIFO ordering of rolled batches per scope TestBurstRolledBatchesDispatchInFIFOOrder
Bounded lock wait + honest member disposition + slot release TestBurstLockWaitBoundedAndMembersDisposedObservably
FIFO wait budget starts at head of queue TestBurstQueuedBatchLockBudgetStartsAtHeadOfQueue
Per-member fresh DetachTimeout budget TestBurstEveryMemberGetsItsOwnExecutionBudget
Collection time consumes no execution budget TestBurstDispatchBudgetStartsWhenWindowCloses
Cooperative cancellation of a timeout-ignoring member TestBurstUncooperativeMemberTimesOutWithoutStarvingSuccessors
Mid-batch lease loss — cancel running member, skip rest TestBurstLeaseLossCancelsRunningMemberAndSkipsRemaining
Observable terminal outcome for every admitted member TestBurstAbortedBatchRecordsTerminalOutcomeForEveryMember
Handler-error member disposition — batch continues TestBurstMemberHandlerErrorDoesNotAbortBatch
Member-reference clearing (GC mid-batch) TestBurstDisposedMemberReleasesEventForGC
Final member's slot held through ReleaseLock TestBurstFinalMemberSlotHeldThroughLockRelease
Parked members occupy admission slots (bounded retention) TestBurstParkedMembersOccupyAdmissionSlots
Open-window shutdown drain TestBurstOpenWindowDrainedByShutdown
Admission-close/drain race under shutdown TestBurstDispatchRacingShutdownRejectedOrDrained
Idle-coordinator GC TestBurstIdleScopeCoordinatorRemoved
Batch join order + single lock hold (base contract) TestBurstDispatchesCollectedBatchInJoinOrder
Window opened during dispatch runs after current batch TestBurstWindowOpenedDuringDispatchRunsAfterCurrentBatch

Validation

  • mise run vet — clean across all workspace modules.
  • GOFLAGS=-race mise run test — all modules green (root, adapters, examples, state backends).
  • Burst lifecycle suite stressed under race: -count=10 and -count=20, zero flakes.

Generated with mux • Model: anthropic:claude-fable-5 • Thinking: xhigh

…variants

Adds the burst Concurrency Strategy per ADR 0015's PR #53 revival verdict:
per-scope collection windows (BurstWindow, anchored at the first member),
optional MaxBurstBatch cap-sealing, FIFO dispatch of rolled batches under a
single Thread Lock hold, per-member DetachTimeout budgets, and full Admission
Bound integration (each parked member occupies a MaxDetached slot until its
terminal disposition).

Every burst-lifecycle finding from the ADR 0015 review history (PR #54) is
proven by a dedicated hardening test. Completes ADR 0012's accepted surface;
force/steerability stays reserved.

Closes #55
@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: a473909df5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector

Copy link
Copy Markdown

Security review completed. No security issues were found in this pull request.

Reviewed commit: a473909df5

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@ThomasK33
ThomasK33 merged commit 7e020e1 into main Aug 27, 2026
1 check passed
@ThomasK33
ThomasK33 deleted the feat/55-concurrency-burst branch August 27, 2026 23:29
ThomasK33 added a commit that referenced this pull request Aug 28, 2026
README's concurrency section still claimed four strategies with burst
staged; all five ship since #57. The ADR index in explanation.md still
showed 0012 as staged and 0015 as Proposed; both are Accepted and
implemented. Force/steerability preemption remains the sole
rejected/reserved concept per ADR 0015.
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.

feat(runtime): revive ConcurrencyBurst per-instance under ADR 0015 invariants (from PR #53)

1 participant