Subscription Completion Guard#
The Subscription Completion Guard is the policy layer inside the SubscribeAssistantEnhanced plugin that decides whether a subscription's "complete" event should be allowed through, held pending, or permanently vetoed. It combines two subsystems:
VolatilityTrackerโ classifies a changingtotal_episodevalue as unstable by detecting changes within a configurable time window.PendingTimeoutManagerโ maintains per-subscription observation state and enforces timeouts that govern how long an unstable or vetoed subscription stays held before being released.
The guard's entry point is CompletionGuard.handle(), which receives a CompletionEvidence object produced by CompletionEvidencePipeline and applies mode-based policy (strict / balanced / loose, defaulting to balanced) . The pipeline itself lives in engine/pipeline.py.
Volatility Classification (F Signal)#
VolatilityTracker in engine/volatility.py records each observed total_episode value for a subscription and flags it as unstable when that value changes within the configured window.
Key mechanics:
- Window: configurable via
volatility_window_days(default:DEFAULT_VOLATILITY_WINDOW_DAYS = 3days) . Each change setsunstable_until = last_total_changed_at + window_seconds. - Stability check:
is_stable()returnsFalseifunstable_untilis still in the future or if the in-window sample set contains more than one distinct total value. - Direction:
recent_change_direction()returns"down"or"up"based on the most recent change within the window. Direction is persisted inlast_total_change_directionso it survives across runs even if samples age out . - Zero values are skipped โ they are not treated as real changes and do not reset or extend the window .
When VolatilityTracker.is_stable() returns False, CompletionEvidencePipeline._unstable_signal() emits an F:unstable signal with volatility_direction attached. A downward direction change is immediately escalated to a hard_veto in the pipeline ; an upward or neutral change is stored as evidence.unstable_signal and blocks early exit unless a high-confidence E signal can bypass it .
Observation Kinds and Guard Policy#
CompletionEvidence.observation_kind is the pivot that drives both the pipeline's exit cascade and the guard's hold/release decisions. The relevant kinds for this topic are:
observation_kind | Trigger | Default guard action |
|---|---|---|
hard_veto | M (mid-season finale) or F (downward total change) or S (site total ahead) | Hold unconditionally โ no timeout release |
unstable | F (upward/neutral total change) | Hold; balanced/loose can override with target-complete evidence |
medium_target_complete | L + I (or L + S) composite | balanced/loose release immediately; strict holds with timeout |
i_medium, high_completion | Medium/high E or I signal | Release in all modes |
low_l, low_i | Low-confidence L or I signal | Release in loose; balanced conditional; strict holds with timeout |
PendingTimeoutManager State Machine#
PendingTimeoutManager in postcheck/timeout.py is the observation state machine. Its check_observation(subscribe, evidence, mode) method manages all transitions:
Hold paths (subscription stays pending)#
hard_veto/unstablekinds โ always hold; timer resets only when the observation family changes . There is no timeout release for hard vetoes โ they hold until re-evaluated.medium_target_completeโ hold untileffective_timeoutelapses, then release the guard .- Low-confidence (
low_l,low_i) โ hold until timeout, then emit a one-time release token viarecord_release_token().
Release paths#
- Episode total grows during observation โ immediately release and re-evaluate .
- High-confidence signal appears โ
_is_allowed_completion()returnsTrueand observation is cleared . - Timeout elapsed โ release guard (medium target-complete) or release with token (low-confidence), clearing observation state.
Effective timeout and cadence acceleration#
_effective_timeout() returns the configured timeout_days * 86400 seconds, but halves it when cadence_acceleration=True and the broadcast cadence has expired (evidence.cadence_expired). The cadence-expired flag (G) is an advisory computed by _cadence_expired() in the pipeline โ it never drives completion on its own but shortens observation windows.
One-time release tokens#
Low-confidence paths that time out do not release outright. Instead they write a token (releases[sid]) containing the signal fingerprint and total_episode. The next CompletionGuard.handle() call consumes the token via consume_release_token(), allowing the check through if and only if the signal and episode count still match . A mismatched or consumed token is immediately deleted.
Timer continuity rules#
hard_veto/unstable: timer resets on observation family change (differentobservation_kind+signals) .- Low-confidence: timer resets on source switch;
I:all_airedโI:cooldowntransitions preserve the timer as the same I-family .
Key Source Files#
| File | Role |
|---|---|
engine/volatility.py | VolatilityTracker โ records total_episode samples, exposes is_stable() and recent_change_direction() |
engine/pipeline.py | CompletionEvidencePipeline โ emits F:unstable signal, escalates downward change to hard veto |
postcheck/timeout.py | PendingTimeoutManager โ observation state machine, timers, and one-time release tokens |
guard.py | CompletionGuard.handle() โ applies mode policy, dispatches to timeout manager |
shared/config.py | DEFAULT_VOLATILITY_WINDOW_DAYS, volatility_window_days, completion_guard_mode |
engine/types.py | CompletionEvidence, CompletionSignal, CompletionObservationDecision |
See also: Completion Evidence Pipeline โ full signal taxonomy and pipeline exit-cascade diagram.