feat: Add TrackedDeck and CueBox to decking module#8
Open
Nicholas-Keystate wants to merge 2 commits intoWebOfTrust:masterfrom
Open
feat: Add TrackedDeck and CueBox to decking module#8Nicholas-Keystate wants to merge 2 commits intoWebOfTrust:masterfrom
Nicholas-Keystate wants to merge 2 commits intoWebOfTrust:masterfrom
Conversation
TrackedDeck extends Deck with optional cap enforcement, push/pull/drop counters, and high water mark tracking. Prevents unbounded memory growth in producer-faster-than-consumer scenarios by silently dropping elements when at capacity (back-pressure). Drop-in replacement for Deck — all existing Deck tests pass unchanged. CueBox provides two-phase cue lifecycle management (claim/resolve/reject) to prevent re-push livelock where unhandled cues bounce between Doers indefinitely. Includes maxRetries limit and leak detection for claimed but never-resolved cues. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Previously claim() always set retries to 0, making maxRetries ineffective — rejected cues would cycle indefinitely (the exact livelock pattern CueBox is designed to prevent). Now uses _retryCounts dict keyed by id(cue) to persist retry count across reject → re-push → re-claim cycles. Cue is permanently dropped once retries reaches maxRetries. Count is cleaned up on resolve() to prevent memory leaks. Test updated to verify livelock actually terminates. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TrackedDeck: extends
Deckwith optionalcapenforcement, push/pull/drop counters, and high water mark tracking. Drop-in replacement — all existing Deck tests pass unchanged. Prevents unbounded memory growth when producers outpace consumers by silently dropping elements at capacity (back-pressure).CueBox: two-phase cue lifecycle manager (
claim→resolve|reject) that prevents the re-push livelock pattern where unhandled cues bounce between Doers indefinitely. IncludesmaxRetrieslimit to cap reject cycles andexpireLeaked()to detect abandoned claims.Both classes are exported from
hio.helpalongsideDeck.Motivation
Several patterns in downstream KERI usage (keripy) show unbounded Deck growth and re-push livelock:
Registrar.processWitnessEscrow()iterateswitDoer.cueswithout removing entriesRespondant.cueDore-appends unhandled cues to shared DecksTrackedDeck and CueBox address these at the infrastructure level so individual Doers don't need to re-implement bounds checking.
Test plan
test_decktests pass unchanged🤖 Generated with Claude Code