diff --git a/src/Febe.Core/Abstractions/Governance.cs b/src/Febe.Core/Abstractions/Governance.cs
index d7e18ef..a0bf8fd 100644
--- a/src/Febe.Core/Abstractions/Governance.cs
+++ b/src/Febe.Core/Abstractions/Governance.cs
@@ -41,6 +41,9 @@ public enum DenialReason
AccountLimitReached,
UserIsDriving,
Paused,
+
+ /// The account is «Solo archivio», paused or not reachable: the engine does not contact it (spec §4.2, rule 6).
+ AccountNotContactable,
}
///
diff --git a/src/Febe.Core/Engine/AccountPlanCalculator.cs b/src/Febe.Core/Engine/AccountPlanCalculator.cs
new file mode 100644
index 0000000..7fa8a27
--- /dev/null
+++ b/src/Febe.Core/Engine/AccountPlanCalculator.cs
@@ -0,0 +1,315 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+
+namespace Febe.Core.Engine;
+
+/// What the «Con queste impostazioni» panel needs (spec §4.4, mockup 05).
+public sealed record AccountPlanInput
+{
+ /// The account with the settings being edited (not yet saved).
+ public required Account Account { get; init; }
+
+ /// All the other accounts, to compute the load on the daily budgets (the edited account is ignored here by id).
+ public IReadOnlyList OtherAccounts { get; init; } = [];
+
+ /// The effective caution profile (settings applied).
+ public required CautionProfile Profile { get; init; }
+
+ /// Posts of this account already in the library (for the backfill estimate).
+ public int ArchivedPosts { get; init; }
+
+ public EngineOptions Options { get; init; } = EngineOptions.Default;
+}
+
+/// A line of the panel: «Nuovi post» — «controllati ogni 3 ore circa, tra le 7:30 e le 23:30».
+public sealed record PlanLine(string Title, string Text);
+
+/// The consequences of an account's settings, with real numbers (spec §4.5).
+public sealed record AccountPlanEstimate
+{
+ public required IReadOnlyList Lines { get; init; }
+
+ /// Warnings: requested accounts and frequencies exceed what the budgets allow (checks get sparser, not forced).
+ public required IReadOnlyList Warnings { get; init; }
+
+ /// The engine contacts this account at all (not paused, not «Solo archivio», reachable).
+ public bool Contacted { get; init; }
+
+ /// Profile checks as wished by the frequency.
+ public TimeSpan? ProfileCheckWanted { get; init; }
+
+ /// Profile checks as they will really happen (sparser when the budget is short).
+ public TimeSpan? ProfileCheckEvery { get; init; }
+
+ /// Planned interval between story checks (null with stories off).
+ public TimeSpan? StoryInterval { get; init; }
+
+ public double? StoryChecksPerDay { get; init; }
+
+ /// Profile openings per day caused by this account (after thinning).
+ public double ProfileOpensPerDay { get; init; }
+
+ /// Profile openings per day asked by all the accounts together (before thinning).
+ public double TotalProfileOpensPerDay { get; init; }
+
+ /// Daily budget of profiles opened (full, without gradual start or halving).
+ public int DailyProfileBudget { get; init; }
+
+ /// Share of the daily profile budget taken by this account, 0–1.
+ public double ShareOfDailyBudget { get; init; }
+
+ /// All the accounts together ask more than the budget allows.
+ public bool OverBudget { get; init; }
+
+ public int? BackfillRemainingPosts { get; init; }
+
+ /// Days the backfill needs (null when the number of posts is not known yet).
+ public int? BackfillDays { get; init; }
+}
+
+///
+/// The «Con queste impostazioni» calculator (spec §4.4): a pure function the web layer can call at every change.
+/// The numbers are estimates from medians; they say «circa».
+///
+public static class AccountPlanCalculator
+{
+ /// Mean of the next-check jitter (log-normal, median 1, σ 0.25, truncated to [0.6, 1.8]).
+ private const double MeanCheckJitter = 1.03;
+
+ /// Mean of the story jitter (median 0.75, σ 0.25, truncated to [0.45, 1]).
+ private const double MeanStoryJitter = 0.74;
+
+ public static AccountPlanEstimate Calculate(AccountPlanInput input)
+ {
+ ArgumentNullException.ThrowIfNull(input);
+ var account = input.Account;
+ var profile = input.Profile;
+ var options = input.Options;
+ var window = CautionProfileRules.WindowLength(profile.WindowStart, profile.WindowEnd);
+ var windowText = $"tra le {Clock(profile.WindowStart)} e le {Clock(profile.WindowEnd)}";
+ var lines = new List();
+ var warnings = new List();
+
+ var all = input.OtherAccounts.Where(a => a.Id == 0 || a.Id != account.Id).Append(account).ToList();
+ var contactable = all.Where(CheckPolicy.IsContactable).ToList();
+ var totalDemand = contactable.Sum(a => ProfileOpensPerDay(a, window, options));
+ var budget = profile.Budgets.TryGetValue(ActionKind.ProfileOpen, out var b) ? b.PerDay : 0;
+ var overBudget = budget > 0 && totalDemand > budget;
+ var thinning = overBudget ? totalDemand / budget : 1.0;
+
+ var contacted = CheckPolicy.IsContactable(account);
+ var own = contacted ? ProfileOpensPerDay(account, window, options) : 0;
+ TimeSpan? wanted = null;
+ TimeSpan? every = null;
+ TimeSpan? storyInterval = null;
+ double? storyChecks = null;
+
+ if (!contacted)
+ {
+ lines.Add(new PlanLine("Controlli", NotContactedText(account)));
+ }
+ else
+ {
+ // New posts.
+ if (CheckPolicy.WantsProfileChecks(account))
+ {
+ wanted = account.IsFollowed ? CheckPolicy.ProfileCheckInterval(account) : CheckPolicy.VisitInterval(account, window, options.MinimumStoryChecksPerDay);
+ every = TimeSpan.FromTicks((long)(wanted.Value.Ticks * MeanCheckJitter * thinning));
+ var text = account.IsFollowed
+ ? $"scoperti dal giro dei profili che segui, di norma entro {Minutes(profile.PauseMin)}–{Minutes(profile.PauseMax)} minuti dalla pubblicazione, {windowText}. Il profilo si riapre solo per riconciliare, {ItalianText.Every(Round(every.Value))} circa."
+ : $"controllati {ItalianText.Every(Round(every.Value))} circa, {windowText}.";
+ lines.Add(new PlanLine("Nuovi post", text));
+ }
+ else
+ {
+ lines.Add(new PlanLine("Nuovi post", "non scaricati con queste impostazioni."));
+ }
+
+ // Stories.
+ if (CheckPolicy.WantsStories(account))
+ {
+ storyInterval = CheckPolicy.StoryInterval(account, window, options.MinimumStoryChecksPerDay);
+ storyChecks = Math.Max(options.MinimumStoryChecksPerDay, 1 + (window / (storyInterval.Value * MeanStoryJitter)));
+ var how = account.IsFollowed && options.SweepCoversFollowedStories
+ ? "a ogni giro dei profili che segui e"
+ : string.Empty;
+ lines.Add(new PlanLine(
+ "Storie",
+ $"controllate {how} almeno {ItalianText.Number(options.MinimumStoryChecksPerDay)} volte al giorno; fra due controlli passano al massimo {ItalianText.Duration(storyInterval.Value)} circa. Restano 24 ore, quindi nessuna dovrebbe scadere prima di essere vista."
+ .Replace(" ", " ", StringComparison.Ordinal)));
+ }
+ else
+ {
+ lines.Add(new PlanLine("Storie", "spente."));
+ }
+ }
+
+ // History.
+ var (backfillText, remaining, days) = Backfill(input, all);
+ lines.Add(new PlanLine("Storico", backfillText));
+
+ // Weight on the daily budget.
+ var ownAfter = own / thinning;
+ var share = budget > 0 ? ownAfter / budget : 0;
+ lines.Add(new PlanLine(
+ "Carico",
+ contacted
+ ? $"circa {ItalianText.Decimal(ownAfter, ownAfter < 10 ? 1 : 0)} aperture del profilo al giorno, su {ItalianText.Number(budget)} disponibili ogni giorno per tutti gli account."
+ : "nessuno."));
+
+ if (overBudget)
+ {
+ warnings.Add(
+ $"Con {ItalianText.Count(contactable.Count, "account", "account")} e queste frequenze servirebbero circa {ItalianText.Number((long)Math.Round(totalDemand))} aperture di profili al giorno, "
+ + $"ma il tetto è {ItalianText.Number(budget)}: i controlli si diradano (circa {ItalianText.Decimal(thinning, 1)} volte più radi), non si forzano.");
+ }
+
+ var sessionsPerDay = SessionsPerDay(profile, window);
+ var homeBudget = profile.Budgets.TryGetValue(ActionKind.Home, out var home) ? home.PerDay : 0;
+ if (contactable.Any(a => a.IsFollowed) && homeBudget > 0 && sessionsPerDay * options.SweepProbability > homeBudget)
+ {
+ warnings.Add($"Il tetto della home ({ItalianText.Number(homeBudget)} al giorno) è più basso del numero di sessioni: alcuni giri dei seguiti salteranno e i nuovi post arriveranno più tardi.");
+ }
+
+ if (profile.GradualStart && profile.RampUpDays > 0)
+ {
+ warnings.Add($"Con l'avvio graduale, nei primi {ItalianText.Count(profile.RampUpDays, "giorno", "giorni")} dopo il collegamento i tetti partono dalla metà: tutto è più lento.");
+ }
+
+ return new AccountPlanEstimate
+ {
+ Lines = lines,
+ Warnings = warnings,
+ Contacted = contacted,
+ ProfileCheckWanted = wanted,
+ ProfileCheckEvery = every,
+ StoryInterval = storyInterval,
+ StoryChecksPerDay = storyChecks,
+ ProfileOpensPerDay = ownAfter,
+ TotalProfileOpensPerDay = totalDemand,
+ DailyProfileBudget = budget,
+ ShareOfDailyBudget = share,
+ OverBudget = overBudget,
+ BackfillRemainingPosts = remaining,
+ BackfillDays = days,
+ };
+ }
+
+ /// Profile openings per day an account asks for (visits, reconciliations, tagged tab).
+ public static double ProfileOpensPerDay(Account account, TimeSpan window, EngineOptions? options = null)
+ {
+ ArgumentNullException.ThrowIfNull(account);
+ options ??= EngineOptions.Default;
+ if (!CheckPolicy.IsContactable(account))
+ {
+ return 0;
+ }
+
+ double visits;
+ if (CheckPolicy.WantsProfileChecks(account))
+ {
+ var interval = account.IsFollowed ? CheckPolicy.ProfileCheckInterval(account) : CheckPolicy.VisitInterval(account, window, options.MinimumStoryChecksPerDay);
+ visits = ChecksPerDay(interval * MeanCheckJitter, window);
+ }
+ else if (!account.IsFollowed && CheckPolicy.WantsStories(account))
+ {
+ visits = ChecksPerDay(CheckPolicy.StoryInterval(account, window, options.MinimumStoryChecksPerDay) * MeanStoryJitter, window);
+ }
+ else
+ {
+ visits = 0;
+ }
+
+ return (account.ContentTypes & ContentTypes.Tagged) != 0 ? visits * 2 : visits;
+ }
+
+ /// Checks a day at an interval, counting the morning catch-up after the night.
+ public static double ChecksPerDay(TimeSpan interval, TimeSpan window)
+ {
+ if (interval <= TimeSpan.Zero)
+ {
+ return 0;
+ }
+
+ if (interval >= TimeSpan.FromHours(24))
+ {
+ return 24 / interval.TotalHours;
+ }
+
+ return 1 + (window / interval);
+ }
+
+ /// Sessions a day with median session length and median pause.
+ public static double SessionsPerDay(CautionProfile profile, TimeSpan window)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ var session = Math.Sqrt(profile.SessionMin.TotalMinutes * profile.SessionMax.TotalMinutes);
+ var pause = Math.Sqrt(profile.PauseMin.TotalMinutes * profile.PauseMax.TotalMinutes);
+ return window.TotalMinutes / (session + pause);
+ }
+
+ private static (string Text, int? Remaining, int? Days) Backfill(AccountPlanInput input, List all)
+ {
+ var account = input.Account;
+ var profile = input.Profile;
+ if (account.BackfillCompletedAt is { } done && account.State != AccountState.Backfilling)
+ {
+ return ($"completato il {ItalianText.Day(DateOnly.FromDateTime(done.UtcDateTime))}.", 0, 0);
+ }
+
+ if (account.Limits.Depth == HistoryDepth.FromDate && account.Limits.FromDate is { } from)
+ {
+ return ($"dipende da quanti post ci sono dopo il {ItalianText.Day(DateOnly.FromDateTime(from.UtcDateTime))}: lo saprò strada facendo.", null, null);
+ }
+
+ if (account.State is not (AccountState.Backfilling or AccountState.UpToDate) || !CheckPolicy.WantsProfileChecks(account))
+ {
+ return ("nessuno storico da scaricare con queste impostazioni.", null, null);
+ }
+
+ int? target = account.Limits.Depth == HistoryDepth.LastPosts
+ ? account.Limits.LastPosts is { } last ? Math.Min(last, account.PostCount ?? last) : account.PostCount
+ : account.PostCount;
+ if (target is null)
+ {
+ return ("il numero dei post non è ancora noto: lo saprò dopo il primo controllo del profilo.", null, null);
+ }
+
+ var remaining = Math.Max(0, target.Value - input.ArchivedPosts);
+ if (remaining == 0)
+ {
+ return ("tutto già in libreria.", 0, 0);
+ }
+
+ var sharing = Math.Max(1, all.Count(a => a.State == AccountState.Backfilling && a.BackfillCompletedAt is null && CheckPolicy.IsContactable(a)));
+ var pagesPerDay = profile.Budgets.TryGetValue(ActionKind.BackfillPage, out var pages) ? pages.PerDay : 0;
+ var byBudget = pagesPerDay * input.Options.PostsPerBackfillPage / (double)sharing;
+ var perDay = Math.Min(Math.Min(account.Limits.BackfillPostsPerDay, profile.BackfillPostsPerAccountPerDay), byBudget);
+ if (perDay <= 0)
+ {
+ return ("fermo: il limite di storico al giorno è zero.", remaining, null);
+ }
+
+ var days = (int)Math.Ceiling(remaining / perDay);
+ var text = $"mancano {ItalianText.Count(remaining, "post", "post")}, servono circa {ItalianText.Count(days, "giorno", "giorni")} ({ItalianText.Number((long)Math.Floor(perDay))} post al giorno"
+ + (sharing > 1 ? $", a turno con altri {ItalianText.Number(sharing - 1)} account" : string.Empty) + ").";
+ return (text, remaining, days);
+ }
+
+ private static string NotContactedText(Account account) => account.State switch
+ {
+ AccountState.ArchiveOnly => "«Solo archivio»: Febe non contatta questo account.",
+ AccountState.Paused => "in pausa: Febe non controlla questo account finché non lo riattivi.",
+ AccountState.Unreachable => "non raggiungibile: Febe non lo contatta finché non lo verifichi.",
+ _ => "Febe non contatta questo account.",
+ };
+
+ private static string Clock(TimeOnly time) => time.Hour.ToString(System.Globalization.CultureInfo.InvariantCulture) + ":" + time.Minute.ToString("00", System.Globalization.CultureInfo.InvariantCulture);
+
+ private static string Minutes(TimeSpan span) => ItalianText.Number((long)Math.Round(span.TotalMinutes));
+
+ /// Rounds an interval for display: to 5 minutes under 2 hours, to half an hour above.
+ private static TimeSpan Round(TimeSpan interval) => interval < TimeSpan.FromHours(2)
+ ? TimeSpan.FromMinutes(Math.Max(5, Math.Round(interval.TotalMinutes / 5) * 5))
+ : TimeSpan.FromMinutes(Math.Round(interval.TotalMinutes / 30) * 30);
+}
diff --git a/src/Febe.Core/Engine/BudgetLimits.cs b/src/Febe.Core/Engine/BudgetLimits.cs
new file mode 100644
index 0000000..bf7118a
--- /dev/null
+++ b/src/Febe.Core/Engine/BudgetLimits.cs
@@ -0,0 +1,138 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+
+namespace Febe.Core.Engine;
+
+/// Which reduction of the budgets is in force (spec §7.2 avvio graduale, §7.6 tetti dimezzati).
+public enum BudgetReduction
+{
+ None,
+
+ /// Gradual start: from half to full over the profile's ramp days.
+ GradualStart,
+
+ /// Halved for 48 hours after a throttle stop.
+ HalvedAfterThrottle,
+}
+
+/// The budgets in force at an instant, after the strongest reduction.
+/// Hourly and daily budget per category (data excluded).
+/// Daily download budget.
+/// The profile's per-account backfill limit, reduced as the budgets.
+/// Multiplier applied to the profile's values (1 = full).
+/// The reduction that determined .
+/// When the reduction ends (end of the ramp or of the 48 hours), if any.
+public sealed record EffectiveBudgets(
+ IReadOnlyDictionary Budgets,
+ long DataPerDayBytes,
+ int BackfillPostsPerAccountPerDay,
+ double Factor,
+ BudgetReduction Reduction,
+ DateTimeOffset? Until)
+{
+ /// Daily limit of a category (bytes for data).
+ public long DailyLimit(ActionKind kind) => kind == ActionKind.DataDownload ? DataPerDayBytes : Budgets[kind].PerDay;
+
+ /// Hourly limit of a category; null for data, which only has a daily budget.
+ public long? HourlyLimit(ActionKind kind) => kind == ActionKind.DataDownload ? null : Budgets[kind].PerHour;
+}
+
+///
+/// Effective budgets (spec §7.4): when several reductions apply together (gradual start, halved budgets after a
+/// throttle) the strongest wins, never their product.
+///
+public static class BudgetLimits
+{
+ /// Gradual start factor: 0.5 at , rising linearly to 1 after the profile's ramp days.
+ public static double GradualStartFactor(CautionProfile profile, DateTimeOffset? rampStart, DateTimeOffset now)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ if (!profile.GradualStart || rampStart is not { } start || profile.RampUpDays <= 0)
+ {
+ return 1;
+ }
+
+ var elapsed = (now - start).TotalDays;
+ if (elapsed < 0)
+ {
+ return 0.5;
+ }
+
+ return elapsed >= profile.RampUpDays ? 1 : 0.5 + (0.5 * elapsed / profile.RampUpDays);
+ }
+
+ /// 0.5 while the 48 hours after a throttle stop last, otherwise 1.
+ public static double ThrottleFactor(DateTimeOffset? halvedUntil, DateTimeOffset now) =>
+ halvedUntil is { } until && now < until ? 0.5 : 1;
+
+ public static EffectiveBudgets Compute(CautionProfile profile, DateTimeOffset? rampStart, DateTimeOffset? halvedUntil, DateTimeOffset now)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ var ramp = GradualStartFactor(profile, rampStart, now);
+ var throttle = ThrottleFactor(halvedUntil, now);
+
+ // The strongest reduction wins, never the product (spec §7.4).
+ var factor = Math.Min(ramp, throttle);
+ var reduction = factor >= 1 ? BudgetReduction.None
+ : throttle <= ramp ? BudgetReduction.HalvedAfterThrottle
+ : BudgetReduction.GradualStart;
+ DateTimeOffset? until = reduction switch
+ {
+ BudgetReduction.HalvedAfterThrottle => halvedUntil,
+ BudgetReduction.GradualStart => rampStart?.AddDays(profile.RampUpDays),
+ _ => null,
+ };
+
+ var budgets = new Dictionary();
+ foreach (var (kind, budget) in profile.Budgets)
+ {
+ budgets[kind] = new Budget(Scale(budget.PerHour, factor), Scale(budget.PerDay, factor));
+ }
+
+ foreach (var kind in Enum.GetValues())
+ {
+ if (kind != ActionKind.DataDownload && !budgets.ContainsKey(kind))
+ {
+ budgets[kind] = new Budget(0, 0);
+ }
+ }
+
+ return new EffectiveBudgets(
+ budgets,
+ ScaleBytes(profile.DataPerDayBytes, factor),
+ Scale(profile.BackfillPostsPerAccountPerDay, factor),
+ factor,
+ reduction,
+ until);
+ }
+
+ /// A budget times the factor, rounded down, never below 1 when the full budget is positive.
+ public static int Scale(int value, double factor) =>
+ value <= 0 ? 0 : Math.Max(1, (int)Math.Floor((value * factor) + 1e-9));
+
+ public static long ScaleBytes(long value, double factor) =>
+ value <= 0 ? 0 : Math.Max(1, (long)Math.Floor((value * factor) + 1e-6));
+}
+
+/// Use of one budget category, for the interface (spec §7.4, §7.9).
+/// Category.
+/// Actions (bytes for data) of the current local day.
+/// Daily limit in force.
+/// Actions in the rolling last 60 minutes (null for data).
+/// Hourly limit in force (null for data).
+public sealed record BudgetStatus(ActionKind Kind, long UsedToday, long LimitToday, long? UsedLastHour, long? LimitPerHour)
+{
+ /// Amber threshold of the interface (spec §7.4).
+ public const double AmberThreshold = 0.8;
+
+ public double DailyRatio => LimitToday <= 0 ? 1 : (double)UsedToday / LimitToday;
+
+ public double HourlyRatio => LimitPerHour is not > 0 ? 0 : (double)(UsedLastHour ?? 0) / LimitPerHour.Value;
+
+ /// At or above 80% of the daily or of the hourly budget.
+ public bool IsAmber => DailyRatio >= AmberThreshold || HourlyRatio >= AmberThreshold;
+
+ public bool DailyReached => UsedToday >= LimitToday;
+
+ public bool HourlyReached => LimitPerHour is { } limit && (UsedLastHour ?? 0) >= limit;
+}
diff --git a/src/Febe.Core/Engine/CheckPolicy.cs b/src/Febe.Core/Engine/CheckPolicy.cs
new file mode 100644
index 0000000..045fec1
--- /dev/null
+++ b/src/Febe.Core/Engine/CheckPolicy.cs
@@ -0,0 +1,192 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Pacing;
+
+namespace Febe.Core.Engine;
+
+///
+/// Frequencies of spec §7.3 and the rules that say which accounts the engine may contact. A frequency expresses a
+/// wish; the Governor decides what is possible.
+///
+public static class CheckPolicy
+{
+ /// Content types that need a visit of the profile page (posts, highlights, tagged posts, profile picture).
+ public const ContentTypes ProfileContent = ContentTypes.PostPhotos | ContentTypes.PostVideos | ContentTypes.Highlights
+ | ContentTypes.Tagged | ContentTypes.ProfilePicture;
+
+ ///
+ /// The engine contacts an account only when it is up to date or backfilling. «Solo archivio», «In pausa» (also
+ /// after the single download of «Tieni aggiornato» off) and «Non raggiungibile» are never contacted on the
+ /// engine's initiative.
+ ///
+ public static bool IsContactable(Account account)
+ {
+ ArgumentNullException.ThrowIfNull(account);
+ return account.State is AccountState.UpToDate or AccountState.Backfilling;
+ }
+
+ ///
+ /// Whether a «Controlla ora» of Alberto may contact the account: never «Solo archivio» and never a private profile
+ /// he does not follow (rule 6); paused and other unreachable accounts may be checked on request.
+ ///
+ public static bool AllowsManualCheck(Account account)
+ {
+ ArgumentNullException.ThrowIfNull(account);
+ return account.State switch
+ {
+ AccountState.ArchiveOnly => false,
+ AccountState.Unreachable => account.UnreachableReason is not UnreachableReason.PrivateNotFollowed,
+ _ => true,
+ };
+ }
+
+ public static bool WantsProfileChecks(Account account) => (account.ContentTypes & ProfileContent) != 0;
+
+ public static bool WantsStories(Account account) => (account.ContentTypes & ContentTypes.Stories) != 0;
+
+ ///
+ /// Interval between profile checks. Not followed: ~12 h / ~3 h / ~75 min (Su misura: the hours chosen). Followed: the
+ /// sweep discovers new posts, the profile check is only a reconciliation every 24 / 12 / 6 hours (Su misura: four
+ /// times the chosen interval, between 6 and 24 hours).
+ ///
+ public static TimeSpan ProfileCheckInterval(Account account)
+ {
+ ArgumentNullException.ThrowIfNull(account);
+ if (account.IsFollowed)
+ {
+ return account.Frequency switch
+ {
+ Frequency.Low => TimeSpan.FromHours(24),
+ Frequency.High => TimeSpan.FromHours(6),
+ Frequency.Custom when account.CustomPostInterval is { } custom =>
+ TimeSpan.FromTicks(Math.Clamp(custom.Ticks * 4, TimeSpan.FromHours(6).Ticks, TimeSpan.FromHours(24).Ticks)),
+ _ => TimeSpan.FromHours(12),
+ };
+ }
+
+ return account.Frequency switch
+ {
+ Frequency.Low => TimeSpan.FromHours(12),
+ Frequency.High => TimeSpan.FromMinutes(75),
+ Frequency.Custom when account.CustomPostInterval is { } custom && custom > TimeSpan.Zero => custom,
+ _ => TimeSpan.FromHours(3),
+ };
+ }
+
+ /// Maximum interval between two story checks: 8 / 6 / 3 hours (Su misura: the chosen one).
+ public static TimeSpan StoryMaxInterval(Account account)
+ {
+ ArgumentNullException.ThrowIfNull(account);
+ return account.Frequency switch
+ {
+ Frequency.Low => TimeSpan.FromHours(8),
+ Frequency.High => TimeSpan.FromHours(3),
+ Frequency.Custom when account.CustomStoryInterval is { } custom && custom > TimeSpan.Zero => custom,
+ _ => TimeSpan.FromHours(6),
+ };
+ }
+
+ ///
+ /// Story interval actually planned: the frequency's maximum, but never more than a third of the active window, so
+ /// that every account gets at least three story checks a day inside it (spec §7.3).
+ ///
+ public static TimeSpan StoryInterval(Account account, TimeSpan windowLength, int checksPerDay = 3)
+ {
+ var max = StoryMaxInterval(account);
+ if (windowLength <= TimeSpan.Zero || checksPerDay <= 0)
+ {
+ return max;
+ }
+
+ var cap = TimeSpan.FromTicks(windowLength.Ticks / checksPerDay);
+ return max < cap ? max : cap;
+ }
+
+ ///
+ /// Interval between visits of a profile that is not followed: its stories can be seen only from the profile, so a
+ /// visit serves both the profile check and the story check and comes at the shorter of the two intervals.
+ ///
+ public static TimeSpan VisitInterval(Account account, TimeSpan windowLength, int checksPerDay = 3)
+ {
+ var profile = ProfileCheckInterval(account);
+ if (account.IsFollowed || !WantsStories(account))
+ {
+ return profile;
+ }
+
+ var stories = StoryInterval(account, windowLength, checksPerDay);
+ return WantsProfileChecks(account) && profile < stories ? profile : stories;
+ }
+
+ /// Frequency weight of spec §7.2: High 3, Normal 2, Low 1 (Su misura from its interval).
+ public static double FrequencyWeight(Account account)
+ {
+ ArgumentNullException.ThrowIfNull(account);
+ return account.Frequency switch
+ {
+ Frequency.High => 3,
+ Frequency.Low => 1,
+ Frequency.Custom => ProfileCheckInterval(account with { IsFollowed = false }) switch
+ {
+ var i when i <= TimeSpan.FromHours(2) => 3,
+ var i when i <= TimeSpan.FromHours(6) => 2,
+ _ => 1,
+ },
+ _ => 2,
+ };
+ }
+
+ /// Weight of an account in the random order: frequency weight × (1 + delay ÷ interval), the ratio limited to 3.
+ public static double SelectionWeight(Account account, TimeSpan delay, TimeSpan interval)
+ {
+ var ratio = interval <= TimeSpan.Zero ? 0 : Math.Clamp(delay / interval, 0, 3);
+ return FrequencyWeight(account) * (1 + ratio);
+ }
+
+ /// The next check: interval × log-normal (median 1, σ 0.25, [0.6, 1.8]) (spec §7.2).
+ public static TimeSpan NextCheckDelay(IRandomSource random, TimeSpan interval) => random.JitteredInterval(interval);
+
+ ///
+ /// The next story check. «Intervallo massimo» is a maximum, so the jitter is drawn below it: interval × log-normal
+ /// with median 0.75, σ 0.25, truncated to [0.45, 1].
+ ///
+ public static TimeSpan NextStoryCheckDelay(IRandomSource random, TimeSpan maxInterval) =>
+ TimeSpan.FromTicks((long)(maxInterval.Ticks * random.TruncatedLogNormal(0.75, 0.25, 0.45, 1.0)));
+
+ ///
+ /// A random order of items by weight, never the same (Efraimidis–Spirakis: key = u^(1/w), highest first).
+ ///
+ public static IReadOnlyList WeightedOrder(IRandomSource random, IEnumerable<(T Item, double Weight)> items)
+ {
+ ArgumentNullException.ThrowIfNull(random);
+ return [.. items
+ .Select(i => (i.Item, Key: Math.Pow(1.0 - random.NextDouble(), 1.0 / Math.Max(i.Weight, 1e-6))))
+ .OrderByDescending(i => i.Key)
+ .Select(i => i.Item)];
+ }
+
+ /// Budget category a recipe needs first (to skip it when that budget is exhausted).
+ public static ActionKind CategoryOf(RecipeKind kind) => kind switch
+ {
+ RecipeKind.FollowingSweep => ActionKind.Home,
+ RecipeKind.AccountStories or RecipeKind.Highlight => ActionKind.StoryView,
+ RecipeKind.Backfill => ActionKind.BackfillPage,
+ RecipeKind.SinglePost => ActionKind.SinglePost,
+ RecipeKind.FollowingList => ActionKind.FollowingListPage,
+ _ => ActionKind.ProfileOpen,
+ };
+
+ public static RecipeKind RecipeOf(EngineTaskKind kind) => kind switch
+ {
+ EngineTaskKind.FollowingSweep => RecipeKind.FollowingSweep,
+ EngineTaskKind.AccountStories => RecipeKind.AccountStories,
+ EngineTaskKind.ProfileCheck => RecipeKind.ProfileCheck,
+ EngineTaskKind.Backfill => RecipeKind.Backfill,
+ EngineTaskKind.HighlightCheck => RecipeKind.Highlight,
+ EngineTaskKind.TaggedCheck => RecipeKind.Tagged,
+ EngineTaskKind.ReelsCheck => RecipeKind.Reels,
+ EngineTaskKind.SinglePost => RecipeKind.SinglePost,
+ EngineTaskKind.FollowingList => RecipeKind.FollowingList,
+ _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null),
+ };
+}
diff --git a/src/Febe.Core/Engine/CircuitBreaker.cs b/src/Febe.Core/Engine/CircuitBreaker.cs
new file mode 100644
index 0000000..dfc4767
--- /dev/null
+++ b/src/Febe.Core/Engine/CircuitBreaker.cs
@@ -0,0 +1,409 @@
+using System.Globalization;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// The circuit breaker («interruttore», spec §7.6).
+///
+/// - Throttle: closes the session at once; stops 1 hour the first time, 6 hours the second within 24 hours,
+/// 24 hours the third; then halved budgets for 48 hours. Reopens by itself.
+/// - Challenge and disconnection: stop everything and never restart alone; only
+/// (Alberto's «Riprendi», after fixing things in the browser) reopens, and the resume starts the gradual start.
+///
+/// Every stop is an incident row and a line of the Activity timeline; the state is restored from the database
+/// at start-up. is synchronous (signals arrive from capture threads): the state changes at once
+/// and the rows are written in order in the background ( waits for them).
+///
+public sealed class CircuitBreaker : ICircuitBreaker
+{
+ /// Fixed stop durations (spec §7.6: not editable in version 1).
+ public static readonly IReadOnlyList ThrottleStops = [TimeSpan.FromHours(1), TimeSpan.FromHours(6), TimeSpan.FromHours(24)];
+
+ public static readonly TimeSpan HalvedPeriod = TimeSpan.FromHours(48);
+ public static readonly TimeSpan EscalationWindow = TimeSpan.FromHours(24);
+ public static readonly TimeSpan ProposalWindow = TimeSpan.FromDays(7);
+ public const int ProposalThreshold = 3;
+
+ private readonly IFebeStorage _storage;
+ private readonly IClock _clock;
+ private readonly EngineRuntime _runtime;
+ private readonly EngineEvents? _events;
+ private readonly Lock _gate = new();
+ private readonly List _recentThrottles = [];
+ private readonly List _openIncidents = [];
+ private BreakerState _state = BreakerState.Normal;
+ private Task _tail = Task.CompletedTask;
+
+ private CircuitBreaker(IFebeStorage storage, IClock clock, EngineRuntime runtime, EngineEvents? events)
+ {
+ _storage = storage;
+ _clock = clock;
+ _runtime = runtime;
+ _events = events;
+ }
+
+ /// Raised after every change of state (outside the internal lock). The engine closes the session on it.
+ public event EventHandler? StateChanged;
+
+ /// Current state; a throttle stop that has expired turns into Closed here.
+ public BreakerState State
+ {
+ get
+ {
+ BreakerState state;
+ bool changed;
+ lock (_gate)
+ {
+ changed = ExpireLocked(_clock.Now);
+ state = _state;
+ }
+
+ if (changed)
+ {
+ StateChanged?.Invoke(this, state);
+ }
+
+ return state;
+ }
+ }
+
+ /// Restores the state from the incidents table (open stops, recent throttles, halved budgets).
+ public static async Task LoadAsync(
+ IFebeStorage storage,
+ IClock clock,
+ EngineRuntime runtime,
+ EngineEvents? events = null,
+ CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(storage);
+ ArgumentNullException.ThrowIfNull(clock);
+ ArgumentNullException.ThrowIfNull(runtime);
+ var breaker = new CircuitBreaker(storage, clock, runtime, events);
+ var now = clock.Now;
+
+ var recent = await storage.Incidents.ListAsync(now - ProposalWindow - EscalationWindow, now.AddSeconds(1), ct).ConfigureAwait(false);
+ DateTimeOffset? halvedUntil = null;
+ foreach (var incident in recent.Where(i => i.Level == SignalLevel.Throttle))
+ {
+ breaker._recentThrottles.Add(incident.At);
+ if (incident.StoppedUntil is { } until && until + HalvedPeriod > now && (halvedUntil is null || until + HalvedPeriod > halvedUntil))
+ {
+ halvedUntil = until + HalvedPeriod;
+ }
+ }
+
+ var state = new BreakerState(BreakerStatus.Closed, null, null, halvedUntil);
+ foreach (var incident in await storage.Incidents.ListOpenAsync(ct).ConfigureAwait(false))
+ {
+ var signal = new Signal(incident.Level, incident.Signal, incident.Url, incident.At);
+ switch (incident.Level)
+ {
+ case SignalLevel.Challenge:
+ state = state with { Status = BreakerStatus.Challenge, Until = null, LastSignal = signal };
+ breaker._openIncidents.Add(incident.Id);
+ break;
+ case SignalLevel.Disconnect:
+ state = state with { Status = BreakerStatus.Disconnected, Until = null, LastSignal = signal };
+ breaker._openIncidents.Add(incident.Id);
+ break;
+ case SignalLevel.Throttle when incident.StoppedUntil is { } until && until > now:
+ if (state.Status == BreakerStatus.Closed)
+ {
+ state = state with { Status = BreakerStatus.Throttled, Until = until, LastSignal = signal };
+ }
+
+ breaker._openIncidents.Add(incident.Id);
+ break;
+ default:
+ // An expired throttle left open by a previous process: resolved at its planned end.
+ await storage.Incidents.ResolveAsync(incident.Id, incident.StoppedUntil ?? now, ct).ConfigureAwait(false);
+ break;
+ }
+ }
+
+ breaker._state = state;
+ return breaker;
+ }
+
+ public void Report(Signal signal) => _ = ReportAsync(signal);
+
+ /// Same as , returning when the incident and the event are stored.
+ public Task ReportAsync(Signal signal, CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(signal);
+ BreakerState state;
+ Task persisted;
+ lock (_gate)
+ {
+ var now = _clock.Now;
+ ExpireLocked(now);
+ var sessionId = _runtime.CurrentSession?.SessionId;
+ switch (signal.Level)
+ {
+ case SignalLevel.Throttle:
+ if (_state.Status != BreakerStatus.Closed)
+ {
+ // Already stopped: a late signal of the same stop does not escalate it.
+ return _tail;
+ }
+
+ _recentThrottles.RemoveAll(t => t < now - ProposalWindow);
+ var within24Hours = _recentThrottles.Count(t => t > now - EscalationWindow);
+ var stop = ThrottleStops[Math.Min(within24Hours, ThrottleStops.Count - 1)];
+ _recentThrottles.Add(now);
+ var until = now + stop;
+ _state = new BreakerState(BreakerStatus.Throttled, until, signal, until + HalvedPeriod);
+ var withinWeek = _recentThrottles.Count(t => t > now - ProposalWindow);
+ persisted = EnqueueLocked(c => PersistThrottleAsync(signal, now, until, stop, sessionId, withinWeek, c));
+ break;
+
+ case SignalLevel.Challenge:
+ case SignalLevel.Disconnect:
+ var status = signal.Level == SignalLevel.Challenge ? BreakerStatus.Challenge : BreakerStatus.Disconnected;
+ if (_state.Status == status)
+ {
+ return _tail;
+ }
+
+ var wasThrottled = _state.Status == BreakerStatus.Throttled;
+ _state = new BreakerState(status, null, signal, _state.HalvedBudgetsUntil);
+ persisted = EnqueueLocked(c => PersistManualStopAsync(signal, now, wasThrottled, sessionId, c));
+ break;
+
+ default:
+ throw new ArgumentOutOfRangeException(nameof(signal), signal.Level, null);
+ }
+
+ state = _state;
+ }
+
+ StateChanged?.Invoke(this, state);
+ return persisted;
+ }
+
+ ///
+ /// «Riprendi» after a verification or a disconnection, once Alberto fixed things in the browser. Resolves the open
+ /// incidents and restarts the gradual start. False when the breaker is not in such a stop (a throttle stop has a
+ /// fixed duration and cannot be shortened).
+ ///
+ public async Task ResumeAsync(CancellationToken ct = default)
+ {
+ BreakerState state;
+ Task persisted;
+ lock (_gate)
+ {
+ var now = _clock.Now;
+ if (_state.Status is not (BreakerStatus.Challenge or BreakerStatus.Disconnected))
+ {
+ return false;
+ }
+
+ var previous = _state.Status;
+ _state = _state with { Status = BreakerStatus.Closed, Until = null };
+ _runtime.RampStart = now;
+ persisted = EnqueueLocked(c => PersistResumeAsync(previous, now, c));
+ state = _state;
+ }
+
+ await persisted.WaitAsync(ct).ConfigureAwait(false);
+ StateChanged?.Invoke(this, state);
+ return true;
+ }
+
+ /// Waits until every incident and event reported so far is stored.
+ public Task FlushAsync()
+ {
+ lock (_gate)
+ {
+ return _tail;
+ }
+ }
+
+ private bool ExpireLocked(DateTimeOffset now)
+ {
+ if (_state.Status != BreakerStatus.Throttled || _state.Until is not { } until || now < until)
+ {
+ return false;
+ }
+
+ _state = _state with { Status = BreakerStatus.Closed, Until = null };
+ var halvedUntil = _state.HalvedBudgetsUntil;
+ EnqueueLocked(ct => PersistThrottleEndAsync(until, halvedUntil, ct));
+ return true;
+ }
+
+ private Task EnqueueLocked(Func work)
+ {
+ // Rows are written strictly in order: an incident is opened before it is resolved.
+ _tail = _tail.ContinueWith(_ => work(CancellationToken.None), CancellationToken.None, TaskContinuationOptions.None, TaskScheduler.Default).Unwrap();
+ return _tail;
+ }
+
+ private async Task PersistThrottleAsync(Signal signal, DateTimeOffset now, DateTimeOffset until, TimeSpan stop, long? sessionId, int withinWeek, CancellationToken ct)
+ {
+ var incident = await _storage.Incidents.OpenAsync(
+ new Incident
+ {
+ At = signal.At,
+ Level = SignalLevel.Throttle,
+ Signal = signal.Code,
+ Url = signal.Url,
+ StoppedUntil = until,
+ SessionId = sessionId,
+ },
+ ct).ConfigureAwait(false);
+ lock (_gate)
+ {
+ _openIncidents.Add(incident.Id);
+ }
+
+ if (_events is null)
+ {
+ return;
+ }
+
+ var zone = _clock.LocalZone;
+ await _events.WriteAsync(
+ EventSeverity.Warning,
+ EngineEventCodes.ThrottleStop,
+ $"Instagram ha chiesto di rallentare (segnale {signal.Code}). Ho chiuso la sessione e mi fermo per {ItalianText.Duration(stop)}, "
+ + $"fino {ItalianText.AtDay(until, now, zone)}. Poi i tetti restano dimezzati per 48 ore.",
+ sessionId: sessionId,
+ ct: ct).ConfigureAwait(false);
+
+ if (withinWeek >= ProposalThreshold)
+ {
+ var profile = _runtime.Profile.Kind;
+ var proposal = profile is CautionProfileKind.Prudent
+ ? "Tre rallentamenti in sette giorni anche con il profilo «Prudente»: conviene ridurre gli account seguiti o abbassare le loro frequenze."
+ : $"Tre rallentamenti in sette giorni con il profilo «{ItalianText.Profile(profile)}»: conviene passare al profilo «{ItalianText.Profile(MorePrudent(profile))}» o ridurre gli account seguiti.";
+ await _events.WriteAsync(EventSeverity.Warning, EngineEventCodes.ProposeMorePrudence, proposal, ct: ct).ConfigureAwait(false);
+ }
+ }
+
+ private async Task PersistManualStopAsync(Signal signal, DateTimeOffset now, bool wasThrottled, long? sessionId, CancellationToken ct)
+ {
+ if (wasThrottled)
+ {
+ await ResolveOpenAsync(now, ct).ConfigureAwait(false);
+ }
+
+ var incident = await _storage.Incidents.OpenAsync(
+ new Incident
+ {
+ At = signal.At,
+ Level = signal.Level,
+ Signal = signal.Code,
+ Url = signal.Url,
+ SessionId = sessionId,
+ },
+ ct).ConfigureAwait(false);
+ lock (_gate)
+ {
+ _openIncidents.Add(incident.Id);
+ }
+
+ if (_events is null)
+ {
+ return;
+ }
+
+ var at = ItalianText.At(now, _clock.LocalZone);
+ var message = signal.Level == SignalLevel.Challenge
+ ? $"Instagram chiede una verifica (segnale {signal.Code}). Ho fermato tutto {at} e non riparto da solo: apri il browser, completa la verifica a mano, poi premi «Riprendi»."
+ : $"La sessione di Instagram non c'è più (segnale {signal.Code}). Ho fermato tutto {at} e non provo a rientrare: apri il browser, accedi a mano, poi premi «Riprendi».";
+ await _events.WriteAsync(
+ EventSeverity.Error,
+ signal.Level == SignalLevel.Challenge ? EngineEventCodes.ChallengeStop : EngineEventCodes.DisconnectStop,
+ message,
+ sessionId: sessionId,
+ ct: ct).ConfigureAwait(false);
+ }
+
+ private async Task PersistThrottleEndAsync(DateTimeOffset until, DateTimeOffset? halvedUntil, CancellationToken ct)
+ {
+ await ResolveOpenAsync(until, ct).ConfigureAwait(false);
+ if (_events is null)
+ {
+ return;
+ }
+
+ var tail = halvedUntil is { } h
+ ? $" Riprendo con i tetti dimezzati fino {ItalianText.AtDay(h, until, _clock.LocalZone)}."
+ : " Riprendo con i tetti normali.";
+ await _events.WriteAsync(EventSeverity.Info, EngineEventCodes.ThrottleEnd, "Fine del fermo per rallentamento." + tail, ct: ct).ConfigureAwait(false);
+ }
+
+ private async Task PersistResumeAsync(BreakerStatus previous, DateTimeOffset now, CancellationToken ct)
+ {
+ await ResolveOpenAsync(now, ct).ConfigureAwait(false);
+ await _storage.Settings.SetAsync(
+ EngineSettingKeys.RampStart,
+ now.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture),
+ ct).ConfigureAwait(false);
+ if (_events is null)
+ {
+ return;
+ }
+
+ var profile = _runtime.Profile;
+ var what = previous == BreakerStatus.Challenge ? "Ripresa dopo la verifica." : "Ripresa dopo il nuovo accesso.";
+ var ramp = profile.GradualStart && profile.RampUpDays > 0
+ ? $" I tetti ripartono dalla metà e tornano pieni in {ItalianText.Count(profile.RampUpDays, "giorno", "giorni")}."
+ : string.Empty;
+ await _events.WriteAsync(EventSeverity.Success, EngineEventCodes.Resumed, what + ramp, ct: ct).ConfigureAwait(false);
+ }
+
+ private async Task ResolveOpenAsync(DateTimeOffset at, CancellationToken ct)
+ {
+ long[] open;
+ lock (_gate)
+ {
+ open = [.. _openIncidents];
+ _openIncidents.Clear();
+ }
+
+ foreach (var id in open)
+ {
+ await _storage.Incidents.ResolveAsync(id, at, ct).ConfigureAwait(false);
+ }
+ }
+
+ private static CautionProfileKind MorePrudent(CautionProfileKind kind) => kind switch
+ {
+ CautionProfileKind.Fast => CautionProfileKind.Balanced,
+ _ => CautionProfileKind.Prudent,
+ };
+}
+
+/// Stable codes of the engine's timeline events.
+public static class EngineEventCodes
+{
+ public const string ThrottleStop = "fermo-rallentamento";
+ public const string ThrottleEnd = "fine-fermo";
+ public const string ChallengeStop = "verifica-richiesta";
+ public const string DisconnectStop = "disconnessione";
+ public const string Resumed = "ripresa";
+ public const string ProposeMorePrudence = "proposta-prudenza";
+ public const string Paused = "pausa";
+ public const string Unpaused = "fine-pausa";
+ public const string BudgetReached = "tetto-raggiunto";
+ public const string SessionEnded = "sessione";
+ public const string BackfillCompleted = "storico-completato";
+ public const string BackfillWaiting = "storico-in-attesa";
+ public const string RecipeSuspended = "ricetta-sospesa";
+ public const string RecipeResumed = "ricetta-riattivata";
+ public const string FormatUnrecognized = "formato-non-riconosciuto";
+ public const string TargetNotFound = "bersaglio-non-trovato";
+ public const string AccountUnreachable = "account-non-raggiungibile";
+ public const string AccountPaused = "account-in-pausa";
+ public const string ManualCheck = "controlla-ora";
+ public const string RecipeFailed = "ricetta-fallita";
+ public const string SettingsChanged = "impostazioni-motore";
+
+ /// Prefix of the per-recipe lines («Appena fatto»): "ricetta." + recipe kind.
+ public const string RecipePrefix = "ricetta.";
+}
diff --git a/src/Febe.Core/Engine/DayPlanner.cs b/src/Febe.Core/Engine/DayPlanner.cs
new file mode 100644
index 0000000..27bb565
--- /dev/null
+++ b/src/Febe.Core/Engine/DayPlanner.cs
@@ -0,0 +1,183 @@
+using System.Globalization;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Pacing;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// The active window of one day (spec §7.2): the engine works only inside it. A window belongs to the local day it
+/// starts on and may end after midnight (e.g. 06:30–00:30).
+///
+public sealed record ActiveWindow(DateOnly Day, DateTimeOffset Start, DateTimeOffset End)
+{
+ public TimeSpan Length => End - Start;
+
+ public bool Contains(DateTimeOffset instant) => instant >= Start && instant < End;
+}
+
+///
+/// Plans the active window of every day: the profile's start and end, each shifted every day by a random amount within
+/// ± the profile's jitter (a normal draw with σ = jitter/2 truncated to ± jitter, never uniform), only on active
+/// weekdays. The shifts of a day are derived from a seed drawn once from the engine's random source and persisted, so
+/// they are deterministic per day and a restart never redraws them.
+///
+public sealed class DayPlanner
+{
+ private const double ShiftSigma = 0.5;
+ private static readonly TimeSpan MinimumLength = TimeSpan.FromMinutes(30);
+
+ private readonly ISettingsStore _settings;
+ private readonly IRandomSource _random;
+ private readonly Func _profile;
+ private readonly SemaphoreSlim _seedGate = new(1, 1);
+ private ulong? _seed;
+
+ public DayPlanner(ISettingsStore settings, IRandomSource random, Func profile, TimeZoneInfo zone)
+ {
+ _settings = settings ?? throw new ArgumentNullException(nameof(settings));
+ _random = random ?? throw new ArgumentNullException(nameof(random));
+ _profile = profile ?? throw new ArgumentNullException(nameof(profile));
+ Zone = zone ?? throw new ArgumentNullException(nameof(zone));
+ }
+
+ public TimeZoneInfo Zone { get; }
+
+ /// The window of a local day, or null when the weekday is not active.
+ public async Task GetWindowAsync(DateOnly day, CancellationToken ct = default)
+ {
+ var profile = _profile();
+ if (!profile.ActiveDays.Contains(day.DayOfWeek))
+ {
+ return null;
+ }
+
+ var seed = await GetSeedAsync(ct).ConfigureAwait(false);
+ return Compute(day, profile, seed, Zone);
+ }
+
+ /// The window containing (today's, or yesterday's when it crosses midnight); null at night.
+ public async Task GetWindowAtAsync(DateTimeOffset instant, CancellationToken ct = default)
+ {
+ var today = LocalCalendar.Today(instant, Zone);
+ foreach (var day in new[] { today.AddDays(-1), today })
+ {
+ var window = await GetWindowAsync(day, ct).ConfigureAwait(false);
+ if (window is not null && window.Contains(instant))
+ {
+ return window;
+ }
+ }
+
+ return null;
+ }
+
+ /// The window containing , or the next one to start; null only without active days.
+ public async Task GetNextWindowAsync(DateTimeOffset instant, CancellationToken ct = default)
+ {
+ var today = LocalCalendar.Today(instant, Zone);
+ for (var offset = -1; offset <= 8; offset++)
+ {
+ var window = await GetWindowAsync(today.AddDays(offset), ct).ConfigureAwait(false);
+ if (window is not null && window.End > instant)
+ {
+ return window;
+ }
+ }
+
+ return null;
+ }
+
+ /// The window of a day from a seed: pure, used by the planner and by tests.
+ public static ActiveWindow Compute(DateOnly day, CautionProfile profile, ulong seed, TimeZoneInfo zone)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ var (startShift, endShift) = Shifts(seed, day);
+ var endDay = profile.WindowEnd > profile.WindowStart ? day : day.AddDays(1);
+ var baseStart = LocalCalendar.FromLocal(day.ToDateTime(profile.WindowStart), zone);
+ var baseEnd = LocalCalendar.FromLocal(endDay.ToDateTime(profile.WindowEnd), zone);
+ var start = baseStart + (profile.WindowJitter * startShift);
+ var end = baseEnd + (profile.WindowJitter * endShift);
+ if (end - start < MinimumLength)
+ {
+ end = start + MinimumLength;
+ }
+
+ // Whole seconds: easier to read and to compare with stored times (milliseconds).
+ return new ActiveWindow(day, TruncateToSecond(start), TruncateToSecond(end));
+ }
+
+ /// Daily shifts of start and end as fractions of the jitter, in [-1, 1].
+ internal static (double Start, double End) Shifts(ulong seed, DateOnly day)
+ {
+ var random = new SplitMixRandom(seed ^ ((ulong)day.DayNumber * 0x9E3779B97F4A7C15UL));
+ return (TruncatedNormal(random), TruncatedNormal(random));
+ }
+
+ private static double TruncatedNormal(IRandomSource random)
+ {
+ for (var attempt = 0; attempt < 64; attempt++)
+ {
+ var value = random.Normal(0, ShiftSigma);
+ if (value is >= -1 and <= 1)
+ {
+ return value;
+ }
+ }
+
+ return 0;
+ }
+
+ private static DateTimeOffset TruncateToSecond(DateTimeOffset value) =>
+ new(value.Ticks - (value.Ticks % TimeSpan.TicksPerSecond), value.Offset);
+
+ private async Task GetSeedAsync(CancellationToken ct)
+ {
+ if (_seed is { } known)
+ {
+ return known;
+ }
+
+ await _seedGate.WaitAsync(ct).ConfigureAwait(false);
+ try
+ {
+ if (_seed is { } again)
+ {
+ return again;
+ }
+
+ var text = await _settings.GetAsync(EngineSettingKeys.WindowSeed, ct).ConfigureAwait(false);
+ if (!ulong.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out var seed))
+ {
+ var high = (ulong)(_random.NextDouble() * uint.MaxValue);
+ var low = (ulong)(_random.NextDouble() * uint.MaxValue);
+ seed = (high << 32) | low;
+ await _settings.SetAsync(EngineSettingKeys.WindowSeed, seed.ToString(CultureInfo.InvariantCulture), ct).ConfigureAwait(false);
+ }
+
+ _seed = seed;
+ return seed;
+ }
+ finally
+ {
+ _seedGate.Release();
+ }
+ }
+}
+
+/// SplitMix64: a tiny deterministic generator for values derived from a stored seed.
+internal sealed class SplitMixRandom(ulong seed) : IRandomSource
+{
+ private ulong _state = seed;
+
+ public double NextDouble() => (Next() >> 11) * (1.0 / (1UL << 53));
+
+ private ulong Next()
+ {
+ var z = _state += 0x9E3779B97F4A7C15UL;
+ z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
+ z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
+ return z ^ (z >> 31);
+ }
+}
diff --git a/src/Febe.Core/Engine/EngineEvents.cs b/src/Febe.Core/Engine/EngineEvents.cs
new file mode 100644
index 0000000..b2c88bb
--- /dev/null
+++ b/src/Febe.Core/Engine/EngineEvents.cs
@@ -0,0 +1,122 @@
+using System.Runtime.CompilerServices;
+using System.Threading.Channels;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+/// What changed in the engine, for the interface (the web layer turns these into server-sent events).
+public enum EngineNotificationKind
+{
+ /// A line was added to the Activity timeline ().
+ Event,
+
+ /// The mode of the engine changed (session started or ended, pause, stop, resume...): refresh the snapshot.
+ StateChanged,
+
+ /// A recipe started or ended inside a session: refresh the current activity and the budgets.
+ ActivityChanged,
+}
+
+/// A notification of the engine. Never contains captions, bodies, cookies or signed addresses.
+public sealed record EngineNotification(EngineNotificationKind Kind, DateTimeOffset At, EventRecord? Event = null);
+
+///
+/// Writes the readable timeline (spec §8.3 event) and publishes engine notifications to any number of
+/// subscribers. Slow subscribers lose the oldest notifications, never block the engine.
+///
+public sealed class EngineEvents
+{
+ private const int SubscriberCapacity = 256;
+
+ private readonly IEventStore _store;
+ private readonly IClock _clock;
+ private readonly Lock _gate = new();
+ private readonly List> _subscribers = [];
+
+ public EngineEvents(IEventStore store, IClock clock)
+ {
+ _store = store ?? throw new ArgumentNullException(nameof(store));
+ _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+ }
+
+ /// Raised synchronously for every notification (after the event is stored).
+ public event EventHandler? Notified;
+
+ /// Stores an event of the timeline and publishes it.
+ public async Task WriteAsync(
+ EventSeverity severity,
+ string code,
+ string message,
+ long? accountId = null,
+ long? sessionId = null,
+ CancellationToken ct = default)
+ {
+ var record = await _store.AppendAsync(
+ new EventRecord
+ {
+ At = _clock.Now,
+ Severity = severity,
+ Code = code,
+ Message = message,
+ AccountId = accountId,
+ SessionId = sessionId,
+ },
+ ct).ConfigureAwait(false);
+ Publish(new EngineNotification(EngineNotificationKind.Event, record.At, record));
+ return record;
+ }
+
+ /// Publishes a notification that is not a timeline line.
+ public void Publish(EngineNotificationKind kind) => Publish(new EngineNotification(kind, _clock.Now));
+
+ /// Notifications from now on, until is cancelled.
+ public async IAsyncEnumerable SubscribeAsync([EnumeratorCancellation] CancellationToken ct = default)
+ {
+ var channel = Channel.CreateBounded(new BoundedChannelOptions(SubscriberCapacity)
+ {
+ FullMode = BoundedChannelFullMode.DropOldest,
+ SingleReader = true,
+ SingleWriter = false,
+ });
+ lock (_gate)
+ {
+ _subscribers.Add(channel);
+ }
+
+ try
+ {
+ while (await channel.Reader.WaitToReadAsync(ct).ConfigureAwait(false))
+ {
+ while (channel.Reader.TryRead(out var notification))
+ {
+ yield return notification;
+ }
+ }
+ }
+ finally
+ {
+ lock (_gate)
+ {
+ _subscribers.Remove(channel);
+ }
+ }
+ }
+
+ private void Publish(EngineNotification notification)
+ {
+ Channel[] subscribers;
+ lock (_gate)
+ {
+ subscribers = [.. _subscribers];
+ }
+
+ foreach (var subscriber in subscribers)
+ {
+ subscriber.Writer.TryWrite(notification);
+ }
+
+ Notified?.Invoke(this, notification);
+ }
+}
diff --git a/src/Febe.Core/Engine/EngineHost.cs b/src/Febe.Core/Engine/EngineHost.cs
new file mode 100644
index 0000000..9c2cc0c
--- /dev/null
+++ b/src/Febe.Core/Engine/EngineHost.cs
@@ -0,0 +1,828 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Pacing;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+/// Outcome of «Controlla ora» (spec §7.8).
+public enum CheckNowStatus
+{
+ /// Put on top of the queue.
+ Queued,
+
+ /// Outside the active window: Alberto must confirm with .
+ NeedsConfirmation,
+
+ /// Not possible now (budget exhausted, engine stopped, account not contactable); the message says why.
+ Refused,
+}
+
+/// Answer to «Controlla ora»: an Italian message for the interface and, when needed, a confirmation token.
+public sealed record CheckNowResult(CheckNowStatus Status, string Message, string? ConfirmationToken = null, DateTimeOffset? ExpectedAround = null);
+
+/// Answer to «Riprendi».
+public sealed record ResumeResult(bool Resumed, string Message);
+
+///
+/// The engine (spec §7): a background loop that plans the day, opens sessions inside the active window, composes them
+/// and rests between them. It only uses for time and for chance, so the
+/// same code runs under the virtual clock of the simulation.
+///
+///
+/// Commands from the interface (pause, resume, «Controlla ora», settings) are thread-safe and wake the loop.
+/// While Alberto uses the browser, during a pause and during a stop of the breaker the engine opens nothing.
+///
+public sealed class EngineHost : IAsyncDisposable
+{
+ private static readonly TimeSpan LongWait = TimeSpan.FromHours(6);
+
+ private readonly EngineServices _s;
+ private readonly IRecipeRunner _runner;
+ private readonly RecipeHealth _health;
+ private readonly RecentActions _recent = new();
+ private readonly SessionComposer _composer;
+ private readonly Lock _gate = new();
+ private readonly Dictionary _confirmations = new(StringComparer.Ordinal);
+ private readonly Dictionary _outsideWindowAllowed = [];
+ private CancellationTokenSource _wake = new();
+ private CancellationTokenSource? _sessionCts;
+ private CancellationTokenSource? _loopCts;
+ private Task? _loop;
+ private bool _initialized;
+ private bool _manualWaiting;
+ private DateTimeOffset? _plannedAfterStop;
+
+ public EngineHost(EngineServices services, IRecipeRunner runner)
+ {
+ _s = services ?? throw new ArgumentNullException(nameof(services));
+ _runner = runner ?? throw new ArgumentNullException(nameof(runner));
+ _health = new RecipeHealth(services.Storage.Settings, services.Options.ConsecutiveFailuresToSuspend);
+ _composer = new SessionComposer(services, runner, _health, _recent, ManualDone);
+ Monitor = new EngineMonitor(services, this);
+ _s.Breaker.StateChanged += OnBreakerChanged;
+ }
+
+ public EngineServices Services => _s;
+
+ /// What the interface shows of the engine (Attività, sidebar, account settings panel).
+ public IEngineMonitor Monitor { get; }
+
+ /// Recipes suspended after repeated unrecognized formats, with when.
+ public IReadOnlyDictionary SuspendedRecipes => _health.Suspended;
+
+ internal IReadOnlyList RecentActions(int limit) => _recent.Snapshot(limit);
+
+ /// Starts the background loop.
+ public Task StartAsync(CancellationToken ct = default)
+ {
+ lock (_gate)
+ {
+ if (_loop is not null)
+ {
+ return Task.CompletedTask;
+ }
+
+ _loopCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
+ var token = _loopCts.Token;
+ _loop = Task.Run(() => RunAsync(token), CancellationToken.None);
+ }
+
+ return Task.CompletedTask;
+ }
+
+ /// Stops the loop; a session in progress ends as interrupted and the browser goes to rest.
+ public async Task StopAsync()
+ {
+ Task? loop;
+ lock (_gate)
+ {
+ loop = _loop;
+ _loopCts?.Cancel();
+ }
+
+ if (loop is not null)
+ {
+ try
+ {
+ await loop.ConfigureAwait(false);
+ }
+ catch (OperationCanceledException)
+ {
+ }
+ }
+
+ lock (_gate)
+ {
+ _loop = null;
+ _loopCts?.Dispose();
+ _loopCts = null;
+ }
+ }
+
+ public async ValueTask DisposeAsync()
+ {
+ _s.Breaker.StateChanged -= OnBreakerChanged;
+ await StopAsync().ConfigureAwait(false);
+ _wake.Dispose();
+ }
+
+ ///
+ /// The loop of the engine, until is cancelled. runs it in the
+ /// background; the simulation awaits it directly under the virtual clock.
+ ///
+ public async Task RunAsync(CancellationToken ct)
+ {
+ _s.Runtime.IsRunning = true;
+ try
+ {
+ await InitializeAsync(ct).ConfigureAwait(false);
+ while (true)
+ {
+ ct.ThrowIfCancellationRequested();
+ CancellationToken wake;
+ lock (_gate)
+ {
+ wake = _wake.Token;
+ }
+
+ var wait = await StepAsync(ct).ConfigureAwait(false);
+ if (wait is { } delay && delay > TimeSpan.Zero)
+ {
+ await WaitAsync(delay, wake, ct).ConfigureAwait(false);
+ }
+ }
+ }
+ finally
+ {
+ _s.Runtime.IsRunning = false;
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+ }
+
+ /// «Metti in pausa»: stops the engine until «Riprendi»; a session in progress ends now.
+ public async Task PauseAsync(CancellationToken ct = default)
+ {
+ if (_s.Runtime.IsPaused)
+ {
+ return;
+ }
+
+ _s.Runtime.IsPaused = true;
+ await _s.Storage.Settings.SetBoolAsync(EngineSettingKeys.Paused, true, ct).ConfigureAwait(false);
+ CancelSession();
+ Wake();
+ await _s.Events.WriteAsync(EventSeverity.Info, EngineEventCodes.Paused, "Messo in pausa da te: Febe non apre nulla finché non premi «Riprendi».", ct: ct).ConfigureAwait(false);
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ ///
+ /// «Riprendi»: ends a pause and, after a verification or a disconnection that Alberto fixed in the browser, reopens
+ /// the breaker (with the gradual start). A throttle stop has a fixed length and is not shortened.
+ ///
+ public async Task ResumeAsync(CancellationToken ct = default)
+ {
+ var messages = new List();
+ var resumed = false;
+ var breaker = _s.Breaker.State;
+ if (breaker.Status is BreakerStatus.Challenge or BreakerStatus.Disconnected)
+ {
+ resumed |= await _s.Breaker.ResumeAsync(ct).ConfigureAwait(false);
+ messages.Add(_s.Runtime.Profile.GradualStart ? "Ripreso dopo il fermo: i tetti ripartono dalla metà." : "Ripreso dopo il fermo.");
+ }
+
+ if (_s.Runtime.IsPaused)
+ {
+ _s.Runtime.IsPaused = false;
+ await _s.Storage.Settings.SetBoolAsync(EngineSettingKeys.Paused, false, ct).ConfigureAwait(false);
+ await _s.Events.WriteAsync(EventSeverity.Info, EngineEventCodes.Unpaused, "Ripreso dopo la pausa.", ct: ct).ConfigureAwait(false);
+ messages.Add("Ripreso dopo la pausa.");
+ resumed = true;
+ }
+
+ breaker = _s.Breaker.State;
+ if (breaker.Status == BreakerStatus.Throttled && breaker.Until is { } until)
+ {
+ messages.Add($"Il fermo per rallentamento dura fino {ItalianText.AtDay(until, _s.Clock.Now, _s.Clock.LocalZone)} e non si accorcia.");
+ }
+ else if (resumed)
+ {
+ // The first session after «Riprendi» comes 2–10 minutes later, as after a start.
+ var restart = _s.Clock.Now + _s.Random.Between(_s.Options.StartupDelayMin, _s.Options.StartupDelayMax);
+ if (_s.Runtime.NextSessionAt is not { } planned || planned < restart)
+ {
+ _s.Runtime.NextSessionAt = restart;
+ }
+ }
+
+ Wake();
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ return new ResumeResult(resumed, messages.Count == 0 ? "Febe stava già lavorando." : string.Join(" ", messages));
+ }
+
+ ///
+ /// «Controlla ora» (spec §7.8): puts the check of an account on top of the queue. It still goes through the
+ /// Governor: with an exhausted budget Febe says so and does not do it. Outside the active window the first call
+ /// returns with a token; calling again with the token allows that
+ /// single check.
+ ///
+ public async Task CheckNowAsync(long accountId, string? confirmationToken = null, CancellationToken ct = default)
+ {
+ var now = _s.Clock.Now;
+ var zone = _s.Clock.LocalZone;
+ var account = await _s.Storage.Accounts.GetAsync(accountId, ct).ConfigureAwait(false);
+ if (account is null)
+ {
+ return new CheckNowResult(CheckNowStatus.Refused, "Questo account non c'è più nell'elenco di Febe.");
+ }
+
+ var handle = ItalianText.Handle(account.Username);
+ if (!CheckPolicy.AllowsManualCheck(account))
+ {
+ return new CheckNowResult(
+ CheckNowStatus.Refused,
+ account.State == AccountState.ArchiveOnly
+ ? $"{handle} è «Solo archivio»: Febe non lo contatta."
+ : $"{handle} è privato e non lo segui: Febe non lo apre.");
+ }
+
+ var breaker = _s.Breaker.State;
+ if (!breaker.AllowsSiteActions)
+ {
+ return new CheckNowResult(CheckNowStatus.Refused, Governor.BreakerMessage(breaker, now, zone));
+ }
+
+ if (_s.Runtime.IsPaused)
+ {
+ return new CheckNowResult(CheckNowStatus.Refused, "Febe è in pausa: premi «Riprendi» prima di chiedere un controllo.");
+ }
+
+ var kind = CheckPolicy.WantsProfileChecks(account) ? EngineTaskKind.ProfileCheck : EngineTaskKind.AccountStories;
+ var category = kind == EngineTaskKind.ProfileCheck ? ActionKind.ProfileOpen : ActionKind.StoryView;
+ var budget = await _s.Governor.EvaluateBudgetAsync(category, accountId, ct).ConfigureAwait(false);
+ if (!budget.Granted && budget.Reason != DenialReason.AccountNotContactable)
+ {
+ return new CheckNowResult(CheckNowStatus.Refused, (budget.Message ?? "Tetto raggiunto.") + " Il controllo non parte.");
+ }
+
+ var window = await _s.Planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
+ var floor = PauseFloor();
+ if (window is null)
+ {
+ bool confirmed;
+ lock (_gate)
+ {
+ PruneLocked(now);
+ confirmed = confirmationToken is not null
+ && _confirmations.TryGetValue(confirmationToken, out var pending)
+ && pending.AccountId == accountId;
+ if (confirmed)
+ {
+ _confirmations.Remove(confirmationToken!);
+ _outsideWindowAllowed[accountId] = now + TimeSpan.FromHours(1);
+ }
+ }
+
+ if (!confirmed)
+ {
+ var token = Guid.NewGuid().ToString("N");
+ lock (_gate)
+ {
+ _confirmations[token] = (accountId, now + _s.Options.ManualConfirmationLifetime);
+ }
+
+ var next = await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
+ var resumes = next is null ? string.Empty : $" Di solito riprende {ItalianText.Around(next.Start, now, zone)}.";
+ return new CheckNowResult(
+ CheckNowStatus.NeedsConfirmation,
+ $"Sei fuori dalla fascia oraria, quando Febe non apre nulla da solo.{resumes} Confermi un solo controllo di {handle} adesso?",
+ token);
+ }
+
+ await EnqueueManualAsync(kind, accountId, now, ct).ConfigureAwait(false);
+ var expected = floor is { } f && f > now ? f : now;
+ await _s.Events.WriteAsync(
+ EventSeverity.Info,
+ EngineEventCodes.ManualCheck,
+ $"Controllo di {handle} fuori fascia, confermato da te: parte {(expected > now ? ItalianText.Around(expected, now, zone) : "adesso")}.",
+ accountId,
+ ct: ct).ConfigureAwait(false);
+ Wake();
+ return new CheckNowResult(CheckNowStatus.Queued, $"Controllo di {handle} confermato: è l'unico che Febe fa fuori fascia.", null, expected);
+ }
+
+ await EnqueueManualAsync(kind, accountId, now, ct).ConfigureAwait(false);
+ Wake();
+ if (_s.Runtime.CurrentSession is not null)
+ {
+ return new CheckNowResult(CheckNowStatus.Queued, $"Controllo di {handle} in cima alla coda: parte in questa sessione.", null, now);
+ }
+
+ // The next session comes as soon as the pause floor allows (spec §7.2: the floor always holds).
+ var start = floor is { } minimum && minimum > now ? minimum : now;
+
+ await _s.Events.WriteAsync(
+ EventSeverity.Info,
+ EngineEventCodes.ManualCheck,
+ $"Controllo di {handle} chiesto da te: in cima alla coda.",
+ accountId,
+ ct: ct).ConfigureAwait(false);
+ return new CheckNowResult(
+ CheckNowStatus.Queued,
+ start > now
+ ? $"Controllo di {handle} in cima alla coda: parte {ItalianText.Around(start, now, zone)}, dopo la pausa minima fra due sessioni."
+ : $"Controllo di {handle} in cima alla coda: parte adesso.",
+ null,
+ start);
+ }
+
+ /// «Leggi l'elenco dei seguiti» (spec §4.2): read at human pace inside the budgets, possibly over several sessions.
+ public async Task RequestFollowingListAsync(CancellationToken ct = default)
+ {
+ var now = _s.Clock.Now;
+ Volatile.Write(ref _manualWaiting, true);
+ await _s.Storage.Tasks.EnqueueAsync(
+ new EngineTask
+ {
+ Kind = EngineTaskKind.FollowingList,
+ DueAt = now,
+ Priority = _s.Options.ManualPriority,
+ IsManual = true,
+ CreatedAt = now,
+ },
+ ct).ConfigureAwait(false);
+ Wake();
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ /// Accounts were added, removed or changed: the queue is brought in step before the next session.
+ public async Task NotifyAccountsChangedAsync(CancellationToken ct = default)
+ {
+ await _composer.SyncQueueAsync(ct).ConfigureAwait(false);
+ Wake();
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ /// Alberto started or finished using the browser: when he starts, the session in progress ends at once.
+ public void NotifyUserDrivingChanged()
+ {
+ if (_s.Runtime.UserIsDriving)
+ {
+ CancelSession();
+ }
+
+ Wake();
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ /// Reactivates a recipe suspended after repeated unrecognized formats (after the reader was updated).
+ public async Task ResumeRecipeAsync(RecipeKind kind, CancellationToken ct = default)
+ {
+ var resumed = await _health.ResumeAsync(kind, ct).ConfigureAwait(false);
+ if (resumed)
+ {
+ await _s.Events.WriteAsync(
+ EventSeverity.Info,
+ EngineEventCodes.RecipeResumed,
+ $"«{ItalianText.Capitalize(SessionComposer.RecipeName(kind))}» riattivato.",
+ ct: ct).ConfigureAwait(false);
+ Wake();
+ }
+
+ return resumed;
+ }
+
+ /// Stores and applies new engine settings, then replans.
+ public async Task ApplySettingsAsync(EngineSettings settings, CancellationToken ct = default)
+ {
+ await _s.ApplySettingsAsync(settings, ct).ConfigureAwait(false);
+ Wake();
+ }
+
+ private async Task InitializeAsync(CancellationToken ct)
+ {
+ if (_initialized)
+ {
+ return;
+ }
+
+ var now = _s.Clock.Now;
+ var store = _s.Storage;
+ await _health.LoadAsync(ct).ConfigureAwait(false);
+
+ // A session left open by a process that ended abruptly closes at its last action.
+ var lastAction = await store.ActionLog.GetLastActionAtAsync(null, ct).ConfigureAwait(false);
+ var last = await store.Sessions.GetLastAsync(ct).ConfigureAwait(false);
+ if (last is { EndedAt: null })
+ {
+ var end = lastAction is { } a && a > last.StartedAt && a <= now ? a : last.StartedAt;
+ await store.Sessions.CloseInterruptedAsync(end, ct).ConfigureAwait(false);
+ last = await store.Sessions.GetLastAsync(ct).ConfigureAwait(false);
+ }
+
+ await store.Tasks.RequeueRunningAsync(ct).ConfigureAwait(false);
+
+ // A restart never brings the next session earlier than a program that stayed on would have.
+ var lastEnd = Max(last?.EndedAt, lastAction);
+ _s.Runtime.LastSessionEnd = lastEnd;
+ var persisted = await store.Settings.GetInt64Async(EngineSettingKeys.NextSession, ct).ConfigureAwait(false);
+ var next = now + _s.Random.Between(_s.Options.StartupDelayMin, _s.Options.StartupDelayMax);
+ if (persisted is { } ms && DateTimeOffset.FromUnixTimeMilliseconds(ms) > next)
+ {
+ next = DateTimeOffset.FromUnixTimeMilliseconds(ms);
+ }
+
+ if (PauseFloor() is { } floor && floor > next)
+ {
+ next = floor;
+ }
+
+ _s.Runtime.NextSessionAt = next;
+ _s.Runtime.StartedAt = now;
+ _s.Runtime.HadSessionSinceStart = false;
+ await store.Settings.SetInt64Async(EngineSettingKeys.NextSession, next.ToUnixTimeMilliseconds(), ct).ConfigureAwait(false);
+ await _composer.SyncQueueAsync(ct).ConfigureAwait(false);
+ _initialized = true;
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ /// One turn of the loop: runs a session when one is due, otherwise says how long to wait.
+ private async Task StepAsync(CancellationToken ct)
+ {
+ var now = _s.Clock.Now;
+ var runtime = _s.Runtime;
+ if (runtime.IsPaused)
+ {
+ return LongWait;
+ }
+
+ var breaker = _s.Breaker.State;
+ if (!breaker.AllowsSiteActions)
+ {
+ if (breaker.Status == BreakerStatus.Throttled && breaker.Until is { } until)
+ {
+ // After the stop the engine does not restart on the dot: a few minutes later, as after a start.
+ if (_plannedAfterStop != until)
+ {
+ _plannedAfterStop = until;
+ var restart = until + _s.Random.Between(_s.Options.StartupDelayMin, _s.Options.StartupDelayMax);
+ if (runtime.NextSessionAt is not { } planned || planned < restart)
+ {
+ runtime.NextSessionAt = restart;
+ }
+ }
+
+ return until - now;
+ }
+
+ return LongWait;
+ }
+
+ if (runtime.UserIsDriving || runtime.IsConnected == false)
+ {
+ // Alberto at the browser, or no Instagram session yet: look again in a while.
+ return _s.Options.UserDrivingPoll;
+ }
+
+ var floor = PauseFloor();
+ var window = await _s.Planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
+ if (window is null)
+ {
+ // Night: nothing on the engine's initiative. The only exception is a «Controlla ora» Alberto confirmed.
+ var manual = await FindConfirmedManualAsync(now, ct).ConfigureAwait(false);
+ if (manual is not null)
+ {
+ if (floor is { } f && f > now)
+ {
+ return f - now;
+ }
+
+ await RunSessionAsync(null, manual, ct).ConfigureAwait(false);
+ return null;
+ }
+
+ var next = await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
+ if (next is null)
+ {
+ return LongWait;
+ }
+
+ var target = runtime.NextSessionAt is { } planned && planned > next.Start ? planned : next.Start;
+ if (floor is { } minimum && minimum > target)
+ {
+ target = minimum;
+ }
+
+ runtime.NextSessionAt = target;
+ return target - now;
+ }
+
+ var start = runtime.NextSessionAt ?? now;
+ if (start > now && Volatile.Read(ref _manualWaiting))
+ {
+ // «Controlla ora»: the next session comes as soon as the pause floor allows.
+ start = now;
+ }
+
+ if (floor is { } pauseFloor && pauseFloor > start)
+ {
+ start = pauseFloor;
+ }
+
+ if (start > now)
+ {
+ runtime.NextSessionAt = start;
+ return (start < window.End ? start : window.End) - now;
+ }
+
+ if (window.End - now < _s.Options.MinimumSessionRoom)
+ {
+ return window.End - now;
+ }
+
+ await RunSessionAsync(window, null, ct).ConfigureAwait(false);
+ return null;
+ }
+
+ private async Task RunSessionAsync(ActiveWindow? window, EngineTask? outsideWindowTask, CancellationToken ct)
+ {
+ var s = _s;
+ var profile = s.Runtime.Profile;
+ var start = s.Clock.Now;
+ var mood = s.Random.SessionMood();
+ var plannedEnd = start + s.Random.Between(profile.SessionMin, profile.SessionMax);
+ if (window is not null && plannedEnd > window.End)
+ {
+ plannedEnd = window.End;
+ }
+
+ var record = await s.Storage.Sessions.StartAsync(start, ct).ConfigureAwait(false);
+ var context = new SessionContext(record.Id, mood, start, plannedEnd, outsideWindowTask?.AccountId);
+ using var sessionCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
+ lock (_gate)
+ {
+ _sessionCts = sessionCts;
+ }
+
+ s.Runtime.CurrentSession = context;
+ s.Runtime.HadSessionSinceStart = true;
+ Volatile.Write(ref _manualWaiting, false);
+ s.Runtime.NextSessionAt = null;
+ s.Events.Publish(EngineNotificationKind.StateChanged);
+
+ var outcome = SessionOutcome.Completed;
+ var interrupted = false;
+ try
+ {
+ // A stop that arrived while the session was opening ends it before anything is done.
+ if (!s.Breaker.State.AllowsSiteActions || s.Runtime.IsPaused || s.Runtime.UserIsDriving)
+ {
+ sessionCts.Cancel();
+ }
+
+ var summary = await _composer.RunAsync(context, outsideWindowTask, sessionCts.Token).ConfigureAwait(false);
+ if (summary.StoppedEarly || !s.Breaker.State.AllowsSiteActions || s.Runtime.IsPaused || s.Runtime.UserIsDriving)
+ {
+ outcome = StopOutcome();
+ }
+ }
+ catch (OperationCanceledException) when (!ct.IsCancellationRequested)
+ {
+ outcome = StopOutcome();
+ }
+ catch (OperationCanceledException)
+ {
+ outcome = SessionOutcome.Interrupted;
+ interrupted = true;
+ throw;
+ }
+ catch (Exception ex) when (ex is not OutOfMemoryException)
+ {
+ outcome = SessionOutcome.Failed;
+ await s.Events.WriteAsync(
+ EventSeverity.Error,
+ EngineEventCodes.RecipeFailed,
+ $"La sessione si è chiusa per un errore imprevisto ({ex.GetType().Name}). Riprendo alla prossima.",
+ sessionId: record.Id,
+ ct: CancellationToken.None).ConfigureAwait(false);
+ }
+ finally
+ {
+ lock (_gate)
+ {
+ _sessionCts = null;
+ }
+
+ s.Runtime.CurrentSession = null;
+ s.Runtime.Activity = null;
+ await EndSessionAsync(record, context, outcome, outsideWindowTask, interrupted).ConfigureAwait(false);
+ }
+ }
+
+ private async Task EndSessionAsync(SessionRecord record, SessionContext context, SessionOutcome outcome, EngineTask? outsideWindowTask, bool interrupted)
+ {
+ var s = _s;
+ var ct = CancellationToken.None;
+
+ // Rest on the empty page, except when the page must stay as it is (verification, disconnection) or Alberto is
+ // using the browser (spec §6.1, §7.6).
+ var breaker = s.Breaker.State;
+ var keepPage = breaker.Status is BreakerStatus.Challenge or BreakerStatus.Disconnected || s.Runtime.UserIsDriving;
+ if (!keepPage)
+ {
+ try
+ {
+ await _runner.RestAsync(ct).ConfigureAwait(false);
+ }
+ catch (Exception ex) when (ex is not OutOfMemoryException)
+ {
+ await s.Events.WriteAsync(
+ EventSeverity.Warning,
+ EngineEventCodes.RecipeFailed,
+ $"Non sono riuscito a portare il browser sulla pagina vuota ({ex.GetType().Name}).",
+ sessionId: record.Id,
+ ct: ct).ConfigureAwait(false);
+ }
+ }
+
+ var end = s.Clock.Now;
+ var summaryText = $"{ItalianText.Count(context.ActionCount, "azione", "azioni")}, {ItalianText.Count(context.NewEntries, "contenuto nuovo", "contenuti nuovi")}";
+ var writes = new List { s.Storage.Sessions.EndAsync(record.Id, end, outcome, context.ActionCount, summaryText, ct) };
+ s.Runtime.LastSessionEnd = end;
+ if (outsideWindowTask?.AccountId is { } manualAccount)
+ {
+ ManualDone(manualAccount);
+ }
+
+ if (interrupted)
+ {
+ await Task.WhenAll(writes).ConfigureAwait(false);
+ return;
+ }
+
+ var pause = s.Random.Between(s.Runtime.Profile.PauseMin, s.Runtime.Profile.PauseMax);
+ var next = end + pause;
+ s.Runtime.NextSessionAt = next;
+ writes.Add(s.Storage.Settings.SetInt64Async(EngineSettingKeys.NextSession, next.ToUnixTimeMilliseconds(), ct));
+ if ((await s.Storage.Accounts.ListAsync(ct).ConfigureAwait(false)).Any(a => a.IsFollowed && CheckPolicy.IsContactable(a)))
+ {
+ writes.Add(_composer.EnsureSweepTaskAsync(next, ct));
+ }
+
+ var length = ItalianText.Duration(end - record.StartedAt);
+ var tail = outcome switch
+ {
+ SessionOutcome.Throttled => " Chiusa per un rallentamento chiesto da Instagram.",
+ SessionOutcome.Stopped => " Chiusa prima del previsto.",
+ SessionOutcome.Failed => " Chiusa per un errore.",
+ _ => string.Empty,
+ };
+ writes.Add(s.Events.WriteAsync(
+ outcome == SessionOutcome.Completed ? EventSeverity.Info : EventSeverity.Warning,
+ EngineEventCodes.SessionEnded,
+ $"Sessione di {length}: {summaryText}.{tail}",
+ sessionId: record.Id,
+ ct: ct));
+ await Task.WhenAll(writes).ConfigureAwait(false);
+ s.Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ private SessionOutcome StopOutcome() =>
+ _s.Breaker.State.Status == BreakerStatus.Throttled ? SessionOutcome.Throttled : SessionOutcome.Stopped;
+
+ private DateTimeOffset? PauseFloor() =>
+ _s.Runtime.LastSessionEnd is { } end ? end + _s.Runtime.Profile.PauseMin : null;
+
+ private async Task FindConfirmedManualAsync(DateTimeOffset now, CancellationToken ct)
+ {
+ Dictionary allowed;
+ lock (_gate)
+ {
+ PruneLocked(now);
+ if (_outsideWindowAllowed.Count == 0)
+ {
+ return null;
+ }
+
+ allowed = new Dictionary(_outsideWindowAllowed);
+ }
+
+ var due = await _s.Storage.Tasks.PeekDueAsync(now, 100, ct).ConfigureAwait(false);
+ return due.FirstOrDefault(t => t.IsManual && t.AccountId is { } id && allowed.ContainsKey(id));
+ }
+
+ private void ManualDone(long accountId)
+ {
+ lock (_gate)
+ {
+ _outsideWindowAllowed.Remove(accountId);
+ }
+ }
+
+ private void PruneLocked(DateTimeOffset now)
+ {
+ foreach (var token in _confirmations.Where(c => c.Value.Expires <= now).Select(c => c.Key).ToList())
+ {
+ _confirmations.Remove(token);
+ }
+
+ foreach (var account in _outsideWindowAllowed.Where(c => c.Value <= now).Select(c => c.Key).ToList())
+ {
+ _outsideWindowAllowed.Remove(account);
+ }
+ }
+
+ private async Task EnqueueManualAsync(EngineTaskKind kind, long accountId, DateTimeOffset now, CancellationToken ct)
+ {
+ Volatile.Write(ref _manualWaiting, true);
+ await _s.Storage.Tasks.EnqueueAsync(
+ new EngineTask
+ {
+ Kind = kind,
+ AccountId = accountId,
+ DueAt = now,
+ Priority = _s.Options.ManualPriority,
+ IsManual = true,
+ CreatedAt = now,
+ },
+ ct).ConfigureAwait(false);
+ }
+
+ private void OnBreakerChanged(object? sender, BreakerState state)
+ {
+ // Signals arrive on capture threads: the engine is never run inline on them (it may need the browser to answer).
+ // The composer also checks the breaker before every recipe, so the session stops at once either way.
+ CancellationTokenSource? session = null;
+ if (!state.AllowsSiteActions)
+ {
+ lock (_gate)
+ {
+ session = _sessionCts;
+ }
+ }
+
+ _ = Task.Run(() =>
+ {
+ Cancel(session);
+ Wake();
+ _s.Events.Publish(EngineNotificationKind.StateChanged);
+ });
+ }
+
+ private void CancelSession()
+ {
+ CancellationTokenSource? session;
+ lock (_gate)
+ {
+ session = _sessionCts;
+ }
+
+ Cancel(session);
+ }
+
+ private static void Cancel(CancellationTokenSource? session)
+ {
+ try
+ {
+ session?.Cancel();
+ }
+ catch (ObjectDisposedException)
+ {
+ }
+ }
+
+ /// Wakes the loop if it is waiting; the wait it was in is cancelled synchronously.
+ private void Wake()
+ {
+ CancellationTokenSource old;
+ lock (_gate)
+ {
+ old = _wake;
+ _wake = new CancellationTokenSource();
+ }
+
+ // The old source is not disposed: the loop may still hold its (now cancelled) token.
+ old.Cancel();
+ }
+
+ private async Task WaitAsync(TimeSpan delay, CancellationToken wake, CancellationToken ct)
+ {
+ if (wake.IsCancellationRequested)
+ {
+ return;
+ }
+
+ using var linked = CancellationTokenSource.CreateLinkedTokenSource(ct, wake);
+ try
+ {
+ await _s.Clock.Delay(delay, linked.Token).ConfigureAwait(false);
+ }
+ catch (OperationCanceledException) when (!ct.IsCancellationRequested)
+ {
+ // Woken by a command: look again.
+ }
+ }
+
+ private static DateTimeOffset? Max(DateTimeOffset? a, DateTimeOffset? b) =>
+ a is null ? b : b is null ? a : a > b ? a : b;
+}
diff --git a/src/Febe.Core/Engine/EngineOptions.cs b/src/Febe.Core/Engine/EngineOptions.cs
new file mode 100644
index 0000000..f979df3
--- /dev/null
+++ b/src/Febe.Core/Engine/EngineOptions.cs
@@ -0,0 +1,71 @@
+namespace Febe.Core.Engine;
+
+///
+/// Tuning of the engine that is not part of a caution profile. Values marked «ipotesi» depend on how Instagram
+/// behaves and must be confirmed in M0 (spec §6.6, rule 10): they are configuration, not facts.
+///
+public sealed record EngineOptions
+{
+ public static EngineOptions Default { get; } = new();
+
+ ///
+ /// Ipotesi da confermare in M0 (H3): posts loaded by one page of history. Used only to estimate how many pages
+ /// the per-account daily backfill limit allows and how many days a backfill needs; the Governor counts real posts.
+ ///
+ public int PostsPerBackfillPage { get; init; } = 12;
+
+ ///
+ /// Ipotesi da confermare in M0 (H2): the stories bar read by the Giro dei seguiti tells which followed profiles
+ /// have active stories, so a completed sweep counts as a story check of every followed account it did not flag.
+ /// With false, followed accounts get explicit story checks at their interval.
+ ///
+ public bool SweepCoversFollowedStories { get; init; } = true;
+
+ /// «Lo storico non corre più veloce dei download» (spec §6.3): backfill of an account waits above this many pending files.
+ public int BackfillMaxPendingDownloads { get; init; } = 60;
+
+ /// Minimum distance between two counted actions at the «naturale» gesture pace (spec §7.2); scaled by the pace.
+ public TimeSpan MinimumSpacing { get; init; } = TimeSpan.FromSeconds(4);
+
+ /// The first session starts 2–10 minutes after the program (spec §7.2).
+ public TimeSpan StartupDelayMin { get; init; } = TimeSpan.FromMinutes(2);
+
+ public TimeSpan StartupDelayMax { get; init; } = TimeSpan.FromMinutes(10);
+
+ /// «Una sessione comincia di norma con il Giro dei seguiti»: probability of opening with the sweep.
+ public double SweepProbability { get; init; } = 0.9;
+
+ /// «Circa una su tre si limita al giro e alle storie».
+ public double LightSessionProbability { get; init; } = 1.0 / 3.0;
+
+ /// «Qualche pagina di storico» per session: drawn in this range (log-normal), then limited by the account's daily maximum.
+ public int BackfillPagesMin { get; init; } = 3;
+
+ public int BackfillPagesMax { get; init; } = 12;
+
+ /// Wait between two recipes of a session («fra un account e l'altro da 1 a 4 s»), times mood and pace.
+ public TimeSpan BetweenRecipesMin { get; init; } = TimeSpan.FromSeconds(1);
+
+ public TimeSpan BetweenRecipesMax { get; init; } = TimeSpan.FromSeconds(4);
+
+ /// Consecutive «formato non riconosciuto» (or «bersaglio non trovato») outcomes that suspend a recipe (spec §6.4).
+ public int ConsecutiveFailuresToSuspend { get; init; } = 3;
+
+ /// How long a «Controlla ora» confirmation token stays valid outside the active window (spec §7.8).
+ public TimeSpan ManualConfirmationLifetime { get; init; } = TimeSpan.FromMinutes(10);
+
+ /// How often the idle engine looks again whether Alberto has finished using the browser.
+ public TimeSpan UserDrivingPoll { get; init; } = TimeSpan.FromSeconds(30);
+
+ /// A session does not start when less than this remains of the active window.
+ public TimeSpan MinimumSessionRoom { get; init; } = TimeSpan.FromMinutes(1);
+
+ /// With «Storie» on, every account gets at least this many story checks per day inside the window (spec §7.3).
+ public int MinimumStoryChecksPerDay { get; init; } = 3;
+
+ /// Priority of «Controlla ora» and of other commands of Alberto in the queue.
+ public int ManualPriority { get; init; } = 100;
+
+ /// Priority of story checks flagged by the stories bar.
+ public int FlaggedStoriesPriority { get; init; } = 10;
+}
diff --git a/src/Febe.Core/Engine/EngineRuntime.cs b/src/Febe.Core/Engine/EngineRuntime.cs
new file mode 100644
index 0000000..4132c0d
--- /dev/null
+++ b/src/Febe.Core/Engine/EngineRuntime.cs
@@ -0,0 +1,170 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+
+namespace Febe.Core.Engine;
+
+///
+/// Live state shared by the engine host, the Governor, the circuit breaker and the monitor. Everything that must
+/// survive a restart is persisted by its owner; this object only mirrors it in memory. Thread-safe.
+///
+public sealed class EngineRuntime
+{
+ private readonly Lock _gate = new();
+ private readonly Func _userIsDriving;
+ private readonly Func? _isConnected;
+ private CautionProfile _profile = CautionProfile.Prudent;
+ private DateTimeOffset? _rampStart;
+ private SessionContext? _session;
+ private string? _activity;
+ private DateTimeOffset? _nextSessionAt;
+ private DateTimeOffset? _lastSessionEnd;
+ private bool _paused;
+ private bool _running;
+
+ /// True while Alberto uses the browser ().
+ /// Whether the Instagram session exists in the browser; null when unknown.
+ public EngineRuntime(Func? userIsDriving = null, Func? isConnected = null)
+ {
+ _userIsDriving = userIsDriving ?? (() => false);
+ _isConnected = isConnected;
+ }
+
+ /// The effective caution profile (settings applied).
+ public CautionProfile Profile
+ {
+ get { lock (_gate) { return _profile; } }
+ set { lock (_gate) { _profile = value ?? throw new ArgumentNullException(nameof(value)); } }
+ }
+
+ /// Start of the gradual start: first connection or last resolved verification/disconnection.
+ public DateTimeOffset? RampStart
+ {
+ get { lock (_gate) { return _rampStart; } }
+ set { lock (_gate) { _rampStart = value; } }
+ }
+
+ /// «Metti in pausa» is active.
+ public bool IsPaused
+ {
+ get { lock (_gate) { return _paused; } }
+ set { lock (_gate) { _paused = value; } }
+ }
+
+ /// True while Alberto uses the browser: the engine does not act.
+ public bool UserIsDriving => _userIsDriving();
+
+ /// Whether the browser holds an Instagram session; null when the host does not say.
+ public bool? IsConnected => _isConnected?.Invoke();
+
+ /// The session in progress, if any. The Governor refuses every site action without one.
+ public SessionContext? CurrentSession
+ {
+ get { lock (_gate) { return _session; } }
+ set { lock (_gate) { _session = value; } }
+ }
+
+ /// What the engine is doing now, in Italian («Sto guardando le storie di @marta.demo»).
+ public string? Activity
+ {
+ get { lock (_gate) { return _activity; } }
+ set { lock (_gate) { _activity = value; } }
+ }
+
+ /// Planned start of the next session (indicative: «verso le»).
+ public DateTimeOffset? NextSessionAt
+ {
+ get { lock (_gate) { return _nextSessionAt; } }
+ set { lock (_gate) { _nextSessionAt = value; } }
+ }
+
+ /// End of the last session (the pause floor counts from here).
+ public DateTimeOffset? LastSessionEnd
+ {
+ get { lock (_gate) { return _lastSessionEnd; } }
+ set { lock (_gate) { _lastSessionEnd = value; } }
+ }
+
+ /// The background loop of the engine is running.
+ public bool IsRunning
+ {
+ get { lock (_gate) { return _running; } }
+ set { lock (_gate) { _running = value; } }
+ }
+
+ /// When the loop started (the first session comes 2–10 minutes later).
+ public DateTimeOffset? StartedAt
+ {
+ get { lock (_gate) { return _startedAt; } }
+ set { lock (_gate) { _startedAt = value; } }
+ }
+
+ /// A session has started since the loop started.
+ public bool HadSessionSinceStart
+ {
+ get { lock (_gate) { return _hadSession; } }
+ set { lock (_gate) { _hadSession = value; } }
+ }
+
+ private DateTimeOffset? _startedAt;
+ private bool _hadSession;
+}
+
+/// The session in progress (spec §7.2), handed to every recipe.
+public sealed class SessionContext : ISessionContext
+{
+ private int _actions;
+ private int _newEntries;
+ private long _manualAccountId = -1;
+
+ public SessionContext(long sessionId, double mood, DateTimeOffset startedAt, DateTimeOffset plannedEnd, long? outsideWindowAccountId = null)
+ {
+ SessionId = sessionId;
+ Mood = mood;
+ StartedAt = startedAt;
+ PlannedEnd = plannedEnd;
+ OutsideWindowAccountId = outsideWindowAccountId;
+ if (outsideWindowAccountId is { } id)
+ {
+ _manualAccountId = id;
+ }
+ }
+
+ ///
+ /// The account of the «Controlla ora» being run, if any: a paused or unreachable account (not private and
+ /// unfollowed, not «Solo archivio») may be checked on Alberto's request.
+ ///
+ public long? ManualAccountId
+ {
+ get
+ {
+ var value = Interlocked.Read(ref _manualAccountId);
+ return value < 0 ? null : value;
+ }
+
+ internal set => Interlocked.Exchange(ref _manualAccountId, value ?? OutsideWindowAccountId ?? -1);
+ }
+
+ public long SessionId { get; }
+
+ public double Mood { get; }
+
+ public DateTimeOffset StartedAt { get; }
+
+ public DateTimeOffset PlannedEnd { get; }
+
+ ///
+ /// Set only for a «Controlla ora» confirmed by Alberto outside the active window (spec §7.8): the Governor allows
+ /// actions on this account only, and only during this session.
+ ///
+ public long? OutsideWindowAccountId { get; }
+
+ /// Counted actions granted in this session.
+ public int ActionCount => Volatile.Read(ref _actions);
+
+ /// New entries reported by the recipes of this session.
+ public int NewEntries => Volatile.Read(ref _newEntries);
+
+ internal void CountAction() => Interlocked.Increment(ref _actions);
+
+ internal void AddNewEntries(int count) => Interlocked.Add(ref _newEntries, count);
+}
diff --git a/src/Febe.Core/Engine/EngineServices.cs b/src/Febe.Core/Engine/EngineServices.cs
new file mode 100644
index 0000000..dbbe7ca
--- /dev/null
+++ b/src/Febe.Core/Engine/EngineServices.cs
@@ -0,0 +1,148 @@
+using System.Globalization;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// The parts of the engine that recipes and the interface need before the engine host exists: runtime state,
+/// timeline, day planner, circuit breaker and Governor. Built in two steps because the real recipe runner needs the
+/// Governor and the breaker, and the host needs the recipe runner:
+///
+/// var services = await EngineServices.CreateAsync(storage, clock, random);
+/// var runner = new SomeRecipeRunner(services.Governor, services.Breaker, ...);
+/// await using var engine = new EngineHost(services, runner);
+/// await engine.StartAsync(ct);
+///
+///
+public sealed class EngineServices
+{
+ private EngineServices(
+ IFebeStorage storage,
+ IClock clock,
+ IRandomSource random,
+ EngineOptions options,
+ EngineRuntime runtime,
+ EngineEvents events,
+ DayPlanner planner,
+ CircuitBreaker breaker,
+ Governor governor,
+ EngineSettings settings)
+ {
+ Storage = storage;
+ Clock = clock;
+ Random = random;
+ Options = options;
+ Runtime = runtime;
+ Events = events;
+ Planner = planner;
+ Breaker = breaker;
+ Governor = governor;
+ Settings = settings;
+ }
+
+ public IFebeStorage Storage { get; }
+
+ public IClock Clock { get; }
+
+ public IRandomSource Random { get; }
+
+ public EngineOptions Options { get; }
+
+ public EngineRuntime Runtime { get; }
+
+ public EngineEvents Events { get; }
+
+ public DayPlanner Planner { get; }
+
+ public CircuitBreaker Breaker { get; }
+
+ /// The Governor: for recipes, for the download queue.
+ public Governor Governor { get; }
+
+ /// Current engine and caution settings.
+ public EngineSettings Settings { get; private set; }
+
+ ///
+ /// Loads settings, pause flag, gradual-start origin and breaker state from the database. When the gradual start has
+ /// no origin yet (first run after the first connection) it starts now.
+ ///
+ /// The database.
+ /// Time source (virtual in tests and simulation).
+ /// Random source (seeded in tests and simulation).
+ /// Tuning; when null.
+ /// True while Alberto uses the browser.
+ /// Whether the browser holds an Instagram session; null when unknown.
+ /// Cancellation.
+ public static async Task CreateAsync(
+ IFebeStorage storage,
+ IClock clock,
+ IRandomSource random,
+ EngineOptions? options = null,
+ Func? userIsDriving = null,
+ Func? isConnected = null,
+ CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(storage);
+ ArgumentNullException.ThrowIfNull(clock);
+ ArgumentNullException.ThrowIfNull(random);
+ options ??= EngineOptions.Default;
+
+ var runtime = new EngineRuntime(userIsDriving, isConnected);
+ var settings = await EngineSettingsStore.LoadAsync(storage.Settings, ct).ConfigureAwait(false);
+ runtime.Profile = settings.EffectiveProfile;
+ runtime.IsPaused = await storage.Settings.GetBoolAsync(EngineSettingKeys.Paused, false, ct).ConfigureAwait(false);
+
+ var rampStart = await storage.Settings.GetInt64Async(EngineSettingKeys.RampStart, ct).ConfigureAwait(false);
+ if (rampStart is null)
+ {
+ rampStart = clock.Now.ToUnixTimeMilliseconds();
+ await storage.Settings.SetInt64Async(EngineSettingKeys.RampStart, rampStart, ct).ConfigureAwait(false);
+ }
+
+ runtime.RampStart = DateTimeOffset.FromUnixTimeMilliseconds(rampStart.Value);
+
+ var events = new EngineEvents(storage.Events, clock);
+ var planner = new DayPlanner(storage.Settings, random, () => runtime.Profile, clock.LocalZone);
+
+ // Draws (or loads) the seed of the daily windows now, so that later readers never consume randomness.
+ await planner.GetNextWindowAsync(clock.Now, ct).ConfigureAwait(false);
+ var breaker = await CircuitBreaker.LoadAsync(storage, clock, runtime, events, ct).ConfigureAwait(false);
+ var governor = new Governor(storage, breaker, runtime, planner, clock, options, events);
+ return new EngineServices(storage, clock, random, options, runtime, events, planner, breaker, governor, settings);
+ }
+
+ ///
+ /// Validates and stores new engine settings (mockup 07) and applies them at once. Throws
+ /// with Italian messages when a value is outside the limits of spec §7.5.
+ ///
+ public async Task ApplySettingsAsync(EngineSettings settings, CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(settings);
+ await EngineSettingsStore.SaveAsync(Storage.Settings, settings, ct).ConfigureAwait(false);
+ Settings = settings;
+ Runtime.Profile = settings.EffectiveProfile;
+
+ await Events.WriteAsync(
+ EventSeverity.Info,
+ EngineEventCodes.SettingsChanged,
+ $"Impostazioni del motore cambiate: profilo «{ItalianText.Profile(settings.ProfileKind)}».",
+ ct: ct).ConfigureAwait(false);
+ Events.Publish(EngineNotificationKind.StateChanged);
+ }
+
+ ///
+ /// The first connection to Instagram (spec §7.2): the gradual start begins now. Later connections do not restart it;
+ /// the resume after a verification or a disconnection does, through .
+ ///
+ public async Task NotifyFirstConnectionAsync(CancellationToken ct = default)
+ {
+ var now = Clock.Now;
+ Runtime.RampStart = now;
+ await Storage.Settings.SetAsync(
+ EngineSettingKeys.RampStart,
+ now.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture),
+ ct).ConfigureAwait(false);
+ }
+}
diff --git a/src/Febe.Core/Engine/EngineSettings.cs b/src/Febe.Core/Engine/EngineSettings.cs
new file mode 100644
index 0000000..5529b34
--- /dev/null
+++ b/src/Febe.Core/Engine/EngineSettings.cs
@@ -0,0 +1,379 @@
+using System.Globalization;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+/// Setting keys of the engine (spec §8.3 setting). Values are invariant-culture text.
+public static class EngineSettingKeys
+{
+ /// Caution profile kind: Prudent, Balanced, Fast or Custom.
+ public const string Profile = "motore.profilo";
+
+ /// Values of the «Su misura» profile, as compact JSON.
+ public const string CustomProfile = "motore.profilo-su-misura";
+
+ /// «Ritmo dei gesti»: Slow, Natural, Brisk.
+ public const string Pace = "motore.ritmo-gesti";
+
+ /// «Avvio graduale» on or off.
+ public const string GradualStart = "motore.avvio-graduale";
+
+ /// Active weekdays as digits 0 (Sunday) … 6 (Saturday), e.g. "0123456".
+ public const string ActiveDays = "motore.giorni-attivi";
+
+ /// «Metti in pausa»: true while the engine is paused by Alberto.
+ public const string Paused = "motore.in-pausa";
+
+ /// Start of the gradual start (first connection, last resolved verification), Unix milliseconds.
+ public const string RampStart = "motore.avvio-graduale-dal";
+
+ /// Planned start of the next session, Unix milliseconds: a restart never brings it earlier.
+ public const string NextSession = "motore.prossima-sessione";
+
+ /// Seed of the daily shifts of the active window: a restart does not redraw them.
+ public const string WindowSeed = "motore.fascia-seme";
+
+ /// Recipes suspended after repeated unrecognized formats: "Kind=ms;Kind=ms".
+ public const string SuspendedRecipes = "motore.ricette-sospese";
+
+ /// Consecutive failures per recipe: "Kind=n;Kind=n".
+ public const string RecipeFailures = "motore.ricette-errori-consecutivi";
+
+ /// Last completed Giro dei seguiti, Unix milliseconds (it read the stories bar of every followed account).
+ public const string LastSweep = "motore.ultimo-giro";
+}
+
+///
+/// Engine and caution settings chosen by Alberto (mockup 07): profile, «Su misura» values, gesture pace, gradual
+/// start, active days.
+///
+public sealed record EngineSettings
+{
+ public static readonly IReadOnlySet AllDays = new HashSet(Enum.GetValues());
+
+ public CautionProfileKind ProfileKind { get; init; } = CautionProfileKind.Prudent;
+
+ /// Values of the «Su misura» profile; used when is Custom.
+ public CautionProfile? Custom { get; init; }
+
+ public GesturePace Pace { get; init; } = GesturePace.Natural;
+
+ public bool GradualStart { get; init; } = true;
+
+ public IReadOnlySet ActiveDays { get; init; } = AllDays;
+
+ /// The profile the engine applies: preset or custom values, with pace, gradual start and active days.
+ public CautionProfile EffectiveProfile
+ {
+ get
+ {
+ var basis = ProfileKind == CautionProfileKind.Custom
+ ? (Custom ?? CautionProfile.Prudent) with { Kind = CautionProfileKind.Custom }
+ : CautionProfile.For(ProfileKind);
+ return basis with { Pace = Pace, GradualStart = GradualStart, ActiveDays = ActiveDays };
+ }
+ }
+
+ /// A modified value turns the profile into «Su misura» (spec §7.5).
+ public EngineSettings WithCustomValues(CautionProfile values) =>
+ this with { ProfileKind = CautionProfileKind.Custom, Custom = values with { Kind = CautionProfileKind.Custom } };
+}
+
+/// Reads and writes in the settings table.
+public static class EngineSettingsStore
+{
+ public static async Task LoadAsync(ISettingsStore store, CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(store);
+ var all = await store.GetAllAsync(ct).ConfigureAwait(false);
+ var settings = new EngineSettings();
+ if (all.TryGetValue(EngineSettingKeys.Profile, out var kindText) && Enum.TryParse(kindText, out var kind))
+ {
+ settings = settings with { ProfileKind = kind };
+ }
+
+ if (all.TryGetValue(EngineSettingKeys.CustomProfile, out var customText))
+ {
+ settings = settings with { Custom = CautionProfileCodec.TryDecode(customText) };
+ }
+
+ if (all.TryGetValue(EngineSettingKeys.Pace, out var paceText) && Enum.TryParse(paceText, out var pace))
+ {
+ settings = settings with { Pace = pace };
+ }
+
+ if (all.TryGetValue(EngineSettingKeys.GradualStart, out var gradualText) && bool.TryParse(gradualText, out var gradual))
+ {
+ settings = settings with { GradualStart = gradual };
+ }
+
+ if (all.TryGetValue(EngineSettingKeys.ActiveDays, out var daysText))
+ {
+ var days = ParseDays(daysText);
+ if (days.Count > 0)
+ {
+ settings = settings with { ActiveDays = days };
+ }
+ }
+
+ if (settings.ProfileKind == CautionProfileKind.Custom && settings.Custom is null)
+ {
+ settings = settings with { ProfileKind = CautionProfileKind.Prudent };
+ }
+
+ return settings;
+ }
+
+ /// Validates and stores the settings. Throws with Italian messages when a value is outside the limits of spec §7.5.
+ public static async Task SaveAsync(ISettingsStore store, EngineSettings settings, CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(store);
+ ArgumentNullException.ThrowIfNull(settings);
+ var errors = CautionProfileRules.Validate(settings.EffectiveProfile);
+ if (settings.ActiveDays.Count == 0)
+ {
+ errors = [.. errors, "Serve almeno un giorno attivo."];
+ }
+
+ if (errors.Count > 0)
+ {
+ throw new ArgumentException(string.Join(" ", errors), nameof(settings));
+ }
+
+ await store.SetManyAsync(
+ new Dictionary
+ {
+ [EngineSettingKeys.Profile] = settings.ProfileKind.ToString(),
+ [EngineSettingKeys.CustomProfile] = settings.Custom is null ? null : CautionProfileCodec.Encode(settings.Custom),
+ [EngineSettingKeys.Pace] = settings.Pace.ToString(),
+ [EngineSettingKeys.GradualStart] = settings.GradualStart ? "true" : "false",
+ [EngineSettingKeys.ActiveDays] = FormatDays(settings.ActiveDays),
+ },
+ ct).ConfigureAwait(false);
+ }
+
+ internal static string FormatDays(IReadOnlySet days) =>
+ string.Concat(days.OrderBy(d => (int)d).Select(d => ((int)d).ToString(CultureInfo.InvariantCulture)));
+
+ internal static HashSet ParseDays(string text)
+ {
+ var days = new HashSet();
+ foreach (var c in text)
+ {
+ if (c is >= '0' and <= '6')
+ {
+ days.Add((DayOfWeek)(c - '0'));
+ }
+ }
+
+ return days;
+ }
+}
+
+/// Limits of what the interface accepts for a profile (spec §7.5).
+public static class CautionProfileRules
+{
+ /// Largest daily jitter of the window that makes sense.
+ public static readonly TimeSpan MaxJitter = TimeSpan.FromHours(2);
+
+ public const int MaxRampUpDays = 30;
+
+ /// Length of the active window before the daily shift (crossing midnight when the end is not after the start).
+ public static TimeSpan WindowLength(TimeOnly start, TimeOnly end)
+ {
+ var length = end.ToTimeSpan() - start.ToTimeSpan();
+ return length <= TimeSpan.Zero ? length + TimeSpan.FromDays(1) : length;
+ }
+
+ /// Italian messages for every value outside the limits; empty when the profile is acceptable.
+ public static IReadOnlyList Validate(CautionProfile profile)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ var errors = new List();
+ if (profile.PauseMin < CautionProfile.Limits.MinPause)
+ {
+ errors.Add("La pausa minima non può scendere sotto i 5 minuti.");
+ }
+
+ if (profile.PauseMax < profile.PauseMin)
+ {
+ errors.Add("La pausa massima deve essere almeno pari alla minima.");
+ }
+
+ if (profile.SessionMin < TimeSpan.FromMinutes(1))
+ {
+ errors.Add("Una sessione dura almeno 1 minuto.");
+ }
+
+ if (profile.SessionMax > CautionProfile.Limits.MaxSession)
+ {
+ errors.Add("Una sessione non può durare più di 30 minuti.");
+ }
+
+ if (profile.SessionMax < profile.SessionMin)
+ {
+ errors.Add("La durata massima di una sessione deve essere almeno pari alla minima.");
+ }
+
+ var window = WindowLength(profile.WindowStart, profile.WindowEnd);
+ if (window > CautionProfile.Limits.MaxWindow)
+ {
+ errors.Add("La fascia oraria non può superare le 20 ore.");
+ }
+
+ if (profile.WindowJitter < TimeSpan.Zero || profile.WindowJitter > MaxJitter)
+ {
+ errors.Add("Lo spostamento giornaliero della fascia va da 0 a 2 ore.");
+ }
+
+ foreach (var kind in Enum.GetValues())
+ {
+ if (kind == ActionKind.DataDownload)
+ {
+ continue;
+ }
+
+ if (!profile.Budgets.TryGetValue(kind, out var budget))
+ {
+ errors.Add($"Manca il tetto delle {ItalianText.Category(kind)}.");
+ continue;
+ }
+
+ var max = CautionProfile.Limits.MaxBudget(kind);
+ if (budget.PerHour < 0 || budget.PerDay < 0)
+ {
+ errors.Add($"Il tetto delle {ItalianText.Category(kind)} non può essere negativo.");
+ }
+ else if (budget.PerHour > max.PerHour || budget.PerDay > max.PerDay)
+ {
+ errors.Add(
+ $"Il tetto delle {ItalianText.Category(kind)} non può superare il doppio di «Rapido» ({ItalianText.Number(max.PerHour)} all'ora, {ItalianText.Number(max.PerDay)} al giorno).");
+ }
+ }
+
+ if (profile.DataPerDayBytes < 0 || profile.DataPerDayBytes > CautionProfile.Limits.MaxDataPerDayBytes)
+ {
+ errors.Add($"I dati scaricati al giorno non possono superare il doppio di «Rapido» ({ItalianText.Bytes(CautionProfile.Limits.MaxDataPerDayBytes)}).");
+ }
+
+ var maxBackfill = CautionProfile.Fast.BackfillPostsPerAccountPerDay * 2;
+ if (profile.BackfillPostsPerAccountPerDay < 0 || profile.BackfillPostsPerAccountPerDay > maxBackfill)
+ {
+ errors.Add($"Lo storico per account al giorno non può superare il doppio di «Rapido» ({ItalianText.Number(maxBackfill)} post).");
+ }
+
+ if (profile.RampUpDays < 0 || profile.RampUpDays > MaxRampUpDays)
+ {
+ errors.Add("L'avvio graduale dura da 0 a 30 giorni.");
+ }
+
+ if (profile.ActiveDays.Count == 0)
+ {
+ errors.Add("Serve almeno un giorno attivo.");
+ }
+
+ return errors;
+ }
+}
+
+///
+/// Compact JSON of a «Su misura» profile. Written with (no reflection serializer), so it keeps
+/// working in a trimmed single-file build.
+///
+public static class CautionProfileCodec
+{
+ public static string Encode(CautionProfile profile)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ var budgets = new JsonObject();
+ foreach (var (kind, budget) in profile.Budgets.OrderBy(b => b.Key))
+ {
+ budgets[kind.ToString()] = new JsonArray(budget.PerHour, budget.PerDay);
+ }
+
+ var json = new JsonObject
+ {
+ ["windowStart"] = profile.WindowStart.ToString("HH:mm", CultureInfo.InvariantCulture),
+ ["windowEnd"] = profile.WindowEnd.ToString("HH:mm", CultureInfo.InvariantCulture),
+ ["jitterMin"] = profile.WindowJitter.TotalMinutes,
+ ["sessionMinMin"] = profile.SessionMin.TotalMinutes,
+ ["sessionMaxMin"] = profile.SessionMax.TotalMinutes,
+ ["pauseMinMin"] = profile.PauseMin.TotalMinutes,
+ ["pauseMaxMin"] = profile.PauseMax.TotalMinutes,
+ ["budgets"] = budgets,
+ ["dataPerDayBytes"] = profile.DataPerDayBytes,
+ ["backfillPerAccount"] = profile.BackfillPostsPerAccountPerDay,
+ ["rampUpDays"] = profile.RampUpDays,
+ };
+ return json.ToJsonString();
+ }
+
+ /// Null when the text is not a valid profile (it then falls back to «Prudente»).
+ public static CautionProfile? TryDecode(string? text)
+ {
+ if (string.IsNullOrWhiteSpace(text))
+ {
+ return null;
+ }
+
+ try
+ {
+ if (JsonNode.Parse(text) is not JsonObject json)
+ {
+ return null;
+ }
+
+ var budgets = new Dictionary();
+ if (json["budgets"] is JsonObject budgetNode)
+ {
+ foreach (var (key, value) in budgetNode)
+ {
+ if (Enum.TryParse(key, out var kind) && value is JsonArray { Count: 2 } pair)
+ {
+ budgets[kind] = new Budget(pair[0]!.GetValue(), pair[1]!.GetValue());
+ }
+ }
+ }
+
+ foreach (var kind in Enum.GetValues())
+ {
+ if (kind != ActionKind.DataDownload && !budgets.ContainsKey(kind))
+ {
+ budgets[kind] = CautionProfile.Prudent.Budgets[kind];
+ }
+ }
+
+ if (json["windowStart"] is not JsonValue start || json["windowEnd"] is not JsonValue end)
+ {
+ return null;
+ }
+
+ return new CautionProfile
+ {
+ Kind = CautionProfileKind.Custom,
+ WindowStart = TimeOnly.ParseExact(start.GetValue(), "HH:mm", CultureInfo.InvariantCulture),
+ WindowEnd = TimeOnly.ParseExact(end.GetValue(), "HH:mm", CultureInfo.InvariantCulture),
+ WindowJitter = TimeSpan.FromMinutes(Number(json, "jitterMin")),
+ SessionMin = TimeSpan.FromMinutes(Number(json, "sessionMinMin")),
+ SessionMax = TimeSpan.FromMinutes(Number(json, "sessionMaxMin")),
+ PauseMin = TimeSpan.FromMinutes(Number(json, "pauseMinMin")),
+ PauseMax = TimeSpan.FromMinutes(Number(json, "pauseMaxMin")),
+ Budgets = budgets,
+ DataPerDayBytes = (long)Number(json, "dataPerDayBytes"),
+ BackfillPostsPerAccountPerDay = (int)Number(json, "backfillPerAccount"),
+ RampUpDays = (int)Number(json, "rampUpDays"),
+ };
+ }
+ catch (Exception ex) when (ex is JsonException or FormatException or InvalidOperationException or KeyNotFoundException)
+ {
+ return null;
+ }
+ }
+
+ private static double Number(JsonObject json, string key) =>
+ json[key] is JsonValue value ? value.GetValue() : throw new KeyNotFoundException(key);
+}
diff --git a/src/Febe.Core/Engine/Governor.cs b/src/Febe.Core/Engine/Governor.cs
new file mode 100644
index 0000000..0be953c
--- /dev/null
+++ b/src/Febe.Core/Engine/Governor.cs
@@ -0,0 +1,410 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Pacing;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// The Governor (spec §7.4): the single point through which every engine action toward the site passes (rule 7).
+/// For every request it checks, in order: breaker state, pause and Alberto using the browser, active window, session
+/// in progress, hourly (rolling 60 minutes) and daily (local calendar day) budget of the category, minimum spacing from
+/// the previous counted action, the account's own limits. Counts come from action_log, never from memory, so a
+/// restart resets nothing. Granted actions are recorded there with session and account.
+///
+///
+/// The minimum spacing is a pace, not a refusal: waits for it (on )
+/// and then grants; reports it as .
+/// CDN downloads are not site actions: only checks the daily byte budget, also
+/// during a stop (spec §7.6: queued downloads may complete), and bytes are recorded with .
+///
+public sealed class Governor : IGovernor, IDataBudget
+{
+ private static readonly TimeSpan Hour = TimeSpan.FromMinutes(60);
+
+ private readonly IFebeStorage _storage;
+ private readonly ICircuitBreaker _breaker;
+ private readonly EngineRuntime _runtime;
+ private readonly DayPlanner _planner;
+ private readonly IClock _clock;
+ private readonly EngineOptions _options;
+ private readonly EngineEvents? _events;
+ private readonly SemaphoreSlim _gate = new(1, 1);
+ private readonly Lock _noticeGate = new();
+ private readonly HashSet<(ActionKind, DateOnly)> _dailyNoticesSent = [];
+
+ public Governor(
+ IFebeStorage storage,
+ ICircuitBreaker breaker,
+ EngineRuntime runtime,
+ DayPlanner planner,
+ IClock clock,
+ EngineOptions? options = null,
+ EngineEvents? events = null)
+ {
+ _storage = storage ?? throw new ArgumentNullException(nameof(storage));
+ _breaker = breaker ?? throw new ArgumentNullException(nameof(breaker));
+ _runtime = runtime ?? throw new ArgumentNullException(nameof(runtime));
+ _planner = planner ?? throw new ArgumentNullException(nameof(planner));
+ _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+ _options = options ?? EngineOptions.Default;
+ _events = events;
+ }
+
+ /// Raised for every refusal of (the monitor shows the last one).
+ public event EventHandler? Denied;
+
+ /// Raised for every granted site action.
+ public event EventHandler? Granted;
+
+ /// Minimum distance between two counted actions at the current gesture pace.
+ public TimeSpan MinimumSpacing => _options.MinimumSpacing * GesturePaceFactors.For(_runtime.Profile.Pace);
+
+ /// Budgets in force at : profile, gradual start and halved budgets, strongest reduction.
+ public EffectiveBudgets GetEffectiveBudgets(DateTimeOffset now) =>
+ BudgetLimits.Compute(_runtime.Profile, _runtime.RampStart, _breaker.State.HalvedBudgetsUntil, now);
+
+ public async Task RequestAsync(ActionKind kind, long? accountId, CancellationToken ct)
+ {
+ if (kind == ActionKind.DataDownload)
+ {
+ return await EvaluateDataAsync(accountId, ct).ConfigureAwait(false);
+ }
+
+ await _gate.WaitAsync(ct).ConfigureAwait(false);
+ try
+ {
+ while (true)
+ {
+ var now = _clock.Now;
+ var permit = await EvaluateCoreAsync(kind, accountId, now, ct).ConfigureAwait(false);
+ if (permit.Reason == DenialReason.MinimumSpacing && permit.RetryAfter is { } retry)
+ {
+ // Spacing is a pace: wait for it, then look again (the state may have changed meanwhile).
+ await _clock.Delay(retry - now, ct).ConfigureAwait(false);
+ continue;
+ }
+
+ if (!permit.Granted)
+ {
+ Denied?.Invoke(this, permit);
+ await NoticeDailyBudgetAsync(permit, now, ct).ConfigureAwait(false);
+ return permit;
+ }
+
+ var session = _runtime.CurrentSession;
+ await _storage.ActionLog.AppendAsync(
+ new ActionLogRecord { At = now, Category = kind, AccountId = accountId, SessionId = session?.SessionId },
+ ct).ConfigureAwait(false);
+ session?.CountAction();
+ Granted?.Invoke(this, permit);
+ return permit;
+ }
+ }
+ finally
+ {
+ _gate.Release();
+ }
+ }
+
+ ///
+ /// What would answer now, without recording or waiting (spacing is reported as a
+ /// refusal with its retry time). The scheduler uses it to skip work whose budget is exhausted.
+ ///
+ public Task EvaluateAsync(ActionKind kind, long? accountId, CancellationToken ct = default) =>
+ kind == ActionKind.DataDownload
+ ? EvaluateDataAsync(accountId, ct)
+ : EvaluateCoreAsync(kind, accountId, _clock.Now, ct);
+
+ /// Budget checks only (no breaker, window, session or spacing): «is there room today for this?».
+ public async Task EvaluateBudgetAsync(ActionKind kind, long? accountId, CancellationToken ct = default)
+ {
+ if (kind == ActionKind.DataDownload)
+ {
+ return await EvaluateDataAsync(accountId, ct).ConfigureAwait(false);
+ }
+
+ var now = _clock.Now;
+ return await CheckBudgetsAsync(kind, accountId, now, GetEffectiveBudgets(now), ct).ConfigureAwait(false)
+ ?? Permit.Grant(kind, accountId);
+ }
+
+ ///
+ /// How many more actions of a category the budgets allow right now (the smaller of the hourly and daily rest).
+ /// For recipes that need room for several actions, e.g. «the budget must allow at least ten stories» (spec §6.3).
+ ///
+ public async Task RemainingAsync(ActionKind kind, CancellationToken ct = default)
+ {
+ if (kind == ActionKind.DataDownload)
+ {
+ return await RemainingTodayAsync(ct).ConfigureAwait(false);
+ }
+
+ var now = _clock.Now;
+ var budget = GetEffectiveBudgets(now).Budgets[kind];
+ var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, _clock.LocalZone);
+ var tick = TimeSpan.FromMilliseconds(1);
+ var today = await _storage.ActionLog.SumAsync(kind, dayStart, dayEnd, ct: ct).ConfigureAwait(false);
+ var lastHour = await _storage.ActionLog.SumAsync(kind, now - Hour + tick, now + tick, ct: ct).ConfigureAwait(false);
+ return Math.Max(0, Math.Min(budget.PerDay - today, budget.PerHour - lastHour));
+ }
+
+ /// Use of every category with the limits in force (spec §7.4, §7.9).
+ public async Task> GetBudgetStatusAsync(CancellationToken ct = default)
+ {
+ var now = _clock.Now;
+ var budgets = GetEffectiveBudgets(now);
+ var usage = await _storage.ActionLog.GetUsageAsync(now, _clock.LocalZone, ct).ConfigureAwait(false);
+ return [.. Enum.GetValues().Select(kind =>
+ {
+ var used = usage.TryGetValue(kind, out var u) ? u : default;
+ return kind == ActionKind.DataDownload
+ ? new BudgetStatus(kind, used.Today, budgets.DataPerDayBytes, null, null)
+ : new BudgetStatus(kind, used.Today, budgets.Budgets[kind].PerDay, used.LastHour, budgets.Budgets[kind].PerHour);
+ })];
+ }
+
+ public async Task RemainingTodayAsync(CancellationToken ct)
+ {
+ var now = _clock.Now;
+ var (start, end) = LocalCalendar.DayBounds(now, _clock.LocalZone);
+ var used = await _storage.ActionLog.SumAsync(ActionKind.DataDownload, start, end, ct: ct).ConfigureAwait(false);
+ return Math.Max(0, GetEffectiveBudgets(now).DataPerDayBytes - used);
+ }
+
+ public async Task RecordAsync(long bytes, long? accountId, CancellationToken ct)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(bytes);
+ if (bytes == 0)
+ {
+ return;
+ }
+
+ await _storage.ActionLog.AppendAsync(
+ new ActionLogRecord
+ {
+ At = _clock.Now,
+ Category = ActionKind.DataDownload,
+ AccountId = accountId,
+ SessionId = _runtime.CurrentSession?.SessionId,
+ Amount = bytes,
+ },
+ ct).ConfigureAwait(false);
+ }
+
+ private async Task EvaluateDataAsync(long? accountId, CancellationToken ct)
+ {
+ var remaining = await RemainingTodayAsync(ct).ConfigureAwait(false);
+ if (remaining > 0)
+ {
+ return Permit.Grant(ActionKind.DataDownload, accountId);
+ }
+
+ var now = _clock.Now;
+ var limit = GetEffectiveBudgets(now).DataPerDayBytes;
+ return Permit.Deny(
+ ActionKind.DataDownload,
+ accountId,
+ DenialReason.DailyBudgetReached,
+ $"Raggiunto il tetto giornaliero dei dati scaricati ({ItalianText.Bytes(limit)}): gli scaricamenti riprendono domani.",
+ LocalCalendar.DayBounds(now, _clock.LocalZone).End);
+ }
+
+ private async Task EvaluateCoreAsync(ActionKind kind, long? accountId, DateTimeOffset now, CancellationToken ct)
+ {
+ var zone = _clock.LocalZone;
+
+ // 1. Breaker.
+ var breaker = _breaker.State;
+ if (!breaker.AllowsSiteActions)
+ {
+ return Permit.Deny(kind, accountId, DenialReason.BreakerOpen, BreakerMessage(breaker, now, zone), breaker.Until);
+ }
+
+ // Pause and Alberto at the browser: the engine does not act.
+ if (_runtime.IsPaused)
+ {
+ return Permit.Deny(kind, accountId, DenialReason.Paused, "Febe è in pausa: premi «Riprendi» per ripartire.");
+ }
+
+ if (_runtime.UserIsDriving)
+ {
+ return Permit.Deny(kind, accountId, DenialReason.UserIsDriving, "Stai usando il browser di Febe: il motore aspetta che tu abbia finito.");
+ }
+
+ // 2. Active window; the only exception is a «Controlla ora» confirmed outside it, for that account only.
+ var session = _runtime.CurrentSession;
+ var manualOutside = session?.OutsideWindowAccountId is { } manualAccount && accountId == manualAccount;
+ if (!manualOutside)
+ {
+ var window = await _planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
+ if (window is null)
+ {
+ var next = await _planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
+ var when = next is null ? "nei giorni attivi" : ItalianText.Around(next.Start, now, zone);
+ return Permit.Deny(kind, accountId, DenialReason.OutsideActiveWindow, $"Fuori dalla fascia oraria: Febe riprende {when}.", next?.Start);
+ }
+ }
+
+ // 3. Session in progress.
+ if (session is null)
+ {
+ return Permit.Deny(kind, accountId, DenialReason.NoSession, "Nessuna sessione in corso: le azioni verso il sito partono solo dentro una sessione.");
+ }
+
+ // 4. Budgets of the category, then 5. spacing, then 6. the account's own limits.
+ var budgets = GetEffectiveBudgets(now);
+ var denial = await CheckCategoryBudgetsAsync(kind, accountId, now, budgets, ct).ConfigureAwait(false);
+ if (denial is not null)
+ {
+ return denial;
+ }
+
+ var last = await _storage.ActionLog.GetLastActionAtAsync(null, ct).ConfigureAwait(false);
+ var spacing = MinimumSpacing;
+ if (last is { } previous && now - previous < spacing)
+ {
+ return Permit.Deny(
+ kind,
+ accountId,
+ DenialReason.MinimumSpacing,
+ $"Troppo vicino all'azione precedente: fra due azioni passano almeno {ItalianText.Decimal(spacing.TotalSeconds, 1)} secondi.",
+ previous + spacing);
+ }
+
+ return await CheckAccountAsync(kind, accountId, now, budgets, session, ct).ConfigureAwait(false)
+ ?? Permit.Grant(kind, accountId);
+ }
+
+ private async Task CheckBudgetsAsync(ActionKind kind, long? accountId, DateTimeOffset now, EffectiveBudgets budgets, CancellationToken ct) =>
+ await CheckCategoryBudgetsAsync(kind, accountId, now, budgets, ct).ConfigureAwait(false)
+ ?? await CheckAccountAsync(kind, accountId, now, budgets, _runtime.CurrentSession, ct).ConfigureAwait(false);
+
+ private async Task CheckCategoryBudgetsAsync(ActionKind kind, long? accountId, DateTimeOffset now, EffectiveBudgets budgets, CancellationToken ct)
+ {
+ var zone = _clock.LocalZone;
+ var budget = budgets.Budgets[kind];
+ var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, zone);
+ var today = await _storage.ActionLog.SumAsync(kind, dayStart, dayEnd, ct: ct).ConfigureAwait(false);
+ var tick = TimeSpan.FromMilliseconds(1);
+
+ // Rolling window (now − 60 min, now], in the milliseconds of the database.
+ var lastHour = await _storage.ActionLog.SumAsync(kind, now - Hour + tick, now + tick, ct: ct).ConfigureAwait(false);
+ var used = new BudgetUsage(lastHour, today);
+ if (used.Today + 1 > budget.PerDay)
+ {
+ var tomorrow = LocalCalendar.DayBounds(now, zone).End;
+ var next = await _planner.GetNextWindowAsync(tomorrow, ct).ConfigureAwait(false);
+ var retry = next is null || next.Start < tomorrow ? tomorrow : next.Start;
+ return Permit.Deny(
+ kind,
+ accountId,
+ DenialReason.DailyBudgetReached,
+ $"Raggiunto il tetto giornaliero delle {ItalianText.Category(kind)} ({ItalianText.Number(budget.PerDay)} al giorno): la categoria riprende domani.",
+ retry);
+ }
+
+ if (used.LastHour + 1 > budget.PerHour)
+ {
+ var retry = await HourlyRetryAsync(kind, now, budget.PerHour, ct).ConfigureAwait(false);
+ return Permit.Deny(
+ kind,
+ accountId,
+ DenialReason.HourlyBudgetReached,
+ $"Raggiunto il tetto orario delle {ItalianText.Category(kind)} ({ItalianText.Number(budget.PerHour)} all'ora): la categoria riprende {ItalianText.Around(retry, now, zone)}.",
+ retry);
+ }
+
+ return null;
+ }
+
+ private async Task CheckAccountAsync(
+ ActionKind kind,
+ long? accountId,
+ DateTimeOffset now,
+ EffectiveBudgets budgets,
+ SessionContext? session,
+ CancellationToken ct)
+ {
+ if (accountId is not { } id)
+ {
+ return null;
+ }
+
+ var account = await _storage.Accounts.GetAsync(id, ct).ConfigureAwait(false);
+ if (account is null)
+ {
+ return Permit.Deny(kind, accountId, DenialReason.AccountNotContactable, "Questo account non c'è più nell'elenco di Febe.");
+ }
+
+ var manual = session?.ManualAccountId == id;
+ if (!CheckPolicy.IsContactable(account) && !(manual && CheckPolicy.AllowsManualCheck(account)))
+ {
+ return Permit.Deny(kind, accountId, DenialReason.AccountNotContactable, NotContactableMessage(account));
+ }
+
+ if (kind == ActionKind.BackfillPage)
+ {
+ var zone = _clock.LocalZone;
+ var limit = Math.Min(account.Limits.BackfillPostsPerDay, budgets.BackfillPostsPerAccountPerDay);
+ var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, zone);
+ var today = await _storage.Entries.CountDiscoveredAsync(id, EntryKind.Post, dayStart, dayEnd, ct).ConfigureAwait(false);
+ if (today >= limit)
+ {
+ return Permit.Deny(
+ kind,
+ accountId,
+ DenialReason.AccountLimitReached,
+ $"Raggiunto il limite di storico di {ItalianText.Handle(account.Username)} per oggi ({ItalianText.Number(limit)} post): riprende domani.",
+ dayEnd);
+ }
+ }
+
+ return null;
+ }
+
+ /// When the oldest action that keeps the rolling hour full leaves the window.
+ private async Task HourlyRetryAsync(ActionKind kind, DateTimeOffset now, int perHour, CancellationToken ct)
+ {
+ var recent = await _storage.ActionLog.ListAsync(now - Hour, now.AddMilliseconds(1), ct).ConfigureAwait(false);
+ var times = recent.Where(r => r.Category == kind && r.At > now - Hour).Select(r => r.At).OrderBy(t => t).ToList();
+ var excess = times.Count - perHour;
+ return excess >= 0 && excess < times.Count ? times[excess] + Hour : now + TimeSpan.FromMinutes(1);
+ }
+
+ private async Task NoticeDailyBudgetAsync(Permit permit, DateTimeOffset now, CancellationToken ct)
+ {
+ if (_events is null || permit.Reason != DenialReason.DailyBudgetReached)
+ {
+ return;
+ }
+
+ var day = LocalCalendar.Today(now, _clock.LocalZone);
+ lock (_noticeGate)
+ {
+ if (!_dailyNoticesSent.Add((permit.Kind, day)))
+ {
+ return;
+ }
+ }
+
+ await _events.WriteAsync(EventSeverity.Info, EngineEventCodes.BudgetReached, permit.Message ?? string.Empty, ct: ct).ConfigureAwait(false);
+ }
+
+ internal static string BreakerMessage(BreakerState state, DateTimeOffset now, TimeZoneInfo zone) => state.Status switch
+ {
+ BreakerStatus.Throttled when state.Until is { } until =>
+ $"Instagram ha chiesto di rallentare: Febe è fermo fino {ItalianText.AtDay(until, now, zone)}.",
+ BreakerStatus.Challenge => "Instagram chiede una verifica: Febe è fermo finché non la completi nel browser e premi «Riprendi».",
+ BreakerStatus.Disconnected => "La sessione di Instagram è chiusa: Febe è fermo finché non accedi di nuovo nel browser e premi «Riprendi».",
+ _ => "Febe è fermo.",
+ };
+
+ private static string NotContactableMessage(Account account) => account.State switch
+ {
+ AccountState.ArchiveOnly => $"{ItalianText.Handle(account.Username)} è «Solo archivio»: Febe non lo contatta.",
+ AccountState.Paused => $"{ItalianText.Handle(account.Username)} è in pausa: Febe non lo controlla.",
+ AccountState.Unreachable => $"{ItalianText.Handle(account.Username)} non è raggiungibile: Febe non lo contatta.",
+ _ => $"Febe non contatta {ItalianText.Handle(account.Username)}.",
+ };
+}
diff --git a/src/Febe.Core/Engine/ItalianText.cs b/src/Febe.Core/Engine/ItalianText.cs
new file mode 100644
index 0000000..29bee2f
--- /dev/null
+++ b/src/Febe.Core/Engine/ItalianText.cs
@@ -0,0 +1,237 @@
+using System.Globalization;
+using System.Text;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+
+namespace Febe.Core.Engine;
+
+///
+/// Italian wording used by the engine for events, denials and the monitor (spec §10.4): dot for thousands, comma for
+/// decimals, «verso le» for future engine times. Independent of the process culture, so it reads the same in Docker
+/// (invariant globalization) and on Windows.
+///
+public static class ItalianText
+{
+ private static readonly string[] Months =
+ [
+ "gennaio", "febbraio", "marzo", "aprile", "maggio", "giugno",
+ "luglio", "agosto", "settembre", "ottobre", "novembre", "dicembre",
+ ];
+
+ private static readonly string[] Weekdays = ["domenica", "lunedì", "martedì", "mercoledì", "giovedì", "venerdì", "sabato"];
+
+ /// Whole number with dots for thousands: 7.682.
+ public static string Number(long value)
+ {
+ var digits = Math.Abs(value).ToString(CultureInfo.InvariantCulture);
+ var builder = new StringBuilder();
+ if (value < 0)
+ {
+ builder.Append('-');
+ }
+
+ for (var i = 0; i < digits.Length; i++)
+ {
+ if (i > 0 && (digits.Length - i) % 3 == 0)
+ {
+ builder.Append('.');
+ }
+
+ builder.Append(digits[i]);
+ }
+
+ return builder.ToString();
+ }
+
+ /// Decimal number with a comma: 1,3. Trailing zeros of the decimals are kept only when asked.
+ public static string Decimal(double value, int decimals = 1, bool keepZeros = false)
+ {
+ var rounded = Math.Round(value, decimals, MidpointRounding.AwayFromZero);
+ var whole = (long)Math.Truncate(rounded);
+ var fraction = Math.Abs(rounded - whole);
+ var text = Number(whole);
+ if (whole == 0 && rounded < 0)
+ {
+ text = "-0";
+ }
+
+ if (decimals <= 0)
+ {
+ return text;
+ }
+
+ var fractionDigits = ((long)Math.Round(fraction * Math.Pow(10, decimals))).ToString(CultureInfo.InvariantCulture).PadLeft(decimals, '0');
+ if (!keepZeros)
+ {
+ fractionDigits = fractionDigits.TrimEnd('0');
+ }
+
+ return fractionDigits.Length == 0 ? text : text + "," + fractionDigits;
+ }
+
+ /// Byte amount: «850 MB», «1,3 GB».
+ public static string Bytes(long bytes)
+ {
+ const double KB = 1024;
+ const double MB = KB * 1024;
+ const double GB = MB * 1024;
+ return bytes switch
+ {
+ >= (long)GB => Decimal(bytes / GB, 1) + " GB",
+ >= (long)MB => Decimal(bytes / MB, bytes >= 100 * MB ? 0 : 1) + " MB",
+ >= (long)KB => Decimal(bytes / KB, 0) + " kB",
+ _ => Number(bytes) + " byte",
+ };
+ }
+
+ /// Local clock time without a leading zero on the hour: «7:42», «15:30».
+ public static string Clock(DateTimeOffset instant, TimeZoneInfo zone)
+ {
+ var local = LocalCalendar.ToLocal(instant, zone);
+ return local.Hour.ToString(CultureInfo.InvariantCulture) + ":" + local.Minute.ToString("00", CultureInfo.InvariantCulture);
+ }
+
+ /// «alle 17:32», «all'1:05».
+ public static string At(DateTimeOffset instant, TimeZoneInfo zone) =>
+ (LocalCalendar.ToLocal(instant, zone).Hour == 1 ? "all'" : "alle ") + Clock(instant, zone);
+
+ /// «dalle 16:32», «dall'1:05».
+ public static string Since(DateTimeOffset instant, TimeZoneInfo zone) =>
+ (LocalCalendar.ToLocal(instant, zone).Hour == 1 ? "dall'" : "dalle ") + Clock(instant, zone);
+
+ ///
+ /// A future engine time, always indicative (spec §7.9): «verso le 15:30», «domani verso le 7:42»,
+ /// «giovedì verso le 7:42», «il 21 ottobre verso le 7:42».
+ ///
+ public static string Around(DateTimeOffset instant, DateTimeOffset now, TimeZoneInfo zone)
+ {
+ var hour = LocalCalendar.ToLocal(instant, zone).Hour;
+ var time = (hour == 1 ? "verso l'" : "verso le ") + Clock(instant, zone);
+ var prefix = DayPrefix(instant, now, zone);
+ return prefix.Length == 0 ? time : prefix + " " + time;
+ }
+
+ /// «alle 17:32», «domani alle 7:42»: a fixed future time (e.g. the end of a throttle stop).
+ public static string AtDay(DateTimeOffset instant, DateTimeOffset now, TimeZoneInfo zone)
+ {
+ var prefix = DayPrefix(instant, now, zone);
+ var at = At(instant, zone);
+ return prefix.Length == 0 ? at : prefix + " " + at;
+ }
+
+ /// «13 ottobre».
+ public static string Day(DateOnly day) => day.Day.ToString(CultureInfo.InvariantCulture) + " " + Months[day.Month - 1];
+
+ /// «lunedì 13 ottobre».
+ public static string DayWithWeekday(DateOnly day) => Weekdays[(int)day.DayOfWeek] + " " + Day(day);
+
+ /// A duration in words: «45 minuti», «1 ora e 20 minuti», «2 giorni e 3 ore», «30 secondi».
+ public static string Duration(TimeSpan span)
+ {
+ if (span < TimeSpan.Zero)
+ {
+ span = TimeSpan.Zero;
+ }
+
+ if (span < TimeSpan.FromMinutes(1))
+ {
+ var seconds = (long)Math.Round(span.TotalSeconds);
+ return seconds == 1 ? "1 secondo" : Number(seconds) + " secondi";
+ }
+
+ if (span < TimeSpan.FromHours(1))
+ {
+ return Minutes((long)Math.Round(span.TotalMinutes));
+ }
+
+ if (span < TimeSpan.FromDays(2))
+ {
+ var totalMinutes = (long)Math.Round(span.TotalMinutes);
+ var hours = totalMinutes / 60;
+ var minutes = totalMinutes % 60;
+ var text = hours == 1 ? "1 ora" : Number(hours) + " ore";
+ return minutes == 0 ? text : text + " e " + Minutes(minutes);
+ }
+
+ var totalHours = (long)Math.Round(span.TotalHours);
+ var days = totalHours / 24;
+ var restHours = totalHours % 24;
+ var dayText = days == 1 ? "1 giorno" : Number(days) + " giorni";
+ return restHours == 0 ? dayText : dayText + " e " + (restHours == 1 ? "1 ora" : Number(restHours) + " ore");
+ }
+
+ /// An interval of a check («ogni 3 ore», «ogni 75 minuti», «ogni giorno»).
+ public static string Every(TimeSpan interval)
+ {
+ if (interval >= TimeSpan.FromHours(23.5) && interval <= TimeSpan.FromHours(24.5))
+ {
+ return "ogni giorno";
+ }
+
+ if (interval < TimeSpan.FromHours(2) && interval.TotalMinutes % 60 != 0)
+ {
+ return "ogni " + Minutes((long)Math.Round(interval.TotalMinutes));
+ }
+
+ var hours = interval.TotalHours;
+ if (Math.Abs(hours - Math.Round(hours)) < 0.05)
+ {
+ var whole = (long)Math.Round(hours);
+ return whole == 1 ? "ogni ora" : "ogni " + Number(whole) + " ore";
+ }
+
+ return "ogni " + Decimal(hours, 1) + " ore";
+ }
+
+ /// Italian name of a budget category, as in the table of spec §7.5.
+ public static string Category(ActionKind kind) => kind switch
+ {
+ ActionKind.Home => "aperture della home",
+ ActionKind.ProfileOpen => "profili aperti",
+ ActionKind.StoryView => "storie viste",
+ ActionKind.BackfillPage => "pagine di storico",
+ ActionKind.SinglePost => "post singoli",
+ ActionKind.FollowingListPage => "pagine dell'elenco dei seguiti",
+ ActionKind.DataDownload => "dati scaricati",
+ _ => kind.ToString(),
+ };
+
+ /// Category name with a capital initial, for labels: «Profili aperti».
+ public static string CategoryLabel(ActionKind kind) => Capitalize(Category(kind));
+
+ /// Italian name of a caution profile: «Prudente».
+ public static string Profile(CautionProfileKind kind) => kind switch
+ {
+ CautionProfileKind.Prudent => "Prudente",
+ CautionProfileKind.Balanced => "Equilibrato",
+ CautionProfileKind.Fast => "Rapido",
+ CautionProfileKind.Custom => "Su misura",
+ _ => kind.ToString(),
+ };
+
+ /// «@marta.demo».
+ public static string Handle(string? username) => string.IsNullOrWhiteSpace(username) ? "un account" : "@" + username.TrimStart('@');
+
+ /// Count with its noun: «1 storia nuova», «3 storie nuove».
+ public static string Count(long count, string singular, string plural) =>
+ count == 1 ? "1 " + singular : Number(count) + " " + plural;
+
+ public static string Capitalize(string text) =>
+ string.IsNullOrEmpty(text) ? text : char.ToUpperInvariant(text[0]) + text[1..];
+
+ private static string Minutes(long minutes) => minutes == 1 ? "1 minuto" : Number(minutes) + " minuti";
+
+ private static string DayPrefix(DateTimeOffset instant, DateTimeOffset now, TimeZoneInfo zone)
+ {
+ var day = LocalCalendar.Today(instant, zone);
+ var today = LocalCalendar.Today(now, zone);
+ var difference = day.DayNumber - today.DayNumber;
+ return difference switch
+ {
+ <= 0 => string.Empty,
+ 1 => "domani",
+ < 7 => Weekdays[(int)day.DayOfWeek],
+ _ => "il " + Day(day),
+ };
+ }
+}
diff --git a/src/Febe.Core/Engine/Monitor.cs b/src/Febe.Core/Engine/Monitor.cs
new file mode 100644
index 0000000..cd6c116
--- /dev/null
+++ b/src/Febe.Core/Engine/Monitor.cs
@@ -0,0 +1,536 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// Builds the snapshot of the engine for the interface. Reads only: it never draws from the engine's random source,
+/// so watching the engine does not change what it does. Future times are indicative and written «verso le».
+///
+public sealed class EngineMonitor : IEngineMonitor
+{
+ private static readonly ActionKind[] Main = [ActionKind.ProfileOpen, ActionKind.StoryView, ActionKind.BackfillPage, ActionKind.DataDownload];
+
+ private readonly EngineServices _s;
+ private readonly EngineHost _host;
+
+ internal EngineMonitor(EngineServices services, EngineHost host)
+ {
+ _s = services;
+ _host = host;
+ }
+
+ public IAsyncEnumerable SubscribeAsync(CancellationToken ct = default) => _s.Events.SubscribeAsync(ct);
+
+ public async Task GetSnapshotAsync(CancellationToken ct = default)
+ {
+ var now = _s.Clock.Now;
+ var zone = _s.Clock.LocalZone;
+ var runtime = _s.Runtime;
+ var breaker = _s.Breaker.State;
+ var profile = runtime.Profile;
+ var window = await _s.Planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
+ var nextWindow = window ?? await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
+ var session = runtime.CurrentSession;
+ var mode = ModeOf(runtime, breaker, session, window);
+ var resumes = ResumesAround(mode, runtime, breaker, nextWindow, now);
+ var (headline, details, sidebar) = Texts(mode, runtime, breaker, session, resumes, now, zone);
+
+ var budgets = _s.Governor.GetEffectiveBudgets(now);
+ var statuses = await _s.Governor.GetBudgetStatusAsync(ct).ConfigureAwait(false);
+ var views = statuses.Select(b => View(b, breaker, now, zone)).ToList();
+ var accounts = (await _s.Storage.Accounts.ListAsync(ct).ConfigureAwait(false)).ToDictionary(a => a.Id);
+
+ return new EngineSnapshot
+ {
+ At = now,
+ Mode = mode,
+ Headline = headline,
+ Details = details,
+ SidebarLine = sidebar,
+ ResumesAround = resumes,
+ Banner = Banner(breaker, now, zone),
+ Profile = profile.Kind,
+ ProfileLine = $"Profilo «{ItalianText.Profile(profile.Kind)}»",
+ ReductionNote = ReductionNote(budgets, now, zone),
+ Today = await StripAsync(now, zone, session, runtime, profile, accounts, ct).ConfigureAwait(false),
+ MainBudgets = [.. Main.Select(k => views.First(v => v.Kind == k))],
+ AllBudgets = views,
+ ProfilesOpenedToday = views.First(v => v.Kind == ActionKind.ProfileOpen),
+ Queue = await QueueAsync(now, zone, mode, session, runtime, accounts, ct).ConfigureAwait(false),
+ RecentActions = await RecentAsync(now, zone, ct).ConfigureAwait(false),
+ SuspendedRecipes = [.. _host.SuspendedRecipes.Select(r => new SuspendedRecipeView(r.Key, ItalianText.Capitalize(SessionComposer.RecipeName(r.Key)), r.Value))],
+ Breaker = breaker,
+ };
+ }
+
+ private static EngineMode ModeOf(EngineRuntime runtime, BreakerState breaker, SessionContext? session, ActiveWindow? window)
+ {
+ if (breaker.Status == BreakerStatus.Challenge)
+ {
+ return EngineMode.StoppedForVerification;
+ }
+
+ if (breaker.Status == BreakerStatus.Disconnected)
+ {
+ return EngineMode.Disconnected;
+ }
+
+ if (runtime.IsConnected == false)
+ {
+ return EngineMode.NotConnected;
+ }
+
+ if (breaker.Status == BreakerStatus.Throttled)
+ {
+ return EngineMode.Throttled;
+ }
+
+ if (runtime.IsPaused)
+ {
+ return EngineMode.Paused;
+ }
+
+ if (runtime.UserIsDriving)
+ {
+ return EngineMode.UserDriving;
+ }
+
+ if (!runtime.IsRunning)
+ {
+ return EngineMode.Off;
+ }
+
+ if (session is not null)
+ {
+ return EngineMode.InSession;
+ }
+
+ if (window is null)
+ {
+ return EngineMode.OutsideWindow;
+ }
+
+ return runtime.HadSessionSinceStart ? EngineMode.Resting : EngineMode.Starting;
+ }
+
+ private static DateTimeOffset? ResumesAround(EngineMode mode, EngineRuntime runtime, BreakerState breaker, ActiveWindow? nextWindow, DateTimeOffset now)
+ {
+ switch (mode)
+ {
+ case EngineMode.Throttled:
+ return breaker.Until;
+ case EngineMode.Resting or EngineMode.Starting or EngineMode.OutsideWindow:
+ var next = runtime.NextSessionAt;
+ if (mode == EngineMode.OutsideWindow && nextWindow is not null && (next is null || next < nextWindow.Start))
+ {
+ next = nextWindow.Start;
+ }
+
+ return next is { } n && n < now ? now : next;
+ default:
+ return null;
+ }
+ }
+
+ private static (string Headline, IReadOnlyList Details, string Sidebar) Texts(
+ EngineMode mode,
+ EngineRuntime runtime,
+ BreakerState breaker,
+ SessionContext? session,
+ DateTimeOffset? resumes,
+ DateTimeOffset now,
+ TimeZoneInfo zone)
+ {
+ var around = resumes is { } r ? ItalianText.Around(r, now, zone) : null;
+ switch (mode)
+ {
+ case EngineMode.InSession when session is not null:
+ {
+ var activity = runtime.Activity ?? "Sto per iniziare il prossimo passo";
+ var left = session.PlannedEnd - now;
+ var timing = left > TimeSpan.FromMinutes(1)
+ ? $"Iniziata {ItalianText.At(session.StartedAt, zone)}, ancora {ItalianText.Duration(left)} circa."
+ : $"Iniziata {ItalianText.At(session.StartedAt, zone)}, sta per finire.";
+ if (session.OutsideWindowAccountId is not null)
+ {
+ timing += " Controllo fuori fascia confermato da te.";
+ }
+
+ var sidebar = runtime.Activity is { } a && a.StartsWith("Sto ", StringComparison.Ordinal) ? ItalianText.Capitalize(a[4..]) : "In sessione";
+ return ("In sessione", [activity, timing], sidebar);
+ }
+
+ case EngineMode.Resting:
+ return ("In ascolto", [$"Riprende {around ?? "a breve"}.", "Fra una sessione e l'altra il browser resta sulla pagina vuota."], $"Riprende {around ?? "a breve"}");
+ case EngineMode.Starting:
+ return ("In avvio", [$"Prima sessione {around ?? "a breve"}."], $"Prima sessione {around ?? "a breve"}");
+ case EngineMode.OutsideWindow:
+ return ("Fuori fascia", ["Fuori dalla fascia oraria Febe non apre nulla da solo.", $"Riprende {around ?? "nei giorni attivi"}."], $"Riprende {around ?? "nei giorni attivi"}");
+ case EngineMode.Paused:
+ return ("In pausa", ["Messo in pausa da te.", "Premi «Riprendi» per ripartire."], "In pausa");
+ case EngineMode.Throttled:
+ {
+ var until = breaker.Until is { } u ? ItalianText.Around(u, now, zone) : "più tardi";
+ return ("Fermo per rallentamento", [$"Instagram ha chiesto di rallentare: riprende {until}.", "Poi i tetti restano dimezzati per 48 ore."], $"Riprende {until}");
+ }
+
+ case EngineMode.StoppedForVerification:
+ {
+ var since = breaker.LastSignal is { } s ? $"Fermo {ItalianText.Since(s.At, zone)}. " : string.Empty;
+ return ("Fermo", ["In attesa che tu completi la verifica", since + "Nessun nuovo tentativo finché non premi «Riprendi»."], "Serve il tuo intervento");
+ }
+
+ case EngineMode.Disconnected:
+ return ("Scollegato", ["La sessione di Instagram non c'è più.", "Apri il browser, accedi di nuovo, poi premi «Riprendi». Febe non prova a rientrare da solo."], "Accedi di nuovo");
+ case EngineMode.NotConnected:
+ return ("Non collegato", ["Il browser di Febe non ha una sessione di Instagram.", "Collegalo dalla pagina Collegamento."], "Non collegato");
+ case EngineMode.UserDriving:
+ return ("Stai usando il browser", ["Il motore resta fermo finché non hai finito."], "Stai usando il browser");
+ default:
+ return ("Motore spento", ["Il motore non è in funzione."], "Motore spento");
+ }
+ }
+
+ private static StopBanner? Banner(BreakerState breaker, DateTimeOffset now, TimeZoneInfo zone)
+ {
+ var at = breaker.LastSignal is { } s ? ItalianText.At(s.At, zone) : null;
+ return breaker.Status switch
+ {
+ BreakerStatus.Challenge => new StopBanner(
+ BannerLevel.Error,
+ "Instagram chiede una verifica",
+ $"Ho fermato tutto{(at is null ? string.Empty : " " + at)} e non riparto da solo. Apri il browser, completa la verifica a mano, poi premi «Riprendi».",
+ true),
+ BreakerStatus.Disconnected => new StopBanner(
+ BannerLevel.Error,
+ "Instagram ha chiuso la sessione",
+ $"Ho fermato tutto{(at is null ? string.Empty : " " + at)} e non provo a rientrare. Apri il browser, accedi a mano, poi premi «Riprendi».",
+ true),
+ BreakerStatus.Throttled when breaker.Until is { } until => new StopBanner(
+ BannerLevel.Warning,
+ "Instagram ha chiesto di rallentare",
+ $"Ho chiuso la sessione e mi fermo fino {ItalianText.AtDay(until, now, zone)}; poi riparto da solo con i tetti dimezzati per 48 ore.",
+ false),
+ _ => null,
+ };
+ }
+
+ private static string? ReductionNote(EffectiveBudgets budgets, DateTimeOffset now, TimeZoneInfo zone) => budgets.Reduction switch
+ {
+ BudgetReduction.GradualStart =>
+ $"Avvio graduale: tetti al {ItalianText.Number((long)Math.Round(budgets.Factor * 100))}%"
+ + (budgets.Until is { } u ? $", pieni {ItalianText.Around(u, now, zone)}" : string.Empty) + ".",
+ BudgetReduction.HalvedAfterThrottle =>
+ "Tetti dimezzati dopo un rallentamento" + (budgets.Until is { } h ? $" fino {ItalianText.AtDay(h, now, zone)}" : string.Empty) + ".",
+ _ => null,
+ };
+
+ internal static BudgetView View(BudgetStatus status, BreakerState breaker, DateTimeOffset now, TimeZoneInfo zone)
+ {
+ var data = status.Kind == ActionKind.DataDownload;
+ var usedText = data ? ItalianText.Bytes(status.UsedToday) : ItalianText.Number(status.UsedToday);
+ var limitText = "di " + (data ? ItalianText.Bytes(status.LimitToday) : ItalianText.Number(status.LimitToday));
+ string note;
+ if (!breaker.AllowsSiteActions && !data)
+ {
+ note = breaker.LastSignal is { } s ? "Fermo " + ItalianText.Since(s.At, zone) : "Fermo";
+ }
+ else if (status.DailyReached)
+ {
+ note = "Tetto di oggi raggiunto: riprende domani";
+ }
+ else if (status.HourlyReached)
+ {
+ note = "Tetto orario raggiunto: riprende entro un'ora";
+ }
+ else if (status.DailyRatio >= BudgetStatus.AmberThreshold)
+ {
+ note = "Quasi al limite per oggi";
+ }
+ else if (status.HourlyRatio >= BudgetStatus.AmberThreshold)
+ {
+ note = "Quasi al limite di quest'ora";
+ }
+ else if (data)
+ {
+ note = "Restano " + ItalianText.Bytes(Math.Max(0, status.LimitToday - status.UsedToday));
+ }
+ else
+ {
+ note = $"In questa ora {ItalianText.Number(status.UsedLastHour ?? 0)} di {ItalianText.Number(status.LimitPerHour ?? 0)}";
+ }
+
+ return new BudgetView(
+ status.Kind,
+ ItalianText.CategoryLabel(status.Kind),
+ status.UsedToday,
+ status.LimitToday,
+ status.UsedLastHour,
+ status.LimitPerHour,
+ status.IsAmber,
+ Math.Clamp(status.DailyRatio, 0, 1),
+ usedText,
+ limitText,
+ note);
+ }
+
+ private async Task StripAsync(
+ DateTimeOffset now,
+ TimeZoneInfo zone,
+ SessionContext? current,
+ EngineRuntime runtime,
+ CautionProfile profile,
+ Dictionary accounts,
+ CancellationToken ct)
+ {
+ var day = LocalCalendar.Today(now, zone);
+ var (dayStart, dayEnd) = LocalCalendar.DayBounds(day, zone);
+ var spans = new List();
+
+ // Night and inactive hours: everything of the day outside the windows of yesterday and today.
+ var windows = new List();
+ foreach (var d in new[] { day.AddDays(-1), day })
+ {
+ if (await _s.Planner.GetWindowAsync(d, ct).ConfigureAwait(false) is { } w && w.End > dayStart && w.Start < dayEnd)
+ {
+ windows.Add(w);
+ }
+ }
+
+ var cursor = dayStart;
+ foreach (var w in windows.OrderBy(w => w.Start))
+ {
+ var start = w.Start < dayStart ? dayStart : w.Start;
+ if (start > cursor)
+ {
+ spans.Add(new StripSpan(StripSpanKind.OutsideWindow, cursor, start, false, "Fuori fascia"));
+ }
+
+ cursor = w.End > cursor ? w.End : cursor;
+ }
+
+ if (cursor < dayEnd)
+ {
+ spans.Add(new StripSpan(StripSpanKind.OutsideWindow, cursor, dayEnd, false, "Fuori fascia"));
+ }
+
+ // Sessions of the day and the rests between them.
+ var sessions = await _s.Storage.Sessions.ListAsync(dayStart, dayEnd, ct).ConfigureAwait(false);
+ DateTimeOffset? previousEnd = null;
+ var activeMinutes = 0.0;
+ foreach (var session in sessions)
+ {
+ var end = session.EndedAt ?? now;
+ var inProgress = session.EndedAt is null && current?.SessionId == session.Id;
+ if (previousEnd is { } rest && session.StartedAt > rest)
+ {
+ spans.Add(new StripSpan(StripSpanKind.Rest, rest, session.StartedAt, false, "Pausa"));
+ }
+
+ spans.Add(new StripSpan(
+ inProgress ? StripSpanKind.CurrentSession : StripSpanKind.Session,
+ session.StartedAt,
+ end,
+ false,
+ (inProgress ? "Sessione in corso dalle " : "Sessione dalle ") + ItalianText.Clock(session.StartedAt, zone)
+ + (inProgress ? string.Empty : " alle " + ItalianText.Clock(end, zone))));
+ activeMinutes += ((end < dayEnd ? end : dayEnd) - (session.StartedAt > dayStart ? session.StartedAt : dayStart)).TotalMinutes;
+ previousEnd = end;
+ }
+
+ if (current is null && previousEnd is { } lastEnd && lastEnd < now && windows.Any(w => w.Contains(now)))
+ {
+ spans.Add(new StripSpan(StripSpanKind.Rest, lastEnd, now, false, "Pausa"));
+ }
+
+ // Stops.
+ var throttles = 0;
+ foreach (var incident in await _s.Storage.Incidents.ListAsync(dayStart - TimeSpan.FromDays(2), dayEnd, ct).ConfigureAwait(false))
+ {
+ var end = incident.ResolvedAt ?? (incident.Level == SignalLevel.Throttle ? incident.StoppedUntil ?? now : now);
+ if (end <= dayStart || incident.At >= dayEnd)
+ {
+ continue;
+ }
+
+ if (incident.Level == SignalLevel.Throttle)
+ {
+ if (incident.At >= dayStart)
+ {
+ throttles++;
+ }
+
+ spans.Add(new StripSpan(StripSpanKind.Throttle, incident.At, end, incident.ResolvedAt is null, "Fermo per rallentamento"));
+ }
+ else
+ {
+ spans.Add(new StripSpan(
+ StripSpanKind.Stop,
+ incident.At,
+ incident.ResolvedAt ?? now,
+ false,
+ incident.Level == SignalLevel.Challenge ? "Fermo per una verifica" : "Fermo per disconnessione"));
+ }
+ }
+
+ // Planned sessions, indicative: median length and median pause from the next planned start.
+ if (current is null && runtime.NextSessionAt is { } next && _s.Breaker.State.AllowsSiteActions && !runtime.IsPaused)
+ {
+ var sessionLength = TimeSpan.FromTicks((long)Math.Sqrt((double)profile.SessionMin.Ticks * profile.SessionMax.Ticks));
+ var pause = TimeSpan.FromTicks((long)Math.Sqrt((double)profile.PauseMin.Ticks * profile.PauseMax.Ticks));
+ var start = next < now ? now : next;
+ for (var i = 0; i < 40 && start < dayEnd; i++)
+ {
+ var window = windows.FirstOrDefault(w => w.Contains(start));
+ if (window is null)
+ {
+ break;
+ }
+
+ var end = start + sessionLength;
+ spans.Add(new StripSpan(StripSpanKind.PlannedSession, start, end < window.End ? end : window.End, true, "Prossima sessione " + ItalianText.Around(start, now, zone)));
+ start = end + pause;
+ }
+ }
+
+ var newEntries = 0L;
+ foreach (var account in accounts.Values)
+ {
+ foreach (var kind in new[] { EntryKind.Post, EntryKind.Story, EntryKind.Highlight, EntryKind.Tagged })
+ {
+ newEntries += await _s.Storage.Entries.CountDiscoveredAsync(account.Id, kind, dayStart, dayEnd, ct).ConfigureAwait(false);
+ }
+ }
+
+ var summary = string.Join(", ", new[]
+ {
+ ItalianText.Count(sessions.Count, "sessione", "sessioni"),
+ ItalianText.Count((long)Math.Round(activeMinutes), "minuto di attività", "minuti di attività"),
+ ItalianText.Count(newEntries, "contenuto nuovo", "contenuti nuovi"),
+ throttles == 0 ? "nessun rallentamento" : ItalianText.Count(throttles, "rallentamento", "rallentamenti"),
+ });
+
+ return new DayStrip(day, dayStart, dayEnd, now, summary, [.. spans.OrderBy(s => s.Start).ThenBy(s => s.Kind)]);
+ }
+
+ private async Task> QueueAsync(
+ DateTimeOffset now,
+ TimeZoneInfo zone,
+ EngineMode mode,
+ SessionContext? session,
+ EngineRuntime runtime,
+ Dictionary accounts,
+ CancellationToken ct)
+ {
+ var suspended = mode is EngineMode.Paused or EngineMode.Throttled or EngineMode.StoppedForVerification or EngineMode.Disconnected
+ or EngineMode.NotConnected or EngineMode.Off;
+ var tasks = await _s.Storage.Tasks.ListPendingAsync(200, ct).ConfigureAwait(false);
+ var items = new List();
+ foreach (var task in tasks
+ .OrderByDescending(t => t.IsManual)
+ .ThenBy(t => t.DueAt)
+ .ThenByDescending(t => t.Priority)
+ .Take(20))
+ {
+ Account? account = null;
+ if (task.AccountId is { } id)
+ {
+ accounts.TryGetValue(id, out account);
+ }
+
+ var (title, detail) = Describe(task, account);
+ DateTimeOffset? around = null;
+ string when;
+ if (suspended)
+ {
+ when = "Sospeso";
+ }
+ else if (session is not null && task.DueAt <= now)
+ {
+ around = now;
+ when = "In questa sessione";
+ }
+ else
+ {
+ var t = task.DueAt;
+ var next = runtime.NextSessionAt ?? now;
+ if (t < next)
+ {
+ t = next;
+ }
+
+ if (t < now)
+ {
+ t = now;
+ }
+
+ if (await _s.Planner.GetWindowAtAsync(t, ct).ConfigureAwait(false) is null
+ && await _s.Planner.GetNextWindowAsync(t, ct).ConfigureAwait(false) is { } w)
+ {
+ t = w.Start;
+ }
+
+ around = t;
+ when = ItalianText.Around(t, now, zone);
+ }
+
+ items.Add(new QueueItem(task.Id, task.Kind, task.AccountId, title, detail, around, when, task.IsManual, suspended));
+ }
+
+ return items;
+ }
+
+ private static (string Title, string Detail) Describe(EngineTask task, Account? account)
+ {
+ var who = ItalianText.Handle(account?.Username);
+ return task.Kind switch
+ {
+ EngineTaskKind.FollowingSweep => ("Giro dei profili che segui", "Home e barra delle storie"),
+ EngineTaskKind.FollowingList => ("Elenco dei profili che segui", "Lettura chiesta da te"),
+ EngineTaskKind.ProfileCheck when task.IsManual => (who, "Controllo chiesto da te"),
+ EngineTaskKind.ProfileCheck when account is { IsFollowed: true } => (who, "Riconciliazione del profilo"),
+ EngineTaskKind.ProfileCheck when account is not null && CheckPolicy.WantsStories(account) => (who, "Nuovi post e storie"),
+ EngineTaskKind.ProfileCheck => (who, "Nuovi post"),
+ EngineTaskKind.AccountStories when task.IsManual => (who, "Storie, chieste da te"),
+ EngineTaskKind.AccountStories when task.Priority > 0 => (who, "Storie segnalate dalla barra"),
+ EngineTaskKind.AccountStories => (who, "Storie"),
+ EngineTaskKind.Backfill when account?.PostCount is { } count => (who, "Storico, " + ItalianText.Count(count, "post sul profilo", "post sul profilo")),
+ EngineTaskKind.Backfill => (who, "Storico"),
+ EngineTaskKind.HighlightCheck => (who, "Storie in evidenza"),
+ EngineTaskKind.TaggedCheck => (who, "Post in cui è taggato"),
+ EngineTaskKind.ReelsCheck => (who, "Reel"),
+ EngineTaskKind.SinglePost => (who, "Post singolo"),
+ _ => (who, task.Kind.ToString()),
+ };
+ }
+
+ private async Task> RecentAsync(DateTimeOffset now, TimeZoneInfo zone, CancellationToken ct)
+ {
+ var views = new List();
+ if (_s.Runtime.CurrentSession is not null && _s.Runtime.Activity is { } activity)
+ {
+ views.Add(new RecentActionView(now, ItalianText.Clock(now, zone), activity.StartsWith("Sto ", StringComparison.Ordinal) ? ItalianText.Capitalize(activity[4..]) : activity, string.Empty, "In corso", true));
+ }
+
+ var recent = _host.RecentActions(10);
+ if (recent.Count > 0)
+ {
+ views.AddRange(recent.Select(r => new RecentActionView(r.At, ItalianText.Clock(r.At, zone), r.Title, r.Detail, r.Badge, false)));
+ return views;
+ }
+
+ // Just started: the latest lines of the timeline.
+ var events = await _s.Storage.Events.ListAsync(new EventQuery { Limit = 200 }, ct).ConfigureAwait(false);
+ foreach (var e in events.Where(e => e.Code.StartsWith(EngineEventCodes.RecipePrefix, StringComparison.Ordinal)).Take(10))
+ {
+ var split = e.Message.IndexOf(": ", StringComparison.Ordinal);
+ var title = split > 0 ? e.Message[..split] : e.Message;
+ var detail = split > 0 ? e.Message[(split + 2)..] : string.Empty;
+ views.Add(new RecentActionView(e.At, ItalianText.Clock(e.At, zone), title, detail, null, false));
+ }
+
+ return views;
+ }
+}
diff --git a/src/Febe.Core/Engine/MonitorModels.cs b/src/Febe.Core/Engine/MonitorModels.cs
new file mode 100644
index 0000000..6c6cf6d
--- /dev/null
+++ b/src/Febe.Core/Engine/MonitorModels.cs
@@ -0,0 +1,193 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+
+namespace Febe.Core.Engine;
+
+/// What the interface shows of the engine (spec §7.9, mockups 06 and 11, sidebar of §10.2).
+public interface IEngineMonitor
+{
+ /// The state of the engine now: mode, texts, strip of the day, budgets, queue, latest actions.
+ Task GetSnapshotAsync(CancellationToken ct = default);
+
+ /// Notifications from now on (timeline lines and state changes); the web layer turns them into server-sent events.
+ IAsyncEnumerable SubscribeAsync(CancellationToken ct = default);
+}
+
+/// Mode of the engine, in order of precedence.
+public enum EngineMode
+{
+ /// The loop is not running.
+ Off,
+
+ /// Just started: the first session comes 2–10 minutes after the program.
+ Starting,
+
+ InSession,
+
+ /// Between two sessions, inside the active window («In ascolto»).
+ Resting,
+
+ /// Outside the active window (night or inactive day).
+ OutsideWindow,
+
+ /// «Metti in pausa».
+ Paused,
+
+ /// Timed stop after a throttle.
+ Throttled,
+
+ /// Stopped for a verification: needs Alberto and «Riprendi».
+ StoppedForVerification,
+
+ /// The Instagram session is gone: needs a new login and «Riprendi».
+ Disconnected,
+
+ /// The browser has no Instagram session yet.
+ NotConnected,
+
+ /// Alberto is using the browser.
+ UserDriving,
+}
+
+/// Severity of the strip at the top of every page.
+public enum BannerLevel
+{
+ Warning,
+ Error,
+}
+
+/// The strip at the top of every page while Febe is stopped and needs Alberto (mockup 11).
+/// Error for verification and disconnection, warning for a throttle stop.
+/// «Instagram chiede una verifica».
+/// What happened, what Febe did, what Alberto must do.
+/// «Riprendi» is needed (after Alberto used the browser).
+public sealed record StopBanner(BannerLevel Level, string Title, string Message, bool NeedsResume);
+
+public enum StripSpanKind
+{
+ /// Outside the active window: night (hatched).
+ OutsideWindow,
+
+ /// A past session.
+ Session,
+
+ /// The session in progress.
+ CurrentSession,
+
+ /// A planned session, indicative («Prossime, orario indicativo»).
+ PlannedSession,
+
+ /// Rest between sessions («Pausa»).
+ Rest,
+
+ /// Throttle stop.
+ Throttle,
+
+ /// Stop for a verification or a disconnection.
+ Stop,
+}
+
+/// A stretch of the strip of the day.
+public sealed record StripSpan(StripSpanKind Kind, DateTimeOffset Start, DateTimeOffset End, bool Indicative, string Label);
+
+/// The strip of the day: a 24-hour bar with sessions as irregular strokes (spec §10.1).
+/// Local day.
+/// Local midnight.
+/// Next local midnight.
+/// Instant of the snapshot (the marker).
+/// «9 sessioni, 80 minuti di attività, 41 contenuti nuovi, nessun rallentamento».
+/// Stretches in time order (spans of different kinds may overlap: stops over sessions).
+public sealed record DayStrip(DateOnly Day, DateTimeOffset Start, DateTimeOffset End, DateTimeOffset Now, string Summary, IReadOnlyList Spans);
+
+/// One budget as the interface shows it (spec §7.4: amber from 80%).
+/// Category.
+/// «Profili aperti».
+/// Today (bytes for data).
+/// Daily limit in force.
+/// Rolling last hour (null for data).
+/// Hourly limit in force (null for data).
+/// At or above 80% of the daily or hourly budget.
+/// Daily use between 0 and 1 (for the bar).
+/// «38», «1,3 GB».
+/// «di 100», «di 4 GB».
+/// «In questa ora 3 di 12», «Quasi al limite per oggi», «Fermo dalle 16:32».
+public sealed record BudgetView(
+ ActionKind Kind,
+ string Label,
+ long UsedToday,
+ long LimitToday,
+ long? UsedLastHour,
+ long? LimitPerHour,
+ bool Amber,
+ double Ratio,
+ string UsedText,
+ string LimitText,
+ string Note);
+
+/// A task of the queue with its indicative time.
+/// Task key.
+/// What it is.
+/// Account, when it has one.
+/// «@luca.viaggi.demo» or «Giro dei profili che segui».
+/// «Nuovi post», «Storico, altri 120 post».
+/// Indicative time; null when suspended.
+/// «verso le 14:32», «In questa sessione», «Sospeso».
+/// Asked by Alberto.
+/// The engine is stopped or paused.
+public sealed record QueueItem(long TaskId, EngineTaskKind Kind, long? AccountId, string Title, string Detail, DateTimeOffset? Around, string When, bool IsManual, bool Suspended);
+
+/// A line of «Appena fatto».
+public sealed record RecentActionView(DateTimeOffset At, string Time, string Title, string Detail, string? Badge, bool InProgress);
+
+/// A recipe suspended after repeated unrecognized formats.
+public sealed record SuspendedRecipeView(RecipeKind Recipe, string Name, DateTimeOffset Since);
+
+/// Everything the Activity page, the sidebar and the stop strip need, at one instant.
+public sealed record EngineSnapshot
+{
+ public required DateTimeOffset At { get; init; }
+
+ public required EngineMode Mode { get; init; }
+
+ /// «In sessione», «In ascolto», «Fermo».
+ public required string Headline { get; init; }
+
+ /// Lines under the headline: «Sto guardando le storie di @marta.demo», «Iniziata alle 15:31, ancora 3 minuti circa».
+ public required IReadOnlyList Details { get; init; }
+
+ /// One short line for the sidebar: «Storie di @marta.demo», «Riprende verso le 15:30».
+ public required string SidebarLine { get; init; }
+
+ /// Indicative restart time when not working.
+ public DateTimeOffset? ResumesAround { get; init; }
+
+ /// The red (or amber) strip at the top of every page; null when the engine does not need Alberto.
+ public StopBanner? Banner { get; init; }
+
+ public required CautionProfileKind Profile { get; init; }
+
+ /// «Profilo «Prudente»» with the reduction in force, if any.
+ public required string ProfileLine { get; init; }
+
+ /// «Avvio graduale: tetti al 64%» or «Tetti dimezzati fino a giovedì alle 17:32»; null without reductions.
+ public string? ReductionNote { get; init; }
+
+ public required DayStrip Today { get; init; }
+
+ /// The four main budgets: profiles opened, stories viewed, history pages, data downloaded.
+ public required IReadOnlyList MainBudgets { get; init; }
+
+ /// «Tutti i tetti».
+ public required IReadOnlyList AllBudgets { get; init; }
+
+ /// «Profili aperti oggi» meter of the sidebar.
+ public required BudgetView ProfilesOpenedToday { get; init; }
+
+ public required IReadOnlyList Queue { get; init; }
+
+ public required IReadOnlyList RecentActions { get; init; }
+
+ public required IReadOnlyList SuspendedRecipes { get; init; }
+
+ public required BreakerState Breaker { get; init; }
+}
diff --git a/src/Febe.Core/Engine/RecentActions.cs b/src/Febe.Core/Engine/RecentActions.cs
new file mode 100644
index 0000000..3be1adc
--- /dev/null
+++ b/src/Febe.Core/Engine/RecentActions.cs
@@ -0,0 +1,60 @@
+namespace Febe.Core.Engine;
+
+/// One recipe run, as shown in «Appena fatto» (mockup 06).
+/// When it ended.
+/// Recipe.
+/// Account, when the recipe has one.
+/// «@marta.demo» or «Giro dei profili che segui».
+/// «2 storie nuove», «Nessuna novità».
+/// How it ended.
+/// New entries found.
+public sealed record RecentAction(
+ DateTimeOffset At,
+ RecipeKind Recipe,
+ long? AccountId,
+ string Title,
+ string Detail,
+ RecipeStatus Status,
+ int NewEntries)
+{
+ /// Short label of the outcome for a badge («Scaricato», «Rimandato»...); null when nothing to say.
+ public string? Badge => Status switch
+ {
+ RecipeStatus.Completed => NewEntries > 0 ? "Scaricato" : null,
+ RecipeStatus.Denied => "Rimandato",
+ RecipeStatus.StoppedBySignal => "Tutto fermo",
+ RecipeStatus.TargetNotFound => "Da controllare",
+ RecipeStatus.UnrecognizedFormat => "Formato nuovo",
+ RecipeStatus.AccountUnreachable => "Non raggiungibile",
+ RecipeStatus.Cancelled => "Interrotto",
+ RecipeStatus.Failed => "Errore",
+ _ => null,
+ };
+}
+
+/// The last recipe runs, newest first, in memory (the timeline keeps the full history).
+internal sealed class RecentActions(int capacity = 50)
+{
+ private readonly Lock _gate = new();
+ private readonly LinkedList _items = new();
+
+ public void Add(RecentAction action)
+ {
+ lock (_gate)
+ {
+ _items.AddFirst(action);
+ while (_items.Count > capacity)
+ {
+ _items.RemoveLast();
+ }
+ }
+ }
+
+ public IReadOnlyList Snapshot(int limit)
+ {
+ lock (_gate)
+ {
+ return [.. _items.Take(limit)];
+ }
+ }
+}
diff --git a/src/Febe.Core/Engine/RecipeHealth.cs b/src/Febe.Core/Engine/RecipeHealth.cs
new file mode 100644
index 0000000..f829052
--- /dev/null
+++ b/src/Febe.Core/Engine/RecipeHealth.cs
@@ -0,0 +1,149 @@
+using System.Globalization;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// Consecutive failures per recipe and suspended recipes (spec §6.4: after three «formato non riconosciuto» in a row
+/// the recipe is suspended and the interface says so). Persisted in the settings table.
+///
+internal sealed class RecipeHealth
+{
+ private readonly ISettingsStore _settings;
+ private readonly int _threshold;
+ private readonly Lock _gate = new();
+ private readonly Dictionary _failures = [];
+ private readonly Dictionary _suspended = [];
+
+ public RecipeHealth(ISettingsStore settings, int threshold)
+ {
+ _settings = settings;
+ _threshold = Math.Max(1, threshold);
+ }
+
+ public async Task LoadAsync(CancellationToken ct)
+ {
+ var failures = await _settings.GetAsync(EngineSettingKeys.RecipeFailures, ct).ConfigureAwait(false);
+ var suspended = await _settings.GetAsync(EngineSettingKeys.SuspendedRecipes, ct).ConfigureAwait(false);
+ lock (_gate)
+ {
+ _failures.Clear();
+ _suspended.Clear();
+ foreach (var (kind, value) in Parse(failures))
+ {
+ _failures[kind] = (int)value;
+ }
+
+ foreach (var (kind, value) in Parse(suspended))
+ {
+ _suspended[kind] = DateTimeOffset.FromUnixTimeMilliseconds(value);
+ }
+ }
+ }
+
+ public IReadOnlyDictionary Suspended
+ {
+ get
+ {
+ lock (_gate)
+ {
+ return new Dictionary(_suspended);
+ }
+ }
+ }
+
+ public bool IsSuspended(RecipeKind kind)
+ {
+ lock (_gate)
+ {
+ return _suspended.ContainsKey(kind);
+ }
+ }
+
+ public int Failures(RecipeKind kind)
+ {
+ lock (_gate)
+ {
+ return _failures.GetValueOrDefault(kind);
+ }
+ }
+
+ /// Counts a failure; true when this one suspends the recipe.
+ public async Task RecordFailureAsync(RecipeKind kind, DateTimeOffset now, CancellationToken ct)
+ {
+ bool suspendedNow;
+ lock (_gate)
+ {
+ var count = _failures.GetValueOrDefault(kind) + 1;
+ _failures[kind] = count;
+ suspendedNow = count >= _threshold && _suspended.TryAdd(kind, now);
+ }
+
+ await SaveAsync(ct).ConfigureAwait(false);
+ return suspendedNow;
+ }
+
+ public async Task RecordSuccessAsync(RecipeKind kind, CancellationToken ct)
+ {
+ lock (_gate)
+ {
+ if (!_failures.Remove(kind))
+ {
+ return;
+ }
+ }
+
+ await SaveAsync(ct).ConfigureAwait(false);
+ }
+
+ /// Alberto updated the reader and reactivated the recipe.
+ public async Task ResumeAsync(RecipeKind kind, CancellationToken ct)
+ {
+ bool removed;
+ lock (_gate)
+ {
+ removed = _suspended.Remove(kind);
+ _failures.Remove(kind);
+ }
+
+ await SaveAsync(ct).ConfigureAwait(false);
+ return removed;
+ }
+
+ private Task SaveAsync(CancellationToken ct)
+ {
+ string failures;
+ string suspended;
+ lock (_gate)
+ {
+ failures = string.Join(';', _failures.OrderBy(f => f.Key).Select(f => f.Key + "=" + f.Value.ToString(CultureInfo.InvariantCulture)));
+ suspended = string.Join(';', _suspended.OrderBy(s => s.Key).Select(s => s.Key + "=" + s.Value.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture)));
+ }
+
+ return _settings.SetManyAsync(
+ new Dictionary
+ {
+ [EngineSettingKeys.RecipeFailures] = failures.Length == 0 ? null : failures,
+ [EngineSettingKeys.SuspendedRecipes] = suspended.Length == 0 ? null : suspended,
+ },
+ ct);
+ }
+
+ private static IEnumerable<(RecipeKind Kind, long Value)> Parse(string? text)
+ {
+ if (string.IsNullOrWhiteSpace(text))
+ {
+ yield break;
+ }
+
+ foreach (var part in text.Split(';', StringSplitOptions.RemoveEmptyEntries))
+ {
+ var pair = part.Split('=', 2);
+ if (pair.Length == 2 && Enum.TryParse(pair[0], out var kind)
+ && long.TryParse(pair[1], NumberStyles.Integer, CultureInfo.InvariantCulture, out var value))
+ {
+ yield return (kind, value);
+ }
+ }
+ }
+}
diff --git a/src/Febe.Core/Engine/SessionComposer.cs b/src/Febe.Core/Engine/SessionComposer.cs
new file mode 100644
index 0000000..46faa4a
--- /dev/null
+++ b/src/Febe.Core/Engine/SessionComposer.cs
@@ -0,0 +1,1040 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Pacing;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Engine;
+
+///
+/// Composes and runs one session (spec §7.2, §7.3): commands of Alberto first, then usually the Giro dei seguiti,
+/// the flagged and due stories, the expired profile checks, finally a few pages of history on one account. About one
+/// session in three stops after the sweep and the stories. Accounts are taken in a random order weighted by frequency
+/// and delay. Planned work lives in the persisted task queue; this class keeps it in step with the accounts.
+///
+internal sealed class SessionComposer
+{
+ private static readonly TimeSpan DefaultWindow = TimeSpan.FromHours(16);
+
+ private readonly EngineServices _s;
+ private readonly IRecipeRunner _runner;
+ private readonly RecipeHealth _health;
+ private readonly RecentActions _recent;
+ private readonly Action _manualDone;
+ private readonly Lock _noticeGate = new();
+ private readonly HashSet<(string Code, long? Account, DateOnly Day)> _notices = [];
+ private DateTimeOffset? _lastSweepAt;
+ private bool _lastSweepLoaded;
+
+ public SessionComposer(EngineServices services, IRecipeRunner runner, RecipeHealth health, RecentActions recent, Action manualDone)
+ {
+ _s = services;
+ _runner = runner;
+ _health = health;
+ _recent = recent;
+ _manualDone = manualDone;
+ }
+
+ private IClock Clock => _s.Clock;
+
+ private IFebeStorage Store => _s.Storage;
+
+ private EngineOptions Options => _s.Options;
+
+ /// Runs the session. is a confirmed «Controlla ora» outside the window: then only that.
+ public async Task RunAsync(SessionContext context, EngineTask? outsideWindowTask, CancellationToken ct)
+ {
+ var state = new SessionState(context);
+ var accounts = await SyncQueueAsync(ct).ConfigureAwait(false);
+
+ if (outsideWindowTask is not null)
+ {
+ await RunManualAsync(outsideWindowTask, accounts, state, ct).ConfigureAwait(false);
+ return state.Summary();
+ }
+
+ // 1. Commands of Alberto («Controlla ora», «Leggi l'elenco»).
+ var due = await Store.Tasks.PeekDueAsync(Clock.Now, 1000, ct).ConfigureAwait(false);
+ await RunManualTasksAsync(due, accounts, state, ct).ConfigureAwait(false);
+
+ var light = _s.Random.Chance(Options.LightSessionProbability);
+ var anyFollowed = accounts.Values.Any(a => a.IsFollowed && CheckPolicy.IsContactable(a));
+
+ // 2. Usually the Giro dei seguiti first.
+ if (anyFollowed && _s.Random.Chance(Options.SweepProbability) && !Over(state, ct))
+ {
+ var sweepTask = due.FirstOrDefault(t => t.Kind == EngineTaskKind.FollowingSweep && !t.IsManual);
+ await RunSweepAsync(sweepTask, accounts, state, ct).ConfigureAwait(false);
+ }
+
+ // 3. Stories: flagged by the stories bar first, then the due ones (visits of profiles not followed included).
+ if (!Over(state, ct))
+ {
+ var now = Clock.Now;
+ var window = await WindowLengthAsync(now, ct).ConfigureAwait(false);
+ due = await Store.Tasks.PeekDueAsync(now, 1000, ct).ConfigureAwait(false);
+ await RunManualTasksAsync(due, accounts, state, ct).ConfigureAwait(false);
+ var storyWork = due.Where(t => !t.IsManual && IsStoryWork(t, accounts, now)).ToList();
+ var flagged = storyWork.Where(t => t.Priority >= Options.FlaggedStoriesPriority);
+ var rest = storyWork.Where(t => t.Priority < Options.FlaggedStoriesPriority);
+ foreach (var task in Weighted(flagged, accounts, now, window).Concat(Weighted(rest, accounts, now, window)))
+ {
+ if (Over(state, ct))
+ {
+ break;
+ }
+
+ await RunScheduledAsync(task, accounts, state, ct).ConfigureAwait(false);
+ }
+
+ // Followed accounts whose stories no recent sweep has read (e.g. the home budget is exhausted).
+ if (Options.SweepCoversFollowedStories && !Over(state, ct))
+ {
+ var lastSweep = await LastSweepAsync().ConfigureAwait(false);
+ now = Clock.Now;
+
+ // Normally the next sweep will cover them: explicit checks only when no sweep can run, or after a long gap.
+ var sweepUnavailable = _health.IsSuspended(RecipeKind.FollowingSweep)
+ || !(await _s.Governor.EvaluateBudgetAsync(ActionKind.Home, null, ct).ConfigureAwait(false)).Granted;
+ var factor = sweepUnavailable ? 1 : 2;
+ var uncovered = accounts.Values
+ .Where(a => a.IsFollowed && CheckPolicy.IsContactable(a) && CheckPolicy.WantsStories(a) && !state.Visited.Contains(a.Id))
+ .Select(a => (Account: a, Interval: CheckPolicy.StoryInterval(a, window, Options.MinimumStoryChecksPerDay)))
+ .Where(x => Uncovered(x.Account, x.Interval * factor, lastSweep, now))
+ .Select(x => (x.Account, CheckPolicy.SelectionWeight(x.Account, now - Latest(x.Account.LastStoriesCheckAt, lastSweep) - x.Interval, x.Interval)))
+ .ToList();
+ foreach (var account in CheckPolicy.WeightedOrder(_s.Random, uncovered))
+ {
+ if (Over(state, ct))
+ {
+ break;
+ }
+
+ await RunStoriesAsync(null, account, state, manual: false, visitNext: null, ct).ConfigureAwait(false);
+ }
+ }
+ }
+
+ // 4. Expired profile checks and other planned work.
+ if (!light && !Over(state, ct))
+ {
+ var now = Clock.Now;
+ var window = await WindowLengthAsync(now, ct).ConfigureAwait(false);
+ due = await Store.Tasks.PeekDueAsync(now, 1000, ct).ConfigureAwait(false);
+ await RunManualTasksAsync(due, accounts, state, ct).ConfigureAwait(false);
+ var other = due.Where(t => !t.IsManual
+ && t.Kind is not (EngineTaskKind.FollowingSweep or EngineTaskKind.Backfill or EngineTaskKind.AccountStories)
+ && !(t.AccountId is { } id && state.Visited.Contains(id)));
+ foreach (var task in Weighted(other, accounts, now, window))
+ {
+ if (Over(state, ct))
+ {
+ break;
+ }
+
+ await RunScheduledAsync(task, accounts, state, ct).ConfigureAwait(false);
+ }
+ }
+
+ // 5. A few pages of history on one account.
+ if (!light && !Over(state, ct))
+ {
+ await RunBackfillAsync(accounts, state, ct).ConfigureAwait(false);
+ }
+
+ return state.Summary();
+ }
+
+ ///
+ /// Keeps the queue in step with the accounts: a profile check and a story check (as the account wants them) for
+ /// every contactable account, a backfill task for every account «Storico in corso», a Giro dei seguiti when someone
+ /// is followed; pending planned tasks of accounts that may not be contacted are cancelled. Commands of Alberto
+ /// are left alone.
+ ///
+ public async Task> SyncQueueAsync(CancellationToken ct)
+ {
+ var now = Clock.Now;
+ var accounts = (await Store.Accounts.ListAsync(ct).ConfigureAwait(false)).ToDictionary(a => a.Id);
+ var pending = await Store.Tasks.ListPendingAsync(10_000, ct).ConfigureAwait(false);
+ var byAccount = pending.Where(t => t.AccountId is not null).ToLookup(t => t.AccountId!.Value);
+
+ foreach (var account in accounts.Values)
+ {
+ var tasks = byAccount[account.Id].Where(t => !t.IsManual).ToList();
+ var wanted = WantedKinds(account);
+ foreach (var task in tasks.Where(t => !wanted.ContainsKey(t.Kind) && !(t.Kind == EngineTaskKind.AccountStories && t.Priority >= Options.FlaggedStoriesPriority && CheckPolicy.IsContactable(account))))
+ {
+ await Store.Tasks.CancelAsync(task.Id, now, ct).ConfigureAwait(false);
+ }
+
+ foreach (var (kind, dueAt) in wanted)
+ {
+ if (tasks.Any(t => t.Kind == kind))
+ {
+ continue;
+ }
+
+ await Store.Tasks.EnqueueAsync(
+ new EngineTask { Kind = kind, AccountId = account.Id, DueAt = dueAt ?? now, CreatedAt = now },
+ ct).ConfigureAwait(false);
+ }
+ }
+
+ var anyFollowed = accounts.Values.Any(a => a.IsFollowed && CheckPolicy.IsContactable(a));
+ var sweeps = pending.Where(t => t.Kind == EngineTaskKind.FollowingSweep && !t.IsManual).ToList();
+ if (anyFollowed && sweeps.Count == 0)
+ {
+ await EnsureSweepTaskAsync(_s.Runtime.NextSessionAt ?? now, ct).ConfigureAwait(false);
+ }
+ else if (!anyFollowed)
+ {
+ foreach (var sweep in sweeps)
+ {
+ await Store.Tasks.CancelAsync(sweep.Id, now, ct).ConfigureAwait(false);
+ }
+ }
+
+ return accounts;
+ }
+
+ /// The Giro dei seguiti shown in the queue at the next session.
+ public Task EnsureSweepTaskAsync(DateTimeOffset dueAt, CancellationToken ct) =>
+ Store.Tasks.EnqueueAsync(
+ new EngineTask { Kind = EngineTaskKind.FollowingSweep, DueAt = dueAt, CreatedAt = Clock.Now },
+ ct);
+
+ private Dictionary WantedKinds(Account account)
+ {
+ var wanted = new Dictionary();
+ if (!CheckPolicy.IsContactable(account))
+ {
+ return wanted;
+ }
+
+ var profile = CheckPolicy.WantsProfileChecks(account);
+ var stories = CheckPolicy.WantsStories(account);
+ if (profile)
+ {
+ // A profile that is not followed shows its stories only on its page: one visit serves both checks.
+ wanted[EngineTaskKind.ProfileCheck] = !account.IsFollowed && stories
+ ? Earliest(account.NextProfileCheckAt, account.NextStoriesCheckAt)
+ : account.NextProfileCheckAt;
+ }
+
+ // Followed accounts: under hypothesis H2 every sweep reads their stories bar, so only flagged checks are queued.
+ if (stories && (account.IsFollowed ? !Options.SweepCoversFollowedStories : !profile))
+ {
+ wanted[EngineTaskKind.AccountStories] = account.NextStoriesCheckAt;
+ }
+
+ if (account.State == AccountState.Backfilling && account.BackfillCompletedAt is null)
+ {
+ wanted[EngineTaskKind.Backfill] = null;
+ }
+
+ return wanted;
+ }
+
+ private static DateTimeOffset? Earliest(DateTimeOffset? a, DateTimeOffset? b) =>
+ a is null || b is null ? null : a < b ? a : b;
+
+ private static bool IsStoryWork(EngineTask task, Dictionary accounts, DateTimeOffset now)
+ {
+ if (task.Kind == EngineTaskKind.AccountStories)
+ {
+ return true;
+ }
+
+ // The visit of a profile that is not followed is story work when its stories are due.
+ return task.Kind == EngineTaskKind.ProfileCheck
+ && task.AccountId is { } id
+ && accounts.TryGetValue(id, out var account)
+ && !account.IsFollowed
+ && CheckPolicy.WantsStories(account)
+ && (account.NextStoriesCheckAt is null || account.NextStoriesCheckAt <= now);
+ }
+
+ private IEnumerable Weighted(IEnumerable tasks, Dictionary accounts, DateTimeOffset now, TimeSpan window)
+ {
+ var items = new List<(EngineTask, double)>();
+ foreach (var task in tasks)
+ {
+ if (task.AccountId is { } id && accounts.TryGetValue(id, out var account))
+ {
+ var interval = task.Kind == EngineTaskKind.AccountStories
+ ? CheckPolicy.StoryInterval(account, window, Options.MinimumStoryChecksPerDay)
+ : CheckPolicy.VisitInterval(account, window, Options.MinimumStoryChecksPerDay);
+ items.Add((task, CheckPolicy.SelectionWeight(account, now - task.DueAt, interval)));
+ }
+ else
+ {
+ items.Add((task, 2));
+ }
+ }
+
+ return CheckPolicy.WeightedOrder(_s.Random, items);
+ }
+
+ private async Task WindowLengthAsync(DateTimeOffset now, CancellationToken ct) =>
+ (await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false))?.Length ?? DefaultWindow;
+
+ ///
+ /// The session must not start anything else: stopped, cancelled, time up, or a stop, a pause or Alberto at the
+ /// browser (checked here too, so the session ends at once even before its cancellation arrives).
+ ///
+ private bool Over(SessionState state, CancellationToken ct) =>
+ state.Stop
+ || ct.IsCancellationRequested
+ || Clock.Now >= state.Context.PlannedEnd
+ || !_s.Breaker.State.AllowsSiteActions
+ || _s.Runtime.IsPaused
+ || _s.Runtime.UserIsDriving;
+
+ /// Commands of Alberto that are due and not run yet in this session, first of all.
+ private async Task RunManualTasksAsync(IReadOnlyList due, Dictionary accounts, SessionState state, CancellationToken ct)
+ {
+ foreach (var task in due.Where(t => t.IsManual && state.ManualDone.Add(t.Id)).OrderByDescending(t => t.Priority).ThenBy(t => t.DueAt))
+ {
+ if (Over(state, ct))
+ {
+ break;
+ }
+
+ await RunManualAsync(task, accounts, state, ct).ConfigureAwait(false);
+ }
+ }
+
+ private async Task RunManualAsync(EngineTask task, Dictionary accounts, SessionState state, CancellationToken ct)
+ {
+ Account? account = null;
+ if (task.AccountId is { } id && !accounts.TryGetValue(id, out account))
+ {
+ await Store.Tasks.CancelAsync(task.Id, Clock.Now, CancellationToken.None).ConfigureAwait(false);
+ return;
+ }
+
+ if (account is not null && !CheckPolicy.AllowsManualCheck(account))
+ {
+ await Store.Tasks.CancelAsync(task.Id, Clock.Now, CancellationToken.None).ConfigureAwait(false);
+ return;
+ }
+
+ state.Context.ManualAccountId = task.AccountId;
+ try
+ {
+ switch (task.Kind)
+ {
+ case EngineTaskKind.ProfileCheck when account is not null:
+ await RunVisitAsync(task, account, state, manual: true, ct).ConfigureAwait(false);
+ break;
+ case EngineTaskKind.AccountStories when account is not null:
+ await RunStoriesAsync(task, account, state, manual: true, visitNext: null, ct).ConfigureAwait(false);
+ break;
+ default:
+ await RunGenericAsync(task, account, state, manual: true, ct).ConfigureAwait(false);
+ break;
+ }
+ }
+ finally
+ {
+ state.Context.ManualAccountId = null;
+ if (task.AccountId is { } done)
+ {
+ _manualDone(done);
+ }
+ }
+ }
+
+ private async Task RunScheduledAsync(EngineTask task, Dictionary accounts, SessionState state, CancellationToken ct)
+ {
+ Account? account = null;
+ if (task.AccountId is { } id)
+ {
+ if (!accounts.TryGetValue(id, out account) || !CheckPolicy.IsContactable(account))
+ {
+ await Store.Tasks.CancelAsync(task.Id, Clock.Now, CancellationToken.None).ConfigureAwait(false);
+ return;
+ }
+
+ if (state.Visited.Contains(id) && task.Kind is EngineTaskKind.ProfileCheck or EngineTaskKind.AccountStories)
+ {
+ return;
+ }
+ }
+
+ switch (task.Kind)
+ {
+ case EngineTaskKind.ProfileCheck when account is not null:
+ await RunVisitAsync(task, account, state, manual: false, ct).ConfigureAwait(false);
+ break;
+ case EngineTaskKind.AccountStories when account is not null:
+ await RunStoriesAsync(task, account, state, manual: false, visitNext: null, ct).ConfigureAwait(false);
+ break;
+ case EngineTaskKind.FollowingSweep or EngineTaskKind.Backfill:
+ break;
+ default:
+ await RunGenericAsync(task, account, state, manual: false, ct).ConfigureAwait(false);
+ break;
+ }
+ }
+
+ /// A visit of a profile: the profile check, then (if on) the tagged posts and, for profiles not followed or on request, the stories.
+ private async Task RunVisitAsync(EngineTask task, Account account, SessionState state, bool manual, CancellationToken ct)
+ {
+ var outcome = await RunRecipeAsync(task, new RecipeRequest(RecipeKind.ProfileCheck, account.Id, Manual: manual), account, state, ct).ConfigureAwait(false);
+ if (outcome?.Status != RecipeStatus.Completed)
+ {
+ return;
+ }
+
+ state.Visited.Add(account.Id);
+ var visitNext = state.LastVisitNext;
+ if ((account.ContentTypes & ContentTypes.Tagged) != 0 && !Over(state, ct))
+ {
+ await RunRecipeAsync(null, new RecipeRequest(RecipeKind.Tagged, account.Id, MaxPages: 1, Manual: manual), account, state, ct).ConfigureAwait(false);
+ }
+
+ if (CheckPolicy.WantsStories(account) && (!account.IsFollowed || manual) && !Over(state, ct))
+ {
+ await RunStoriesAsync(null, account, state, manual, account.IsFollowed ? null : visitNext, ct).ConfigureAwait(false);
+ }
+ }
+
+ private async Task RunStoriesAsync(EngineTask? task, Account account, SessionState state, bool manual, DateTimeOffset? visitNext, CancellationToken ct)
+ {
+ state.PendingStoriesNext = visitNext;
+ try
+ {
+ var outcome = await RunRecipeAsync(task, new RecipeRequest(RecipeKind.AccountStories, account.Id, Manual: manual), account, state, ct).ConfigureAwait(false);
+ if (outcome?.Status == RecipeStatus.Completed)
+ {
+ state.Visited.Add(account.Id);
+ }
+ }
+ finally
+ {
+ state.PendingStoriesNext = null;
+ }
+ }
+
+ private async Task RunGenericAsync(EngineTask task, Account? account, SessionState state, bool manual, CancellationToken ct)
+ {
+ var kind = CheckPolicy.RecipeOf(task.Kind);
+ var request = kind switch
+ {
+ RecipeKind.SinglePost => new RecipeRequest(kind, task.AccountId, EntryId: ParseLong(task.Payload), Manual: manual),
+ RecipeKind.Highlight => new RecipeRequest(kind, task.AccountId, HighlightId: task.Payload, Manual: manual),
+ RecipeKind.Tagged or RecipeKind.Reels => new RecipeRequest(kind, task.AccountId, MaxPages: 1, Manual: manual),
+ _ => new RecipeRequest(kind, task.AccountId, Manual: manual),
+ };
+ await RunRecipeAsync(task, request, account, state, ct).ConfigureAwait(false);
+ }
+
+ private async Task RunSweepAsync(EngineTask? task, Dictionary accounts, SessionState state, CancellationToken ct)
+ {
+ var outcome = await RunRecipeAsync(task, new RecipeRequest(RecipeKind.FollowingSweep), null, state, ct).ConfigureAwait(false);
+ if (outcome?.Status != RecipeStatus.Completed)
+ {
+ return;
+ }
+
+ var now = Clock.Now;
+ var flagged = new HashSet(outcome.AccountsWithStories);
+ foreach (var id in flagged)
+ {
+ if (accounts.TryGetValue(id, out var account) && CheckPolicy.IsContactable(account) && CheckPolicy.WantsStories(account))
+ {
+ await Store.Tasks.EnqueueAsync(
+ new EngineTask
+ {
+ Kind = EngineTaskKind.AccountStories,
+ AccountId = id,
+ DueAt = now,
+ Priority = Options.FlaggedStoriesPriority,
+ CreatedAt = now,
+ },
+ CancellationToken.None).ConfigureAwait(false);
+ }
+ }
+
+ // Hypothesis H2: the stories bar showed every followed profile with active stories; the others count as checked.
+ // One timestamp is enough: story checks of followed accounts that come due are postponed while it is recent.
+ _lastSweepAt = now;
+ await Store.Settings.SetInt64Async(EngineSettingKeys.LastSweep, now.ToUnixTimeMilliseconds(), CancellationToken.None).ConfigureAwait(false);
+ }
+
+ /// A followed account needs an explicit story check when neither a sweep nor a check covered its interval.
+ private static bool Uncovered(Account account, TimeSpan interval, DateTimeOffset? lastSweep, DateTimeOffset now) =>
+ now - Latest(account.LastStoriesCheckAt, lastSweep) >= interval;
+
+ private static DateTimeOffset Latest(DateTimeOffset? a, DateTimeOffset? b) =>
+ (a, b) switch
+ {
+ (null, null) => DateTimeOffset.MinValue,
+ (null, { } y) => y,
+ ({ } x, null) => x,
+ ({ } x, { } y) => x > y ? x : y,
+ };
+
+ private async Task LastSweepAsync()
+ {
+ if (_lastSweepLoaded)
+ {
+ return _lastSweepAt;
+ }
+
+ var stored = await Store.Settings.GetInt64Async(EngineSettingKeys.LastSweep, CancellationToken.None).ConfigureAwait(false);
+ _lastSweepAt ??= stored is { } ms ? DateTimeOffset.FromUnixTimeMilliseconds(ms) : null;
+ _lastSweepLoaded = true;
+ return _lastSweepAt;
+ }
+
+ ///
+ /// History advances on one account per session, alternating among the accounts «Storico in corso», each up to its
+ /// daily maximum; suspended while the account has too many files waiting or the data budget is reached (§6.3).
+ ///
+ private async Task RunBackfillAsync(Dictionary accounts, SessionState state, CancellationToken ct)
+ {
+ if (_health.IsSuspended(RecipeKind.Backfill) || state.Exhausted.Contains(ActionKind.BackfillPage))
+ {
+ return;
+ }
+
+ var candidates = accounts.Values
+ .Where(a => a.State == AccountState.Backfilling && a.BackfillCompletedAt is null && CheckPolicy.IsContactable(a))
+ .ToList();
+ if (candidates.Count == 0)
+ {
+ return;
+ }
+
+ var now = Clock.Now;
+ var zone = Clock.LocalZone;
+ var today = LocalCalendar.Today(now, zone);
+ if (await _s.Governor.RemainingTodayAsync(ct).ConfigureAwait(false) <= 0)
+ {
+ await NoticeOnceAsync(
+ EngineEventCodes.BackfillWaiting,
+ null,
+ today,
+ "Storico sospeso: raggiunto il tetto dei dati scaricati di oggi. Riprende domani.",
+ ct).ConfigureAwait(false);
+ return;
+ }
+
+ var tasks = (await Store.Tasks.ListPendingAsync(10_000, ct).ConfigureAwait(false))
+ .Where(t => t.Kind == EngineTaskKind.Backfill && !t.IsManual && t.AccountId is not null)
+ .GroupBy(t => t.AccountId!.Value)
+ .ToDictionary(g => g.Key, g => g.First());
+ var ordered = candidates
+ .OrderBy(a => tasks.TryGetValue(a.Id, out var t) ? t.DueAt : now)
+ .ThenBy(a => a.Id);
+ var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, zone);
+ foreach (var account in ordered)
+ {
+ var pendingFiles = await Store.Media.CountPendingDownloadsAsync(account.Id, ct).ConfigureAwait(false);
+ if (pendingFiles > Options.BackfillMaxPendingDownloads)
+ {
+ await NoticeOnceAsync(
+ EngineEventCodes.BackfillWaiting,
+ account.Id,
+ today,
+ $"Storico di {ItalianText.Handle(account.Username)} in attesa: {ItalianText.Number(pendingFiles)} file da scaricare. Riprende quando la coda scende sotto {ItalianText.Number(Options.BackfillMaxPendingDownloads)}.",
+ ct).ConfigureAwait(false);
+ continue;
+ }
+
+ var permit = await _s.Governor.EvaluateBudgetAsync(ActionKind.BackfillPage, account.Id, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ if (permit.Reason is DenialReason.HourlyBudgetReached or DenialReason.DailyBudgetReached)
+ {
+ state.Exhausted.Add(ActionKind.BackfillPage);
+ return;
+ }
+
+ continue;
+ }
+
+ var budgets = _s.Governor.GetEffectiveBudgets(now);
+ var limit = Math.Min(account.Limits.BackfillPostsPerDay, budgets.BackfillPostsPerAccountPerDay);
+ var postsToday = await Store.Entries.CountDiscoveredAsync(account.Id, EntryKind.Post, dayStart, dayEnd, ct).ConfigureAwait(false);
+ var perPage = Math.Max(1, Options.PostsPerBackfillPage);
+ var pagesAllowed = Math.Max(1, (int)Math.Ceiling((limit - postsToday) / (double)perPage));
+ var pages = Math.Min(_s.Random.CountBetween(Options.BackfillPagesMin, Options.BackfillPagesMax), pagesAllowed);
+ tasks.TryGetValue(account.Id, out var task);
+ await RunRecipeAsync(task, new RecipeRequest(RecipeKind.Backfill, account.Id, MaxPages: pages), account, state, ct).ConfigureAwait(false);
+ return;
+ }
+ }
+
+ /// Runs one recipe with every check around it, then records its outcome. Null when it did not run.
+ private async Task RunRecipeAsync(EngineTask? task, RecipeRequest request, Account? account, SessionState state, CancellationToken ct)
+ {
+ if (_health.IsSuspended(request.Kind))
+ {
+ return null;
+ }
+
+ var category = CheckPolicy.CategoryOf(request.Kind);
+ if (state.Exhausted.Contains(category))
+ {
+ return null;
+ }
+
+ var budget = await _s.Governor.EvaluateBudgetAsync(category, request.AccountId, ct).ConfigureAwait(false);
+ if (!budget.Granted)
+ {
+ if (budget.Reason is DenialReason.HourlyBudgetReached or DenialReason.DailyBudgetReached)
+ {
+ state.Exhausted.Add(category);
+ }
+
+ return null;
+ }
+
+ var context = state.Context;
+ if (state.Recipes > 0)
+ {
+ var pace = GesturePaceFactors.For(_s.Runtime.Profile.Pace);
+ var wait = _s.Random.Between(Options.BetweenRecipesMin, Options.BetweenRecipesMax) * (context.Mood * pace);
+ await Clock.Delay(wait, ct).ConfigureAwait(false);
+ if (Over(state, ct) && !request.Manual)
+ {
+ return null;
+ }
+ }
+
+ if (!_s.Breaker.State.AllowsSiteActions || _s.Runtime.IsPaused || _s.Runtime.UserIsDriving)
+ {
+ state.Stop = true;
+ return null;
+ }
+
+ if (task is not null && !await Store.Tasks.TryStartAsync(task.Id, Clock.Now, ct).ConfigureAwait(false))
+ {
+ return null;
+ }
+
+ state.Recipes++;
+ _s.Runtime.Activity = ActivityText(request.Kind, account);
+ _s.Events.Publish(EngineNotificationKind.ActivityChanged);
+ RecipeOutcome outcome;
+ try
+ {
+ outcome = await _runner.RunAsync(request, context, ct).ConfigureAwait(false);
+ }
+ catch (OperationCanceledException)
+ {
+ if (task is not null)
+ {
+ await RequeueAsync(task, "Interrotta", Clock.Now).ConfigureAwait(false);
+ }
+
+ throw;
+ }
+ catch (Exception ex) when (ex is not OutOfMemoryException)
+ {
+ // The message of an unexpected exception may carry data of the page: only its type is kept.
+ outcome = new RecipeOutcome(RecipeStatus.Failed, 0, 0, $"Errore imprevisto ({ex.GetType().Name}).");
+ }
+ finally
+ {
+ _s.Runtime.Activity = null;
+ }
+
+ context.AddNewEntries(outcome.NewEntries);
+ await ApplyOutcomeAsync(task, request, account, outcome, state).ConfigureAwait(false);
+ _s.Events.Publish(EngineNotificationKind.ActivityChanged);
+ return outcome;
+ }
+
+ private async Task ApplyOutcomeAsync(EngineTask? task, RecipeRequest request, Account? account, RecipeOutcome outcome, SessionState state)
+ {
+ // Bookkeeping always completes, even when the session has just been cancelled. Independent writes are queued
+ // together (the single writer keeps their order and commits them in one transaction).
+ var ct = CancellationToken.None;
+ var now = Clock.Now;
+ var kind = request.Kind;
+ var writes = new List();
+ switch (outcome.Status)
+ {
+ case RecipeStatus.Completed:
+ await _health.RecordSuccessAsync(kind, ct).ConfigureAwait(false);
+ await OnCheckedAsync(task, request, account, outcome, state, now, writes, ct).ConfigureAwait(false);
+ break;
+
+ case RecipeStatus.Denied:
+ if (task is not null)
+ {
+ await RequeueAsync(task, "Rimandata: tetto raggiunto", now).ConfigureAwait(false);
+ }
+
+ var recheck = await _s.Governor.EvaluateBudgetAsync(CheckPolicy.CategoryOf(kind), request.AccountId, ct).ConfigureAwait(false);
+ if (recheck.Reason is DenialReason.HourlyBudgetReached or DenialReason.DailyBudgetReached)
+ {
+ state.Exhausted.Add(CheckPolicy.CategoryOf(kind));
+ }
+ else if (recheck.Reason is DenialReason.BreakerOpen or DenialReason.OutsideActiveWindow or DenialReason.Paused or DenialReason.UserIsDriving)
+ {
+ state.Stop = true;
+ }
+
+ break;
+
+ case RecipeStatus.StoppedBySignal:
+ case RecipeStatus.Cancelled:
+ if (task is not null)
+ {
+ await RequeueAsync(task, outcome.Status == RecipeStatus.Cancelled ? "Interrotta" : "Fermata da un segnale", now).ConfigureAwait(false);
+ }
+
+ state.Stop = true;
+ break;
+
+ case RecipeStatus.TargetNotFound:
+ if (task is not null)
+ {
+ await RequeueAsync(task, "Bersaglio non trovato", now).ConfigureAwait(false);
+ }
+
+ await RecordRecipeFailureAsync(kind, account, EngineEventCodes.TargetNotFound,
+ $"Non trovo nella pagina ciò che serve per {RecipeName(kind)}{Of(account)}: mi fermo e lo segnalo, senza cliccare a caso.", now).ConfigureAwait(false);
+ state.Stop = true;
+ break;
+
+ case RecipeStatus.UnrecognizedFormat:
+ // The check took place: plan the next one as usual instead of insisting.
+ await OnCheckedAsync(task, request, account, outcome, state, now, writes, ct).ConfigureAwait(false);
+ if (account is not null)
+ {
+ await Store.Accounts.AddNoticesAsync(account.Id, AccountNotices.UnrecognizedFormat, now, ct).ConfigureAwait(false);
+ }
+
+ await RecordRecipeFailureAsync(kind, account, EngineEventCodes.FormatUnrecognized,
+ $"Formato non riconosciuto in {RecipeName(kind)}{Of(account)}: Instagram potrebbe aver cambiato le sue risposte.", now).ConfigureAwait(false);
+ break;
+
+ case RecipeStatus.AccountUnreachable:
+ if (task is not null)
+ {
+ await Store.Tasks.CompleteAsync(task.Id, now, ct).ConfigureAwait(false);
+ }
+
+ if (account is not null)
+ {
+ if (account.State != AccountState.Unreachable)
+ {
+ await Store.Accounts.SetStateAsync(account.Id, AccountState.Unreachable, now, account.UnreachableReason, ct).ConfigureAwait(false);
+ }
+
+ await Store.Tasks.CancelForAccountAsync(account.Id, now, ct).ConfigureAwait(false);
+ await _s.Events.WriteAsync(
+ EventSeverity.Warning,
+ EngineEventCodes.AccountUnreachable,
+ $"{ItalianText.Handle(account.Username)} non è raggiungibile (privato non seguito, inesistente o bloccato): Febe smette di controllarlo. Lo trovi fra gli account «Da controllare».",
+ account.Id,
+ state.Context.SessionId,
+ ct).ConfigureAwait(false);
+ }
+
+ break;
+
+ default:
+ if (task is not null)
+ {
+ await Store.Tasks.FailAsync(task.Id, now, outcome.Message ?? "Non riuscita", now + TimeSpan.FromHours(1), ct).ConfigureAwait(false);
+ }
+
+ await _s.Events.WriteAsync(
+ EventSeverity.Warning,
+ EngineEventCodes.RecipeFailed,
+ $"{ItalianText.Capitalize(RecipeName(kind))}{Of(account)} non è riuscito: {outcome.Message ?? "errore sconosciuto"}. Riprovo più tardi.",
+ account?.Id,
+ state.Context.SessionId,
+ ct).ConfigureAwait(false);
+ break;
+ }
+
+ var (title, detail) = Describe(kind, account, outcome);
+ _recent.Add(new RecentAction(now, kind, account?.Id, title, detail, outcome.Status, outcome.NewEntries));
+ var severity = outcome.Status switch
+ {
+ RecipeStatus.Completed => outcome.NewEntries > 0 ? EventSeverity.Success : EventSeverity.Info,
+ RecipeStatus.Denied or RecipeStatus.Cancelled => EventSeverity.Info,
+ _ => EventSeverity.Warning,
+ };
+ writes.Add(_s.Events.WriteAsync(severity, EngineEventCodes.RecipePrefix + kind, title + ": " + detail, account?.Id, state.Context.SessionId, ct));
+ await Task.WhenAll(writes).ConfigureAwait(false);
+ }
+
+ /// Check times, next task and state changes after a check that took place.
+ private async Task OnCheckedAsync(
+ EngineTask? task,
+ RecipeRequest request,
+ Account? account,
+ RecipeOutcome outcome,
+ SessionState state,
+ DateTimeOffset now,
+ List writes,
+ CancellationToken ct)
+ {
+ if (task is not null)
+ {
+ writes.Add(Store.Tasks.CompleteAsync(task.Id, now, ct));
+ }
+
+ if (account is null)
+ {
+ return;
+ }
+
+ var window = await WindowLengthAsync(now, ct).ConfigureAwait(false);
+ var contactable = CheckPolicy.IsContactable(account);
+ switch (request.Kind)
+ {
+ case RecipeKind.ProfileCheck:
+ {
+ // A profile not followed is visited at the earlier of its post check and its story check.
+ var next = now + CheckPolicy.NextCheckDelay(_s.Random, CheckPolicy.ProfileCheckInterval(account));
+ DateTimeOffset? storiesNext = !account.IsFollowed && CheckPolicy.WantsStories(account)
+ ? now + CheckPolicy.NextStoryCheckDelay(_s.Random, CheckPolicy.StoryInterval(account, window, Options.MinimumStoryChecksPerDay))
+ : null;
+ state.LastVisitNext = storiesNext;
+ var due = storiesNext is { } sn && sn < next ? sn : next;
+ writes.Add(Store.Accounts.UpdateChecksAsync(account.Id, new AccountCheckTimes { LastProfileCheckAt = now, NextProfileCheckAt = next }, ct));
+ if (contactable)
+ {
+ writes.Add(Store.Tasks.EnqueueAsync(
+ new EngineTask { Kind = EngineTaskKind.ProfileCheck, AccountId = account.Id, DueAt = due, CreatedAt = now },
+ ct));
+ }
+
+ if (!account.KeepUpdated && account.State == AccountState.UpToDate)
+ {
+ await PauseAfterSingleDownloadAsync(account, now, state, ct).ConfigureAwait(false);
+ }
+
+ break;
+ }
+
+ case RecipeKind.AccountStories:
+ {
+ var next = state.PendingStoriesNext
+ ?? now + CheckPolicy.NextStoryCheckDelay(_s.Random, CheckPolicy.StoryInterval(account, window, Options.MinimumStoryChecksPerDay));
+ writes.Add(Store.Accounts.UpdateChecksAsync(account.Id, new AccountCheckTimes { LastStoriesCheckAt = now, NextStoriesCheckAt = next }, ct));
+ if (contactable && (account.IsFollowed ? !Options.SweepCoversFollowedStories : !CheckPolicy.WantsProfileChecks(account)))
+ {
+ writes.Add(Store.Tasks.EnqueueAsync(
+ new EngineTask { Kind = EngineTaskKind.AccountStories, AccountId = account.Id, DueAt = next, CreatedAt = now },
+ ct));
+ }
+
+ break;
+ }
+
+ case RecipeKind.Backfill when outcome.BackfillFinished:
+ {
+ var fresh = await Store.Accounts.GetAsync(account.Id, ct).ConfigureAwait(false) ?? account;
+ await Store.Accounts.SetBackfillAsync(account.Id, fresh.BackfillCursor, now, ct).ConfigureAwait(false);
+ var newState = fresh.KeepUpdated ? AccountState.UpToDate : AccountState.Paused;
+ await Store.Accounts.SetStateAsync(account.Id, newState, now, null, ct).ConfigureAwait(false);
+ var total = await Store.Entries.CountDiscoveredAsync(account.Id, EntryKind.Post, DateTimeOffset.UnixEpoch, now.AddSeconds(1), ct).ConfigureAwait(false);
+ var tail = fresh.KeepUpdated
+ ? " Da ora lo tengo aggiornato."
+ : " «Tieni aggiornato» è spento: l'account resta in pausa.";
+ await _s.Events.WriteAsync(
+ EventSeverity.Success,
+ EngineEventCodes.BackfillCompleted,
+ $"Storico di {ItalianText.Handle(account.Username)} completato: {ItalianText.Count(total, "post", "post")} in libreria.{tail}",
+ account.Id,
+ state.Context.SessionId,
+ ct).ConfigureAwait(false);
+ break;
+ }
+
+ case RecipeKind.Backfill:
+ if (contactable)
+ {
+ // Behind the other accounts «Storico in corso»: they alternate.
+ writes.Add(Store.Tasks.EnqueueAsync(
+ new EngineTask { Kind = EngineTaskKind.Backfill, AccountId = account.Id, DueAt = now, CreatedAt = now },
+ ct));
+ }
+
+ break;
+ }
+ }
+
+ private async Task PauseAfterSingleDownloadAsync(Account account, DateTimeOffset now, SessionState state, CancellationToken ct)
+ {
+ await Store.Accounts.SetStateAsync(account.Id, AccountState.Paused, now, null, ct).ConfigureAwait(false);
+ await Store.Tasks.CancelForAccountAsync(account.Id, now, ct).ConfigureAwait(false);
+ await _s.Events.WriteAsync(
+ EventSeverity.Info,
+ EngineEventCodes.AccountPaused,
+ $"{ItalianText.Handle(account.Username)}: scaricamento unico fatto. «Tieni aggiornato» è spento, quindi l'account resta in pausa.",
+ account.Id,
+ state.Context.SessionId,
+ ct).ConfigureAwait(false);
+ }
+
+ private async Task RecordRecipeFailureAsync(RecipeKind kind, Account? account, string code, string message, DateTimeOffset now)
+ {
+ var ct = CancellationToken.None;
+ var suspended = await _health.RecordFailureAsync(kind, now, ct).ConfigureAwait(false);
+ var count = _health.Failures(kind);
+ var threshold = Options.ConsecutiveFailuresToSuspend;
+ await _s.Events.WriteAsync(
+ EventSeverity.Warning,
+ code,
+ message + (count < threshold ? $" ({ItalianText.Number(count)} di {ItalianText.Number(threshold)} di fila)" : string.Empty),
+ account?.Id,
+ ct: ct).ConfigureAwait(false);
+ if (suspended)
+ {
+ await _s.Events.WriteAsync(
+ EventSeverity.Error,
+ EngineEventCodes.RecipeSuspended,
+ $"«{ItalianText.Capitalize(RecipeName(kind))}» è sospeso dopo {ItalianText.Number(threshold)} problemi di fila: Instagram potrebbe essere cambiato. Serve un campione nuovo con la modalità sonda; poi si riattiva da Attività.",
+ account?.Id,
+ ct: ct).ConfigureAwait(false);
+ }
+ }
+
+ private async Task RequeueAsync(EngineTask task, string reason, DateTimeOffset retryAt) =>
+ await Store.Tasks.FailAsync(task.Id, Clock.Now, reason, retryAt, CancellationToken.None).ConfigureAwait(false);
+
+ private async Task NoticeOnceAsync(string code, long? accountId, DateOnly day, string message, CancellationToken ct)
+ {
+ lock (_noticeGate)
+ {
+ if (!_notices.Add((code, accountId, day)))
+ {
+ return;
+ }
+ }
+
+ await _s.Events.WriteAsync(EventSeverity.Info, code, message, accountId, ct: ct).ConfigureAwait(false);
+ }
+
+ private static long? ParseLong(string? text) =>
+ long.TryParse(text, System.Globalization.NumberStyles.Integer, System.Globalization.CultureInfo.InvariantCulture, out var value) ? value : null;
+
+ private static string Of(Account? account) => account is null ? string.Empty : " di " + ItalianText.Handle(account.Username);
+
+ /// Italian name of a recipe, lower case: «il controllo del profilo».
+ internal static string RecipeName(RecipeKind kind) => kind switch
+ {
+ RecipeKind.FollowingSweep => "il giro dei profili che segui",
+ RecipeKind.AccountStories => "le storie",
+ RecipeKind.ProfileCheck => "il controllo del profilo",
+ RecipeKind.Backfill => "lo storico",
+ RecipeKind.Highlight => "le storie in evidenza",
+ RecipeKind.Tagged => "i post in cui è taggato",
+ RecipeKind.Reels => "i reel",
+ RecipeKind.SinglePost => "il post singolo",
+ RecipeKind.FollowingList => "l'elenco dei profili che segui",
+ _ => kind.ToString(),
+ };
+
+ /// What the engine is doing, for the monitor: «Sto guardando le storie di @marta.demo».
+ internal static string ActivityText(RecipeKind kind, Account? account)
+ {
+ var who = ItalianText.Handle(account?.Username);
+ return kind switch
+ {
+ RecipeKind.FollowingSweep => "Sto facendo il giro dei profili che segui",
+ RecipeKind.AccountStories => $"Sto guardando le storie di {who}",
+ RecipeKind.ProfileCheck => $"Sto controllando il profilo di {who}",
+ RecipeKind.Backfill => $"Sto scorrendo lo storico di {who}",
+ RecipeKind.Highlight => $"Sto guardando le storie in evidenza di {who}",
+ RecipeKind.Tagged => $"Sto guardando i post in cui è taggato {who}",
+ RecipeKind.Reels => $"Sto guardando i reel di {who}",
+ RecipeKind.SinglePost => $"Sto aprendo un post di {who}",
+ RecipeKind.FollowingList => "Sto leggendo l'elenco dei profili che segui",
+ _ => "Sto lavorando",
+ };
+ }
+
+ internal static (string Title, string Detail) Describe(RecipeKind kind, Account? account, RecipeOutcome outcome)
+ {
+ var title = kind switch
+ {
+ RecipeKind.FollowingSweep => "Giro dei profili che segui",
+ RecipeKind.FollowingList => "Elenco dei profili che segui",
+ _ => ItalianText.Handle(account?.Username),
+ };
+
+ var detail = outcome.Status switch
+ {
+ RecipeStatus.Completed => kind switch
+ {
+ RecipeKind.FollowingSweep => SweepDetail(outcome),
+ RecipeKind.AccountStories => outcome.NewEntries > 0 ? ItalianText.Count(outcome.NewEntries, "storia nuova", "storie nuove") : "Nessuna storia nuova",
+ RecipeKind.Backfill => outcome.BackfillFinished
+ ? "Storico completato"
+ : "Storico, " + ItalianText.Count(outcome.NewEntries, "post", "post"),
+ RecipeKind.Highlight => outcome.NewEntries > 0 ? "In evidenza, " + ItalianText.Count(outcome.NewEntries, "contenuto nuovo", "contenuti nuovi") : "In evidenza, nessuna novità",
+ RecipeKind.Tagged => outcome.NewEntries > 0 ? "Taggati, " + ItalianText.Count(outcome.NewEntries, "post nuovo", "post nuovi") : "Taggati, nessuna novità",
+ RecipeKind.FollowingList => "Lettura completata",
+ _ => outcome.NewEntries > 0 ? ItalianText.Count(outcome.NewEntries, "contenuto nuovo", "contenuti nuovi") : "Nessuna novità",
+ },
+ RecipeStatus.Denied => "Rimandato: tetto raggiunto",
+ RecipeStatus.StoppedBySignal => "Fermato da un segnale di Instagram",
+ RecipeStatus.TargetNotFound => "Bersaglio non trovato nella pagina",
+ RecipeStatus.UnrecognizedFormat => "Formato non riconosciuto",
+ RecipeStatus.AccountUnreachable => "Non raggiungibile",
+ RecipeStatus.Cancelled => "Interrotto",
+ _ => "Non riuscito",
+ };
+ return (title, detail);
+ }
+
+ private static string SweepDetail(RecipeOutcome outcome)
+ {
+ var parts = new List();
+ if (outcome.AccountsWithNewPosts.Count > 0)
+ {
+ parts.Add(ItalianText.Count(outcome.AccountsWithNewPosts.Count, "account con novità", "account con novità"));
+ }
+ else if (outcome.NewEntries > 0)
+ {
+ parts.Add(ItalianText.Count(outcome.NewEntries, "contenuto nuovo", "contenuti nuovi"));
+ }
+
+ if (outcome.AccountsWithStories.Count > 0)
+ {
+ parts.Add(ItalianText.Count(outcome.AccountsWithStories.Count, "con storie da vedere", "con storie da vedere"));
+ }
+
+ return parts.Count == 0 ? "Nessuna novità" : string.Join(", ", parts);
+ }
+
+ private sealed class SessionState(SessionContext context)
+ {
+ public SessionContext Context { get; } = context;
+
+ public HashSet Exhausted { get; } = [];
+
+ /// Accounts whose profile or stories were checked in this session.
+ public HashSet Visited { get; } = [];
+
+ /// Commands of Alberto already taken up in this session.
+ public HashSet ManualDone { get; } = [];
+
+ public bool Stop { get; set; }
+
+ public int Recipes { get; set; }
+
+ /// Next story check planned by the last visit of a profile not followed.
+ public DateTimeOffset? LastVisitNext { get; set; }
+
+ /// Set while the stories of a visit run: their next check is the visit's.
+ public DateTimeOffset? PendingStoriesNext { get; set; }
+
+ public SessionSummary Summary() => new(Recipes, Stop);
+ }
+}
+
+/// What a session did, for its row and its timeline line.
+internal sealed record SessionSummary(int Recipes, bool StoppedEarly);
diff --git a/src/Febe.Core/Simulation/EngineSimulation.cs b/src/Febe.Core/Simulation/EngineSimulation.cs
new file mode 100644
index 0000000..59d411f
--- /dev/null
+++ b/src/Febe.Core/Simulation/EngineSimulation.cs
@@ -0,0 +1,94 @@
+using System.Diagnostics;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Simulation;
+
+/// Options of --simula (spec §14.3).
+public sealed record SimulationOptions
+{
+ public int Days { get; init; } = 30;
+
+ public CautionProfileKind Profile { get; init; } = CautionProfileKind.Prudent;
+
+ /// Seed of the engine; the world uses a seed derived from it unless sets one.
+ public int Seed { get; init; } = 1;
+
+ /// Program start; by default 14 October 2026 at 6:00 in Rome.
+ public DateTimeOffset? Start { get; init; }
+
+ public TimeZoneInfo? Zone { get; init; }
+
+ public SimulatedWorldOptions? World { get; init; }
+
+ public EngineOptions? Engine { get; init; }
+
+ /// Full engine settings (e.g. a «Su misura» profile); when null, with the other defaults.
+ public EngineSettings? Settings { get; init; }
+}
+
+///
+/// Runs the real engine (Governor, breaker, planner, scheduler) under the virtual clock against the simulated world,
+/// on a real database, and builds the report Alberto reads to judge a profile (spec §14.3).
+///
+public static class EngineSimulation
+{
+ /// What to simulate.
+ /// Opens an empty database (e.g. FebeDatabase.OpenAsync in a temporary folder).
+ /// Cancellation.
+ public static async Task RunAsync(
+ SimulationOptions options,
+ Func> openStorage,
+ CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(options);
+ ArgumentNullException.ThrowIfNull(openStorage);
+ if (options.Days < 1)
+ {
+ throw new ArgumentOutOfRangeException(nameof(options), options.Days, "Servono almeno un giorno di simulazione.");
+ }
+
+ var stopwatch = Stopwatch.StartNew();
+ var zone = options.Zone ?? SimulationZones.Rome;
+ var start = options.Start ?? LocalCalendar.FromLocal(new DateTime(2026, 10, 14, 6, 0, 0), zone);
+ // Whole local days: the run ends at the midnight after the last one.
+ var end = LocalCalendar.StartOfDay(LocalCalendar.Today(start, zone).AddDays(options.Days), zone);
+ var storage = await openStorage(ct).ConfigureAwait(false);
+ await using (storage.ConfigureAwait(false))
+ {
+ var clock = new VirtualClock(start, zone);
+ await EngineSettingsStore.SaveAsync(storage.Settings, options.Settings ?? new EngineSettings { ProfileKind = options.Profile }, ct).ConfigureAwait(false);
+ var services = await EngineServices.CreateAsync(storage, clock, new SeededRandom(options.Seed), options.Engine, ct: ct).ConfigureAwait(false);
+ var worldOptions = options.World ?? new SimulatedWorldOptions { Seed = options.Seed };
+ var world = new SimulatedWorld(storage, services.Governor, services.Governor, services.Breaker, clock, worldOptions);
+ await world.InitializeAsync(start, end, services.Runtime.Profile, ct).ConfigureAwait(false);
+
+ var host = new EngineHost(services, world);
+ await using (host.ConfigureAwait(false))
+ {
+ using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
+ var loop = host.RunAsync(cts.Token);
+ try
+ {
+ await clock.RunUntilAsync(end, ct, loop).ConfigureAwait(false);
+ }
+ finally
+ {
+ await cts.CancelAsync().ConfigureAwait(false);
+ try
+ {
+ await loop.ConfigureAwait(false);
+ }
+ catch (OperationCanceledException)
+ {
+ }
+ }
+ }
+
+ await services.Breaker.FlushAsync().ConfigureAwait(false);
+ return await SimulationReport.BuildAsync(storage, world, services, options, start, end, clock.FiredTimers, stopwatch.Elapsed, ct).ConfigureAwait(false);
+ }
+ }
+}
diff --git a/src/Febe.Core/Simulation/SimulatedWorld.cs b/src/Febe.Core/Simulation/SimulatedWorld.cs
new file mode 100644
index 0000000..1ca1161
--- /dev/null
+++ b/src/Febe.Core/Simulation/SimulatedWorld.cs
@@ -0,0 +1,691 @@
+using System.Globalization;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Pacing;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Simulation;
+
+/// The fake world of the simulation (spec §14.3).
+public sealed record SimulatedWorldOptions
+{
+ public int FollowedAccounts { get; init; } = 25;
+
+ public int NotFollowedAccounts { get; init; } = 15;
+
+ /// Average posts per account per day (one every three days), with rates varying among accounts.
+ public double MeanPostsPerDay { get; init; } = 1.0 / 3.0;
+
+ /// Share of accounts that post stories every day.
+ public double StoryAccountShare { get; init; } = 0.5;
+
+ /// Posts of history of the first account, to download with the backfill (0 for none).
+ public int HistoricalPosts { get; init; } = 2000;
+
+ /// Probability that a counted action meets a throttle signal («qualche rallentamento inserito a caso»).
+ public double ThrottleProbabilityPerAction { get; init; } = 0.0003;
+
+ /// Seed of the world, independent of the engine's.
+ public int Seed { get; init; } = 1;
+
+ /// Check frequency of the account with this index: by default one in ten High, two in ten Low, the rest Normal.
+ public Func FrequencyOf { get; init; } = i => (i % 10) switch
+ {
+ 0 => Frequency.High,
+ 1 or 2 => Frequency.Low,
+ _ => Frequency.Normal,
+ };
+
+ /// Gesture pace of the simulated recipes.
+ public GesturePace Pace { get; init; } = GesturePace.Natural;
+}
+
+/// What the world saw happen: discoveries, story checks, backfill, throttles.
+public sealed class WorldStats
+{
+ /// Publication and discovery of every new post found (history excluded).
+ public List<(DateTimeOffset Published, DateTimeOffset Discovered, bool Followed)> PostDiscoveries { get; } = [];
+
+ /// Publication and viewing of every story seen.
+ public List<(DateTimeOffset Published, DateTimeOffset Seen)> StoryViews { get; } = [];
+
+ /// Completed explicit story checks per account and local day.
+ public Dictionary<(long Account, DateOnly Day), int> StoryChecks { get; } = [];
+
+ /// Completed sweeps per local day (each one reads the stories bar of every followed account).
+ public Dictionary Sweeps { get; } = [];
+
+ /// Runs per recipe and status.
+ public Dictionary<(RecipeKind Kind, RecipeStatus Status), int> Runs { get; } = [];
+
+ public long? BackfillAccountId { get; set; }
+
+ public int BackfillPostsStored { get; set; }
+
+ public DateTimeOffset? BackfillFinishedAt { get; set; }
+
+ public int ThrottlesReported { get; set; }
+
+ public int ProfileOpensOutsideRecipes { get; set; }
+}
+
+///
+/// A fake Instagram for the simulation: implements by asking the real Governor for every
+/// counted action, spending virtual time like the gestures of spec §7.7, storing entries in the real database and
+/// «downloading» their files within the data budget. It never opens anything: there is no browser.
+///
+///
+/// The world's behaviour (H2: the stories bar shows which followed profiles have stories; twelve posts per page of
+/// history; a sweep sees up to three posts per scroll burst) is an assumption of the simulation, not a fact about Instagram.
+///
+public sealed class SimulatedWorld : IRecipeRunner
+{
+ private const int PostsPerPage = 12;
+ private const int PostsPerBurst = 3;
+ private const long MB = 1024 * 1024;
+
+ private readonly IFebeStorage _storage;
+ private readonly IGovernor _governor;
+ private readonly IDataBudget _data;
+ private readonly ICircuitBreaker _breaker;
+ private readonly IClock _clock;
+ private readonly IRandomSource _random;
+ private readonly SimulatedWorldOptions _options;
+ private readonly List _accounts = [];
+ private readonly Dictionary _byId = [];
+ private readonly List _pending = [];
+ private long _fileCounter;
+
+ public SimulatedWorld(
+ IFebeStorage storage,
+ IGovernor governor,
+ IDataBudget data,
+ ICircuitBreaker breaker,
+ IClock clock,
+ SimulatedWorldOptions? options = null)
+ {
+ _storage = storage ?? throw new ArgumentNullException(nameof(storage));
+ _governor = governor ?? throw new ArgumentNullException(nameof(governor));
+ _data = data ?? throw new ArgumentNullException(nameof(data));
+ _breaker = breaker ?? throw new ArgumentNullException(nameof(breaker));
+ _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+ _options = options ?? new SimulatedWorldOptions();
+ _random = new SeededRandom(unchecked((_options.Seed * 7919) + 13));
+ }
+
+ public WorldStats Stats { get; } = new();
+
+ public IReadOnlyList Accounts => _accounts;
+
+ private double Pace => GesturePaceFactors.For(_options.Pace);
+
+ /// Creates the accounts in the database and the publications of the period [start, end).
+ public async Task InitializeAsync(DateTimeOffset start, DateTimeOffset end, CautionProfile profile, CancellationToken ct = default)
+ {
+ ArgumentNullException.ThrowIfNull(profile);
+ var zone = _clock.LocalZone;
+ var total = _options.FollowedAccounts + _options.NotFollowedAccounts;
+ for (var i = 0; i < total; i++)
+ {
+ var followed = i < _options.FollowedAccounts;
+ var username = string.Create(CultureInfo.InvariantCulture, $"{(followed ? "seguito" : "pubblico")}{i + 1:00}.demo");
+
+ // Rates are log-normal around the mean (σ 0.9): some accounts post daily, some once a month.
+ var rate = _options.MeanPostsPerDay / Math.Exp(0.9 * 0.9 / 2) * Math.Exp(0.9 * _random.StandardNormal());
+ var historical = i == 0 ? _options.HistoricalPosts : 0;
+ var account = Account.Create(username, StartingPoint.EverythingAndKeepUpdated, start, zone, profile) with
+ {
+ InstagramId = (9_000_000 + i).ToString(CultureInfo.InvariantCulture),
+ IsFollowed = followed,
+ Frequency = _options.FrequencyOf(i),
+ State = historical > 0 ? AccountState.Backfilling : AccountState.UpToDate,
+ BackfillCompletedAt = historical > 0 ? null : start,
+ PostCount = historical,
+ };
+ var stored = await _storage.Accounts.AddAsync(account, ct).ConfigureAwait(false);
+ var share = _options.StoryAccountShare;
+ var postsStories = Math.Floor((i + 1) * share) > Math.Floor(i * share);
+ var sim = new SimAccount(stored.Id, username, followed, i, rate, postsStories);
+ if (historical > 0)
+ {
+ Stats.BackfillAccountId = stored.Id;
+ for (var h = 0; h < historical; h++)
+ {
+ // Newest first, about one every two days before the start.
+ sim.History.Add(new SimPost(Id(i, "h", h), start - TimeSpan.FromHours(6 + (h * 47.3)), 1 + (h % 4 == 0 ? 2 : 0), h % 5 == 0));
+ }
+ }
+
+ Generate(sim, start, end, zone);
+ _accounts.Add(sim);
+ _byId[sim.Id] = sim;
+ }
+ }
+
+ public async Task RunAsync(RecipeRequest request, ISessionContext session, CancellationToken ct)
+ {
+ ArgumentNullException.ThrowIfNull(request);
+ ArgumentNullException.ThrowIfNull(session);
+ await DownloadPendingAsync(ct).ConfigureAwait(false);
+ var outcome = request.Kind switch
+ {
+ RecipeKind.FollowingSweep => await SweepAsync(session, ct).ConfigureAwait(false),
+ RecipeKind.ProfileCheck => await ProfileAsync(Get(request), session, ct).ConfigureAwait(false),
+ RecipeKind.AccountStories => await StoriesAsync(Get(request), session, ct).ConfigureAwait(false),
+ RecipeKind.Backfill => await BackfillAsync(Get(request), request.MaxPages ?? 5, session, ct).ConfigureAwait(false),
+ RecipeKind.SinglePost => await SimpleAsync(ActionKind.SinglePost, request.AccountId, session, ct).ConfigureAwait(false),
+ RecipeKind.FollowingList => await SimpleAsync(ActionKind.FollowingListPage, null, session, ct).ConfigureAwait(false),
+ _ => await SimpleAsync(ActionKind.ProfileOpen, request.AccountId, session, ct).ConfigureAwait(false),
+ };
+ var key = (request.Kind, outcome.Status);
+ Stats.Runs[key] = Stats.Runs.GetValueOrDefault(key) + 1;
+ return outcome;
+ }
+
+ public Task RestAsync(CancellationToken ct) => Task.CompletedTask;
+
+ /// Stories published in [start, end) that expired before anyone saw them.
+ public int MissedStories(DateTimeOffset start, DateTimeOffset end) =>
+ _accounts.Sum(a => a.Stories.Count(s => s.PublishedAt >= start && s.ExpiresAt <= end && s.SeenAt is null));
+
+ /// New posts published in [start, end) not yet discovered at the end.
+ public int UndiscoveredPosts(DateTimeOffset start, DateTimeOffset end) =>
+ _accounts.Sum(a => a.Posts.Count(p => p.PublishedAt >= start && p.PublishedAt < end && p.DiscoveredAt is null));
+
+ /// Stories published in [start, end).
+ public int PublishedStories(DateTimeOffset start, DateTimeOffset end) =>
+ _accounts.Sum(a => a.Stories.Count(s => s.PublishedAt >= start && s.PublishedAt < end));
+
+ /// Posts published in [start, end).
+ public int PublishedPosts(DateTimeOffset start, DateTimeOffset end) =>
+ _accounts.Sum(a => a.Posts.Count(p => p.PublishedAt >= start && p.PublishedAt < end));
+
+ private SimAccount Get(RecipeRequest request) =>
+ request.AccountId is { } id && _byId.TryGetValue(id, out var account)
+ ? account
+ : throw new InvalidOperationException("Account sconosciuto al mondo simulato.");
+
+ private void Generate(SimAccount account, DateTimeOffset start, DateTimeOffset end, TimeZoneInfo zone)
+ {
+ var first = LocalCalendar.Today(start, zone);
+ var last = LocalCalendar.Today(end, zone);
+ for (var day = first; day <= last; day = day.AddDays(1))
+ {
+ var posts = Poisson(account.PostRate);
+ for (var p = 0; p < posts; p++)
+ {
+ var at = DaytimeInstant(day, zone);
+ if (at >= start && at < end)
+ {
+ account.Posts.Add(new SimPost(Id(account.Index, "p", account.Posts.Count), at, 1 + Poisson(0.6), _random.Chance(0.25)));
+ }
+ }
+
+ if (account.PostsStories)
+ {
+ var stories = 1 + Poisson(1.5);
+ for (var s = 0; s < stories; s++)
+ {
+ var at = DaytimeInstant(day, zone);
+ if (at >= start && at < end)
+ {
+ var video = _random.Chance(0.3);
+ account.Stories.Add(new SimStory(
+ Id(account.Index, "s", account.Stories.Count),
+ at,
+ at + TimeSpan.FromHours(24),
+ video,
+ video ? TimeSpan.FromSeconds(5 + (10 * _random.NextDouble())) : TimeSpan.Zero));
+ }
+ }
+ }
+ }
+
+ account.Posts.Sort((a, b) => a.PublishedAt.CompareTo(b.PublishedAt));
+ account.Stories.Sort((a, b) => a.PublishedAt.CompareTo(b.PublishedAt));
+ }
+
+ private DateTimeOffset DaytimeInstant(DateOnly day, TimeZoneInfo zone)
+ {
+ // People post mostly between 8:00 and 23:30.
+ var minutes = 8 * 60 + (_random.NextDouble() * 15.5 * 60);
+ return LocalCalendar.FromLocal(day.ToDateTime(TimeOnly.MinValue).AddMinutes(minutes), zone);
+ }
+
+ private int Poisson(double mean)
+ {
+ var limit = Math.Exp(-mean);
+ var product = _random.NextDouble();
+ var count = 0;
+ while (product > limit && count < 50)
+ {
+ count++;
+ product *= _random.NextDouble();
+ }
+
+ return count;
+ }
+
+ private static string Id(int account, string kind, int n) =>
+ string.Create(CultureInfo.InvariantCulture, $"{account + 1:000}{kind}{n:00000}");
+
+ private async Task SweepAsync(ISessionContext session, CancellationToken ct)
+ {
+ var permit = await AskAsync(ActionKind.Home, null, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ return Denied(0, 0);
+ }
+
+ if (permit.Throttled)
+ {
+ return Signal(1, 0);
+ }
+
+ await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
+ var bursts = _random.CountBetween(3, 8);
+ var now = _clock.Now;
+ var visible = _accounts
+ .Where(a => a.Followed)
+ .SelectMany(a => a.Posts.Where(p => p.PublishedAt <= now && p.DiscoveredAt is null).Select(p => (Account: a, Post: p)))
+ .OrderByDescending(x => x.Post.PublishedAt)
+ .Take(bursts * PostsPerBurst)
+ .ToList();
+ for (var b = 0; b < bursts; b++)
+ {
+ await WaitAsync(session, 0.4, 4, 1.1, ct).ConfigureAwait(false);
+ }
+
+ if (bursts >= 6)
+ {
+ await WaitAsync(session, 3, 20, 6, ct).ConfigureAwait(false);
+ }
+
+ now = _clock.Now;
+ foreach (var group in visible.GroupBy(v => v.Account))
+ {
+ await StorePostsAsync(group.Key, [.. group.Select(g => g.Post)], now, history: false, ct).ConfigureAwait(false);
+ }
+
+ var day = LocalCalendar.Today(now, _clock.LocalZone);
+ Stats.Sweeps[day] = Stats.Sweeps.GetValueOrDefault(day) + 1;
+ var withStories = _accounts
+ .Where(a => a.Followed && a.Stories.Any(s => s.PublishedAt <= now && s.ExpiresAt > now && s.SeenAt is null))
+ .Select(a => a.Id)
+ .ToList();
+ return new RecipeOutcome(RecipeStatus.Completed, 1, visible.Count)
+ {
+ AccountsWithStories = withStories,
+ AccountsWithNewPosts = [.. visible.Select(v => v.Account.Id).Distinct()],
+ };
+ }
+
+ private async Task ProfileAsync(SimAccount account, ISessionContext session, CancellationToken ct)
+ {
+ var permit = await AskAsync(ActionKind.ProfileOpen, account.Id, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ return Denied(0, 0);
+ }
+
+ if (permit.Throttled)
+ {
+ return Signal(1, 0);
+ }
+
+ account.LastProfileOpen = _clock.Now;
+ await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
+ var bursts = _random.CountBetween(1, 3);
+ for (var b = 0; b < bursts; b++)
+ {
+ await WaitAsync(session, 0.4, 4, 1.1, ct).ConfigureAwait(false);
+ }
+
+ var now = _clock.Now;
+ var firstPage = account.Posts.Where(p => p.PublishedAt <= now).OrderByDescending(p => p.PublishedAt).Take(PostsPerPage);
+ var fresh = firstPage.Where(p => p.DiscoveredAt is null).ToList();
+ await StorePostsAsync(account, fresh, now, history: false, ct).ConfigureAwait(false);
+ return new RecipeOutcome(RecipeStatus.Completed, 1, fresh.Count);
+ }
+
+ private async Task StoriesAsync(SimAccount account, ISessionContext session, CancellationToken ct)
+ {
+ var counted = 0;
+ var now = _clock.Now;
+ if (!account.Followed && (account.LastProfileOpen is not { } opened || now - opened > TimeSpan.FromMinutes(2)))
+ {
+ // A profile that is not followed shows its stories only from its page.
+ var permit = await AskAsync(ActionKind.ProfileOpen, account.Id, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ return Denied(0, 0);
+ }
+
+ counted++;
+ if (permit.Throttled)
+ {
+ return Signal(counted, 0);
+ }
+
+ account.LastProfileOpen = _clock.Now;
+ await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
+ }
+
+ now = _clock.Now;
+ var active = account.Stories.Where(s => s.PublishedAt <= now && s.ExpiresAt > now && s.SeenAt is null).ToList();
+ var seen = 0;
+ foreach (var story in active)
+ {
+ var permit = await AskAsync(ActionKind.StoryView, account.Id, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ return Denied(counted, seen);
+ }
+
+ counted++;
+ if (permit.Throttled)
+ {
+ return Signal(counted, seen);
+ }
+
+ if (story.IsVideo)
+ {
+ var seconds = Math.Min(15, story.Duration.TotalSeconds * (0.4 + (0.6 * _random.NextDouble())));
+ await _clock.Delay(TimeSpan.FromSeconds(seconds * session.Mood * Pace), ct).ConfigureAwait(false);
+ }
+ else
+ {
+ await WaitAsync(session, 1.8, 5, null, ct).ConfigureAwait(false);
+ }
+
+ var at = _clock.Now;
+ story.SeenAt = at;
+ Stats.StoryViews.Add((story.PublishedAt, at));
+ await StoreStoryAsync(account, story, at, ct).ConfigureAwait(false);
+ seen++;
+ }
+
+ await WaitAsync(session, 1, 4, null, ct).ConfigureAwait(false);
+ var day = LocalCalendar.Today(_clock.Now, _clock.LocalZone);
+ Stats.StoryChecks[(account.Id, day)] = Stats.StoryChecks.GetValueOrDefault((account.Id, day)) + 1;
+ return new RecipeOutcome(RecipeStatus.Completed, counted, seen);
+ }
+
+ private async Task BackfillAsync(SimAccount account, int maxPages, ISessionContext session, CancellationToken ct)
+ {
+ var pages = 0;
+ var stored = 0;
+ while (pages < maxPages && _clock.Now < session.PlannedEnd)
+ {
+ if (account.HistoryCursor >= account.History.Count)
+ {
+ break;
+ }
+
+ var permit = await AskAsync(ActionKind.BackfillPage, account.Id, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ return pages > 0 ? new RecipeOutcome(RecipeStatus.Completed, pages, stored) : Denied(0, 0);
+ }
+
+ pages++;
+ if (permit.Throttled)
+ {
+ return Signal(pages, stored);
+ }
+
+ await WaitAsync(session, 2, 8, 3.5, ct).ConfigureAwait(false);
+ var page = account.History.Skip(account.HistoryCursor).Take(PostsPerPage).ToList();
+ account.HistoryCursor += page.Count;
+ await StorePostsAsync(account, page, _clock.Now, history: true, ct).ConfigureAwait(false);
+ stored += page.Count;
+ Stats.BackfillPostsStored += page.Count;
+ }
+
+ var finished = account.HistoryCursor >= account.History.Count;
+ if (finished && account.Id == Stats.BackfillAccountId && Stats.BackfillFinishedAt is null)
+ {
+ Stats.BackfillFinishedAt = _clock.Now;
+ }
+
+ return new RecipeOutcome(RecipeStatus.Completed, pages, stored) { BackfillFinished = finished };
+ }
+
+ private async Task SimpleAsync(ActionKind kind, long? accountId, ISessionContext session, CancellationToken ct)
+ {
+ var permit = await AskAsync(kind, accountId, ct).ConfigureAwait(false);
+ if (!permit.Granted)
+ {
+ return Denied(0, 0);
+ }
+
+ if (permit.Throttled)
+ {
+ return Signal(1, 0);
+ }
+
+ await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
+ return new RecipeOutcome(RecipeStatus.Completed, 1, 0);
+ }
+
+ /// Asks the Governor; a granted action may meet a simulated throttle signal, reported to the breaker.
+ private async Task<(bool Granted, bool Throttled)> AskAsync(ActionKind kind, long? accountId, CancellationToken ct)
+ {
+ var permit = await _governor.RequestAsync(kind, accountId, ct).ConfigureAwait(false);
+ if (permit.Granted && _random.Chance(_options.ThrottleProbabilityPerAction))
+ {
+ Stats.ThrottlesReported++;
+ _breaker.Report(new Signal(SignalLevel.Throttle, "http-429", "sito-simulato/" + kind, _clock.Now));
+ return (true, true);
+ }
+
+ return (permit.Granted, false);
+ }
+
+ private Task WaitAsync(ISessionContext session, double min, double max, double? median, CancellationToken ct) =>
+ _clock.Delay(TimeSpan.FromSeconds(_random.Between(min, max, median) * session.Mood * Pace), ct);
+
+ private static RecipeOutcome Denied(int counted, int found) => new(RecipeStatus.Denied, counted, found);
+
+ private static RecipeOutcome Signal(int counted, int found) => new(RecipeStatus.StoppedBySignal, counted, found, "Rallentamento simulato");
+
+ private async Task StorePostsAsync(SimAccount account, IReadOnlyList posts, DateTimeOffset now, bool history, CancellationToken ct)
+ {
+ if (posts.Count == 0)
+ {
+ return;
+ }
+
+ foreach (var post in posts)
+ {
+ post.DiscoveredAt = now;
+ if (!history)
+ {
+ Stats.PostDiscoveries.Add((post.PublishedAt, now, account.Followed));
+ }
+ }
+
+ var remaining = await _data.RemainingTodayAsync(ct).ConfigureAwait(false);
+ var batch = new List(posts.Count);
+ var sizes = new List(posts.Count);
+ foreach (var post in posts)
+ {
+ var bytes = new long[post.Files];
+ for (var f = 0; f < post.Files; f++)
+ {
+ var video = post.HasVideo && f == 0;
+ bytes[f] = (long)((video ? _random.Between(2, 25) : _random.Between(0.3, 1.6)) * MB);
+ }
+
+ sizes.Add(bytes);
+ var fits = bytes.Sum() <= remaining;
+ if (fits)
+ {
+ remaining -= bytes.Sum();
+ }
+
+ var media = bytes.Select((b, f) => File(post.Id, f + 1, post.HasVideo && f == 0, b, fits)).ToList();
+ batch.Add(new NewEntry(
+ new Entry
+ {
+ AccountId = account.Id,
+ Kind = EntryKind.Post,
+ InstagramId = post.Id,
+ Code = "C" + post.Id,
+ PublishedAt = post.PublishedAt,
+ DiscoveredAt = now,
+ },
+ media));
+ }
+
+ var results = await _storage.Entries.AddManyAsync(batch, ct).ConfigureAwait(false);
+ await RecordAsync(account, results, ct).ConfigureAwait(false);
+ }
+
+ private async Task StoreStoryAsync(SimAccount account, SimStory story, DateTimeOffset now, CancellationToken ct)
+ {
+ var bytes = (long)((story.IsVideo ? _random.Between(1, 8) : _random.Between(0.2, 0.9)) * MB);
+ var fits = bytes <= await _data.RemainingTodayAsync(ct).ConfigureAwait(false);
+ var result = await _storage.Entries.AddAsync(
+ new Entry
+ {
+ AccountId = account.Id,
+ Kind = EntryKind.Story,
+ InstagramId = story.Id,
+ PublishedAt = story.PublishedAt,
+ ExpiresAt = story.ExpiresAt,
+ DiscoveredAt = now,
+ },
+ [File(story.Id, 1, story.IsVideo, bytes, fits)],
+ ct).ConfigureAwait(false);
+ await RecordAsync(account, [result], ct).ConfigureAwait(false);
+ }
+
+ private Media File(string id, int position, bool video, long bytes, bool downloaded)
+ {
+ var media = new Media
+ {
+ Position = position,
+ Kind = video ? MediaKind.Video : MediaKind.Photo,
+ Bytes = bytes,
+ State = downloaded ? MediaState.Downloaded : MediaState.ToDownload,
+ };
+ return downloaded
+ ? media with
+ {
+ RelativePath = $"sim/{id}_{position}{(video ? ".mp4" : ".jpg")}",
+ Sha256 = (++_fileCounter).ToString("x64", CultureInfo.InvariantCulture),
+ DownloadedAt = _clock.Now,
+ }
+ : media;
+ }
+
+ private async Task RecordAsync(SimAccount account, IReadOnlyList results, CancellationToken ct)
+ {
+ long downloaded = 0;
+ foreach (var result in results.Where(r => r.Created))
+ {
+ foreach (var media in result.Stored.Media)
+ {
+ if (media.State == MediaState.Downloaded)
+ {
+ downloaded += media.Bytes ?? 0;
+ }
+ else
+ {
+ _pending.Add(new PendingFile(media.Id, account.Id, media.Bytes ?? 0, result.Stored.Entry.Kind == EntryKind.Story, media.Kind == MediaKind.Video));
+ }
+ }
+ }
+
+ await _data.RecordAsync(downloaded, account.Id, ct).ConfigureAwait(false);
+ }
+
+ /// The download queue: files left waiting by the data budget go as soon as there is room (stories first).
+ private async Task DownloadPendingAsync(CancellationToken ct)
+ {
+ if (_pending.Count == 0)
+ {
+ return;
+ }
+
+ var remaining = await _data.RemainingTodayAsync(ct).ConfigureAwait(false);
+ foreach (var file in _pending.OrderByDescending(p => p.IsStory).ToList())
+ {
+ if (file.Bytes > remaining)
+ {
+ continue;
+ }
+
+ var sha = (++_fileCounter).ToString("x64", CultureInfo.InvariantCulture);
+ await _storage.Media.MarkStoredAsync(
+ file.MediaId,
+ new StoredFile($"sim/attesa-{file.MediaId}{(file.IsVideo ? ".mp4" : ".jpg")}", file.Bytes, sha),
+ MediaState.Downloaded,
+ _clock.Now,
+ ct).ConfigureAwait(false);
+ await _data.RecordAsync(file.Bytes, file.AccountId, ct).ConfigureAwait(false);
+ remaining -= file.Bytes;
+ _pending.Remove(file);
+ }
+ }
+
+ private sealed record PendingFile(long MediaId, long AccountId, long Bytes, bool IsStory, bool IsVideo);
+}
+
+/// An account of the simulated world.
+public sealed class SimAccount(long id, string username, bool followed, int index, double postRate, bool postsStories)
+{
+ public long Id { get; } = id;
+
+ public string Username { get; } = username;
+
+ public bool Followed { get; } = followed;
+
+ public int Index { get; } = index;
+
+ /// Average new posts per day.
+ public double PostRate { get; } = postRate;
+
+ public bool PostsStories { get; } = postsStories;
+
+ internal List Posts { get; } = [];
+
+ /// Posts before the start, newest first.
+ internal List History { get; } = [];
+
+ internal int HistoryCursor { get; set; }
+
+ internal List Stories { get; } = [];
+
+ internal DateTimeOffset? LastProfileOpen { get; set; }
+}
+
+internal sealed class SimPost(string id, DateTimeOffset publishedAt, int files, bool hasVideo)
+{
+ public string Id { get; } = id;
+
+ public DateTimeOffset PublishedAt { get; } = publishedAt;
+
+ public int Files { get; } = Math.Max(1, files);
+
+ public bool HasVideo { get; } = hasVideo;
+
+ public DateTimeOffset? DiscoveredAt { get; set; }
+}
+
+internal sealed class SimStory(string id, DateTimeOffset publishedAt, DateTimeOffset expiresAt, bool isVideo, TimeSpan duration)
+{
+ public string Id { get; } = id;
+
+ public DateTimeOffset PublishedAt { get; } = publishedAt;
+
+ public DateTimeOffset ExpiresAt { get; } = expiresAt;
+
+ public bool IsVideo { get; } = isVideo;
+
+ public TimeSpan Duration { get; } = duration;
+
+ public DateTimeOffset? SeenAt { get; set; }
+}
diff --git a/src/Febe.Core/Simulation/SimulationReport.cs b/src/Febe.Core/Simulation/SimulationReport.cs
new file mode 100644
index 0000000..2a40430
--- /dev/null
+++ b/src/Febe.Core/Simulation/SimulationReport.cs
@@ -0,0 +1,487 @@
+using System.Globalization;
+using System.Text;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Storage;
+
+namespace Febe.Core.Simulation;
+
+/// Numbers of one simulated day.
+public sealed record SimulatedDay(
+ DateOnly Day,
+ int Sessions,
+ double ActiveMinutes,
+ IReadOnlyDictionary Actions,
+ IReadOnlyDictionary WorstHour,
+ int Throttles,
+ int Overruns);
+
+/// Numbers of one budget category over the whole simulation.
+public sealed record SimulatedCategory(ActionKind Kind, double MeanPerDay, long MaxPerDay, long WorstHour, long? HourlyLimit, long DailyLimit);
+
+/// Mean and maximum of a delay, with how many cases.
+public sealed record DelayStats(int Count, TimeSpan Mean, TimeSpan Max)
+{
+ public static DelayStats From(IEnumerable delays)
+ {
+ var list = delays.ToList();
+ return list.Count == 0
+ ? new DelayStats(0, TimeSpan.Zero, TimeSpan.Zero)
+ : new DelayStats(list.Count, TimeSpan.FromTicks((long)list.Average(d => d.Ticks)), list.Max());
+ }
+}
+
+///
+/// The report of the simulation (spec §14.3): sessions per day; actions per category per day and in the worst hour;
+/// mean and maximum time between publication and discovery; days for the 2,000-post backfill; budget overruns (must be
+/// zero). Overruns, actions outside the window and pause-floor violations are recomputed here from the database,
+/// independently of the Governor.
+///
+public sealed class SimulationReport
+{
+ private static readonly ActionKind[] Categories = Enum.GetValues();
+ private static readonly TimeSpan Hour = TimeSpan.FromMinutes(60);
+
+ public required CautionProfileKind Profile { get; init; }
+
+ public required int Seed { get; init; }
+
+ public required DateTimeOffset Start { get; init; }
+
+ public required DateTimeOffset End { get; init; }
+
+ public required TimeZoneInfo Zone { get; init; }
+
+ public required int Accounts { get; init; }
+
+ public required int FollowedAccounts { get; init; }
+
+ public required IReadOnlyList Days { get; init; }
+
+ public required IReadOnlyList CategoryTotals { get; init; }
+
+ public required int SessionCount { get; init; }
+
+ public required double SessionsPerDayMean { get; init; }
+
+ public required int SessionsPerDayMin { get; init; }
+
+ public required int SessionsPerDayMax { get; init; }
+
+ public required TimeSpan MeanSessionLength { get; init; }
+
+ /// Coefficient of variation of the intervals between session starts (whole run).
+ public required double SessionStartCv { get; init; }
+
+ /// Same, only for intervals inside one day (nights excluded).
+ public required double SessionStartCvWithinDay { get; init; }
+
+ public required TimeSpan ShortestPause { get; init; }
+
+ public required int PauseFloorViolations { get; init; }
+
+ public required int ActionsOutsideWindow { get; init; }
+
+ public required DelayStats FollowedPosts { get; init; }
+
+ public required DelayStats NotFollowedPosts { get; init; }
+
+ public required DelayStats Stories { get; init; }
+
+ public required int PublishedPosts { get; init; }
+
+ public required int UndiscoveredPosts { get; init; }
+
+ public required int PublishedStories { get; init; }
+
+ public required int MissedStories { get; init; }
+
+ public required int BackfillPosts { get; init; }
+
+ public required int BackfillStored { get; init; }
+
+ public DateTimeOffset? BackfillFinishedAt { get; init; }
+
+ public required IReadOnlyList Throttles { get; init; }
+
+ /// Times Febe proposed a more prudent profile (three throttles in seven days).
+ public required int ProposalsOfMorePrudence { get; init; }
+
+ /// Overruns of the budgets in force (gradual start and halving applied): must be zero.
+ public required int Overruns { get; init; }
+
+ /// Overruns of the profile's full budgets: must be zero too.
+ public required int OverrunsOfFullBudgets { get; init; }
+
+ public required IReadOnlyList OverrunDetails { get; init; }
+
+ public required long VirtualEvents { get; init; }
+
+ /// What the fake world saw (for tests and closer looks).
+ public required WorldStats World { get; init; }
+
+ /// The accounts of the fake world.
+ public required IReadOnlyList WorldAccounts { get; init; }
+
+ public required TimeSpan RealDuration { get; init; }
+
+ public double? BackfillDays => BackfillFinishedAt is { } done ? (done - Start).TotalDays : null;
+
+ internal static async Task BuildAsync(
+ IFebeStorage storage,
+ SimulatedWorld world,
+ EngineServices services,
+ SimulationOptions options,
+ DateTimeOffset start,
+ DateTimeOffset end,
+ long virtualEvents,
+ TimeSpan realDuration,
+ CancellationToken ct)
+ {
+ var zone = services.Clock.LocalZone;
+ var profile = services.Runtime.Profile;
+ var sessions = (await storage.Sessions.ListAsync(start, end + TimeSpan.FromDays(1), ct).ConfigureAwait(false))
+ .Where(s => s.StartedAt < end)
+ .ToList();
+ var actions = await storage.ActionLog.ListAsync(start, end + TimeSpan.FromDays(1), ct).ConfigureAwait(false);
+ var incidents = await storage.Incidents.ListAsync(start, end + TimeSpan.FromDays(1), ct).ConfigureAwait(false);
+ var throttles = incidents.Where(i => i.Level == SignalLevel.Throttle).ToList();
+ var seedText = await storage.Settings.GetAsync(EngineSettingKeys.WindowSeed, ct).ConfigureAwait(false);
+ var seed = ulong.TryParse(seedText, NumberStyles.Integer, CultureInfo.InvariantCulture, out var s) ? s : 0;
+ var rampStart = services.Runtime.RampStart;
+
+ // Halving applies after the throttle: the action that met the signal was granted before it.
+ DateTimeOffset? HalvedUntil(DateTimeOffset t) => throttles
+ .Where(i => i.At < t && i.StoppedUntil is not null)
+ .Select(i => (DateTimeOffset?)(i.StoppedUntil!.Value + CircuitBreaker.HalvedPeriod))
+ .Where(u => u > t)
+ .DefaultIfEmpty(null)
+ .Max();
+
+ // Overruns, recomputed from action_log: at every action the rolling hour and the local day so far.
+ var overruns = 0;
+ var overrunsFull = 0;
+ var details = new List();
+ var overrunsByDay = new Dictionary();
+ var worstHourByDay = new Dictionary<(DateOnly, ActionKind), long>();
+ var worstHour = new Dictionary();
+ foreach (var kind in Categories)
+ {
+ var list = actions.Where(a => a.Category == kind).OrderBy(a => a.At).ThenBy(a => a.Id).ToList();
+ var windowStart = 0;
+ long windowSum = 0;
+ long daySum = 0;
+ DateOnly? currentDay = null;
+ for (var i = 0; i < list.Count; i++)
+ {
+ var action = list[i];
+ windowSum += action.Amount;
+ while (list[windowStart].At <= action.At - Hour)
+ {
+ windowSum -= list[windowStart].Amount;
+ windowStart++;
+ }
+
+ var day = LocalCalendar.Today(action.At, zone);
+ if (day != currentDay)
+ {
+ currentDay = day;
+ daySum = 0;
+ }
+
+ daySum += action.Amount;
+ worstHour[kind] = Math.Max(worstHour.GetValueOrDefault(kind), windowSum);
+ worstHourByDay[(day, kind)] = Math.Max(worstHourByDay.GetValueOrDefault((day, kind)), windowSum);
+
+ var limits = BudgetLimits.Compute(profile, rampStart, HalvedUntil(action.At), action.At);
+ var over = kind == ActionKind.DataDownload
+ ? daySum > limits.DataPerDayBytes
+ : windowSum > limits.Budgets[kind].PerHour || daySum > limits.Budgets[kind].PerDay;
+ var overFull = kind == ActionKind.DataDownload
+ ? daySum > profile.DataPerDayBytes
+ : windowSum > profile.Budgets[kind].PerHour || daySum > profile.Budgets[kind].PerDay;
+ if (over)
+ {
+ overruns++;
+ overrunsByDay[day] = overrunsByDay.GetValueOrDefault(day) + 1;
+ if (details.Count < 20)
+ {
+ details.Add(string.Create(
+ CultureInfo.InvariantCulture,
+ $"{ItalianText.Category(kind)} {LocalCalendar.ToLocal(action.At, zone):yyyy-MM-dd HH:mm:ss}: ora {windowSum}, giorno {daySum}"));
+ }
+ }
+
+ if (overFull)
+ {
+ overrunsFull++;
+ }
+ }
+ }
+
+ // Actions outside the active window (recomputed with the persisted seed of the daily shifts).
+ var outside = 0;
+ var windows = new Dictionary();
+ ActiveWindow? WindowOf(DateOnly day)
+ {
+ if (!windows.TryGetValue(day, out var w))
+ {
+ w = profile.ActiveDays.Contains(day.DayOfWeek) ? DayPlanner.Compute(day, profile, seed, zone) : null;
+ windows[day] = w;
+ }
+
+ return w;
+ }
+
+ foreach (var action in actions.Where(a => a.Category != ActionKind.DataDownload))
+ {
+ var today = LocalCalendar.Today(action.At, zone);
+ var inside = (WindowOf(today)?.Contains(action.At) ?? false) || (WindowOf(today.AddDays(-1))?.Contains(action.At) ?? false);
+ if (!inside)
+ {
+ outside++;
+ }
+ }
+
+ // Pauses and irregularity of the session starts.
+ var ordered = sessions.OrderBy(x => x.StartedAt).ToList();
+ var shortest = TimeSpan.MaxValue;
+ var floorViolations = 0;
+ for (var i = 1; i < ordered.Count; i++)
+ {
+ if (ordered[i - 1].EndedAt is { } previousEnd)
+ {
+ var pause = ordered[i].StartedAt - previousEnd;
+ shortest = pause < shortest ? pause : shortest;
+ if (pause < profile.PauseMin)
+ {
+ floorViolations++;
+ }
+ }
+ }
+
+ var intervals = new List();
+ var withinDay = new List();
+ for (var i = 1; i < ordered.Count; i++)
+ {
+ var gap = (ordered[i].StartedAt - ordered[i - 1].StartedAt).TotalMinutes;
+ intervals.Add(gap);
+ if (LocalCalendar.Today(ordered[i].StartedAt, zone) == LocalCalendar.Today(ordered[i - 1].StartedAt, zone) && gap < 6 * 60)
+ {
+ withinDay.Add(gap);
+ }
+ }
+
+ // Days.
+ var firstDay = LocalCalendar.Today(start, zone);
+ var lastDay = LocalCalendar.Today(end - TimeSpan.FromTicks(1), zone);
+ var days = new List();
+ for (var day = firstDay; day <= lastDay; day = day.AddDays(1))
+ {
+ var (dayStart, dayEnd) = LocalCalendar.DayBounds(day, zone);
+ var daySessions = ordered.Where(x => x.StartedAt >= dayStart && x.StartedAt < dayEnd).ToList();
+ var active = daySessions.Sum(x => ((x.EndedAt ?? x.StartedAt) - x.StartedAt).TotalMinutes);
+ var counts = Categories.ToDictionary(k => k, k => actions.Where(a => a.Category == k && a.At >= dayStart && a.At < dayEnd).Sum(a => a.Amount));
+ var worst = Categories.ToDictionary(k => k, k => worstHourByDay.GetValueOrDefault((day, k)));
+ days.Add(new SimulatedDay(
+ day,
+ daySessions.Count,
+ active,
+ counts,
+ worst,
+ throttles.Count(t => t.At >= dayStart && t.At < dayEnd),
+ overrunsByDay.GetValueOrDefault(day)));
+ }
+
+ var categories = Categories.Select(k => new SimulatedCategory(
+ k,
+ days.Count == 0 ? 0 : days.Average(d => (double)d.Actions[k]),
+ days.Count == 0 ? 0 : days.Max(d => d.Actions[k]),
+ worstHour.GetValueOrDefault(k),
+ k == ActionKind.DataDownload ? null : profile.Budgets[k].PerHour,
+ k == ActionKind.DataDownload ? profile.DataPerDayBytes : profile.Budgets[k].PerDay)).ToList();
+
+ var stats = world.Stats;
+ return new SimulationReport
+ {
+ Profile = profile.Kind,
+ Seed = options.Seed,
+ Start = start,
+ End = end,
+ Zone = zone,
+ Accounts = world.Accounts.Count,
+ FollowedAccounts = world.Accounts.Count(a => a.Followed),
+ Days = days,
+ CategoryTotals = categories,
+ SessionCount = ordered.Count,
+ SessionsPerDayMean = days.Count == 0 ? 0 : days.Average(d => d.Sessions),
+ SessionsPerDayMin = days.Count == 0 ? 0 : days.Min(d => d.Sessions),
+ SessionsPerDayMax = days.Count == 0 ? 0 : days.Max(d => d.Sessions),
+ MeanSessionLength = ordered.Count == 0 ? TimeSpan.Zero : TimeSpan.FromTicks((long)ordered.Average(x => ((x.EndedAt ?? x.StartedAt) - x.StartedAt).Ticks)),
+ SessionStartCv = Cv(intervals),
+ SessionStartCvWithinDay = Cv(withinDay),
+ ShortestPause = shortest == TimeSpan.MaxValue ? TimeSpan.Zero : shortest,
+ PauseFloorViolations = floorViolations,
+ ActionsOutsideWindow = outside,
+ FollowedPosts = DelayStats.From(stats.PostDiscoveries.Where(p => p.Followed).Select(p => p.Discovered - p.Published)),
+ NotFollowedPosts = DelayStats.From(stats.PostDiscoveries.Where(p => !p.Followed).Select(p => p.Discovered - p.Published)),
+ Stories = DelayStats.From(stats.StoryViews.Select(v => v.Seen - v.Published)),
+ PublishedPosts = world.PublishedPosts(start, end),
+ UndiscoveredPosts = world.UndiscoveredPosts(start, end),
+ PublishedStories = world.PublishedStories(start, end),
+ MissedStories = world.MissedStories(start, end),
+ BackfillPosts = (options.World ?? new SimulatedWorldOptions()).HistoricalPosts,
+ BackfillStored = stats.BackfillPostsStored,
+ BackfillFinishedAt = stats.BackfillFinishedAt,
+ Throttles = throttles,
+ ProposalsOfMorePrudence = throttles.Count(t => throttles.Count(o => o.At <= t.At && o.At > t.At - CircuitBreaker.ProposalWindow) >= CircuitBreaker.ProposalThreshold),
+ Overruns = overruns,
+ OverrunsOfFullBudgets = overrunsFull,
+ OverrunDetails = details,
+ VirtualEvents = virtualEvents,
+ World = stats,
+ WorldAccounts = world.Accounts,
+ RealDuration = realDuration,
+ };
+ }
+
+ /// Italian text report.
+ public string ToText()
+ {
+ var b = new StringBuilder();
+ var firstDay = LocalCalendar.Today(Start, Zone);
+ var lastDay = LocalCalendar.Today(End - TimeSpan.FromTicks(1), Zone);
+ b.AppendLine($"Simulazione del motore: {ItalianText.Count(Days.Count, "giorno", "giorni")} con il profilo «{ItalianText.Profile(Profile)}» (seme {Seed.ToString(CultureInfo.InvariantCulture)})");
+ b.AppendLine($"Periodo: dal {ItalianText.Day(firstDay)} alle {ItalianText.Clock(Start, Zone)} al {ItalianText.Day(lastDay)}, fuso {Zone.Id}");
+ b.AppendLine($"Mondo finto: {ItalianText.Number(Accounts)} account ({ItalianText.Number(FollowedAccounts)} seguiti, {ItalianText.Number(Accounts - FollowedAccounts)} no), {ItalianText.Number(PublishedPosts)} post e {ItalianText.Number(PublishedStories)} storie pubblicati nel periodo, uno storico di {ItalianText.Number(BackfillPosts)} post");
+ b.AppendLine("I tetti del profilo sono stime prudenti, non limiti ufficiali di Instagram.");
+ b.AppendLine();
+
+ b.AppendLine("Sessioni");
+ b.AppendLine($" al giorno: media {ItalianText.Decimal(SessionsPerDayMean, 1)}, minimo {ItalianText.Number(SessionsPerDayMin)}, massimo {ItalianText.Number(SessionsPerDayMax)} (in tutto {ItalianText.Number(SessionCount)})");
+ b.AppendLine($" durata media: {ItalianText.Duration(MeanSessionLength)}; pausa più breve: {ItalianText.Duration(ShortestPause)}");
+ b.AppendLine($" irregolarità degli inizi (coefficiente di variazione): {ItalianText.Decimal(SessionStartCv, 2)} in tutto, {ItalianText.Decimal(SessionStartCvWithinDay, 2)} dentro la giornata");
+ b.AppendLine();
+
+ b.AppendLine("Azioni per categoria: media al giorno, giorno peggiore, ora peggiore (tetto all'ora / al giorno)");
+ foreach (var c in CategoryTotals)
+ {
+ if (c.Kind == ActionKind.DataDownload)
+ {
+ b.AppendLine($" {ItalianText.CategoryLabel(c.Kind)}: {ItalianText.Bytes((long)c.MeanPerDay)} al giorno, giorno peggiore {ItalianText.Bytes(c.MaxPerDay)} (tetto {ItalianText.Bytes(c.DailyLimit)} al giorno)");
+ }
+ else
+ {
+ b.AppendLine($" {ItalianText.CategoryLabel(c.Kind)}: {ItalianText.Decimal(c.MeanPerDay, 1)} al giorno, giorno peggiore {ItalianText.Number(c.MaxPerDay)}, ora peggiore {ItalianText.Number(c.WorstHour)} (tetto {ItalianText.Number(c.HourlyLimit ?? 0)} / {ItalianText.Number(c.DailyLimit)})");
+ }
+ }
+
+ b.AppendLine();
+ b.AppendLine("Dalla pubblicazione alla scoperta");
+ b.AppendLine($" post degli account seguiti: {Delay(FollowedPosts)}");
+ b.AppendLine($" post degli account non seguiti: {Delay(NotFollowedPosts)}");
+ b.AppendLine($" storie: {Delay(Stories)}");
+ b.AppendLine($" post non ancora scoperti alla fine: {ItalianText.Number(UndiscoveredPosts)} di {ItalianText.Number(PublishedPosts)}; storie scadute senza essere viste: {ItalianText.Number(MissedStories)} di {ItalianText.Number(PublishedStories)}");
+ b.AppendLine();
+
+ b.AppendLine($"Storico di {ItalianText.Number(BackfillPosts)} post");
+ b.AppendLine(BackfillFinishedAt is { } done
+ ? $" completato in {ItalianText.Decimal(BackfillDays ?? 0, 1)} giorni ({ItalianText.DayWithWeekday(LocalCalendar.Today(done, Zone))} {ItalianText.At(done, Zone)})"
+ : $" non completato: {ItalianText.Number(BackfillStored)} post scaricati in {ItalianText.Count(Days.Count, "giorno", "giorni")}");
+ b.AppendLine();
+
+ b.AppendLine("Rallentamenti simulati");
+ if (Throttles.Count == 0)
+ {
+ b.AppendLine(" nessuno");
+ }
+
+ foreach (var t in Throttles)
+ {
+ var stop = t.StoppedUntil is { } until ? ItalianText.Duration(until - t.At) : "?";
+ b.AppendLine($" {ItalianText.DayWithWeekday(LocalCalendar.Today(t.At, Zone))} {ItalianText.At(t.At, Zone)}: fermo di {stop}");
+ }
+
+ if (ProposalsOfMorePrudence > 0)
+ {
+ b.AppendLine($" proposte di passare a un profilo più prudente (tre rallentamenti in sette giorni): {ItalianText.Number(ProposalsOfMorePrudence)}");
+ }
+
+ b.AppendLine();
+ b.AppendLine("Controlli");
+ b.AppendLine($" superamenti dei tetti: {ItalianText.Number(Overruns)} (dei tetti pieni del profilo: {ItalianText.Number(OverrunsOfFullBudgets)})");
+ foreach (var detail in OverrunDetails)
+ {
+ b.AppendLine(" " + detail);
+ }
+
+ b.AppendLine($" azioni fuori dalla fascia oraria: {ItalianText.Number(ActionsOutsideWindow)}");
+ b.AppendLine($" pause più brevi della pausa minima: {ItalianText.Number(PauseFloorViolations)}");
+ b.AppendLine();
+ b.AppendLine($"Simulati {ItalianText.Number(VirtualEvents)} eventi in {ItalianText.Decimal(RealDuration.TotalSeconds, 1)} secondi.");
+ return b.ToString();
+ }
+
+ /// One row per day, ';' separated, for Excel in Italian (write it as UTF-8 with BOM).
+ public string ToCsv()
+ {
+ var b = new StringBuilder();
+ var headers = new List { "giorno", "sessioni", "minuti di attività" };
+ headers.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => ItalianText.Category(k)));
+ headers.Add("dati scaricati (MB)");
+ headers.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => "ora peggiore, " + ItalianText.Category(k)));
+ headers.Add("rallentamenti");
+ headers.Add("superamenti");
+ b.AppendLine(string.Join(';', headers.Select(Quote)));
+ foreach (var day in Days)
+ {
+ var cells = new List
+ {
+ day.Day.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture),
+ day.Sessions.ToString(CultureInfo.InvariantCulture),
+ ItalianText.Decimal(day.ActiveMinutes, 1, keepZeros: true).Replace(".", string.Empty, StringComparison.Ordinal),
+ };
+ cells.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => day.Actions[k].ToString(CultureInfo.InvariantCulture)));
+ cells.Add(ItalianText.Decimal(day.Actions[ActionKind.DataDownload] / (1024.0 * 1024.0), 1, keepZeros: true).Replace(".", string.Empty, StringComparison.Ordinal));
+ cells.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => day.WorstHour[k].ToString(CultureInfo.InvariantCulture)));
+ cells.Add(day.Throttles.ToString(CultureInfo.InvariantCulture));
+ cells.Add(day.Overruns.ToString(CultureInfo.InvariantCulture));
+ b.AppendLine(string.Join(';', cells));
+ }
+
+ return b.ToString();
+ }
+
+ /// Writes as UTF-8 with BOM.
+ public async Task WriteCsvAsync(string path, CancellationToken ct = default)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(path);
+ await File.WriteAllTextAsync(path, ToCsv(), new UTF8Encoding(encoderShouldEmitUTF8Identifier: true), ct).ConfigureAwait(false);
+ }
+
+ private static string Delay(DelayStats stats) => stats.Count == 0
+ ? "nessun caso"
+ : $"media {ItalianText.Duration(stats.Mean)}, massimo {ItalianText.Duration(stats.Max)} ({ItalianText.Count(stats.Count, "caso", "casi")})";
+
+ private static string Quote(string text) => text.Contains(';', StringComparison.Ordinal) || text.Contains('"', StringComparison.Ordinal)
+ ? "\"" + text.Replace("\"", "\"\"", StringComparison.Ordinal) + "\""
+ : text;
+
+ private static double Cv(IReadOnlyList values)
+ {
+ if (values.Count < 2)
+ {
+ return 0;
+ }
+
+ var mean = values.Average();
+ if (mean <= 0)
+ {
+ return 0;
+ }
+
+ var variance = values.Sum(v => (v - mean) * (v - mean)) / (values.Count - 1);
+ return Math.Sqrt(variance) / mean;
+ }
+}
diff --git a/src/Febe.Core/Simulation/SimulationZones.cs b/src/Febe.Core/Simulation/SimulationZones.cs
new file mode 100644
index 0000000..e995396
--- /dev/null
+++ b/src/Febe.Core/Simulation/SimulationZones.cs
@@ -0,0 +1,30 @@
+namespace Febe.Core.Simulation;
+
+/// Alberto's time zone for the simulation, also where the system has no time zone data.
+public static class SimulationZones
+{
+ /// Europe/Rome, or an equivalent custom zone (CET/CEST, last Sunday of March and October).
+ public static TimeZoneInfo Rome { get; } = LoadRome();
+
+ private static TimeZoneInfo LoadRome()
+ {
+ foreach (var id in new[] { "Europe/Rome", "W. Europe Standard Time" })
+ {
+ try
+ {
+ return TimeZoneInfo.FindSystemTimeZoneById(id);
+ }
+ catch (TimeZoneNotFoundException)
+ {
+ }
+ catch (InvalidTimeZoneException)
+ {
+ }
+ }
+
+ var start = TimeZoneInfo.TransitionTime.CreateFloatingDateRule(new DateTime(1, 1, 1, 2, 0, 0), 3, 5, DayOfWeek.Sunday);
+ var end = TimeZoneInfo.TransitionTime.CreateFloatingDateRule(new DateTime(1, 1, 1, 3, 0, 0), 10, 5, DayOfWeek.Sunday);
+ var rule = TimeZoneInfo.AdjustmentRule.CreateAdjustmentRule(DateTime.MinValue.Date, DateTime.MaxValue.Date, TimeSpan.FromHours(1), start, end);
+ return TimeZoneInfo.CreateCustomTimeZone("Europe/Rome", TimeSpan.FromHours(1), "Europe/Rome", "CET", "CEST", [rule]);
+ }
+}
diff --git a/src/Febe.Core/Simulation/VirtualClock.cs b/src/Febe.Core/Simulation/VirtualClock.cs
new file mode 100644
index 0000000..4696211
--- /dev/null
+++ b/src/Febe.Core/Simulation/VirtualClock.cs
@@ -0,0 +1,274 @@
+using System.Diagnostics;
+using Febe.Core.Abstractions;
+
+namespace Febe.Core.Simulation;
+
+///
+/// Event-driven virtual clock for the simulation and the engine tests (spec §14.1, §14.3). A
+/// registers a timer that completes only when virtual time reaches it; waits until every
+/// actor (by default one: the engine loop) is waiting on a timer, then moves time to the earliest timer and fires it.
+/// Thirty simulated days take seconds, and the outcome depends only on the seeds.
+///
+///
+/// Delays are rounded up to whole milliseconds, the resolution of the database, so stored and computed times compare exactly.
+/// With a delay moves time forward at once: handy for one component under test, without a driver.
+/// Each actor must wait on at most one delay at a time, otherwise the driver could advance before the second is registered.
+///
+public sealed class VirtualClock : IClock
+{
+ private static readonly long TicksPerMillisecond = TimeSpan.TicksPerMillisecond;
+
+ private readonly Lock _gate = new();
+ private readonly PriorityQueue _timers = new();
+ private readonly SemaphoreSlim _registered = new(0);
+ private DateTimeOffset _now;
+ private long _sequence;
+ private int _active;
+
+ public VirtualClock(DateTimeOffset start, TimeZoneInfo? zone = null)
+ {
+ _now = new DateTimeOffset(start.UtcTicks - (start.UtcTicks % TicksPerMillisecond), TimeSpan.Zero);
+ LocalZone = zone ?? TimeZoneInfo.Utc;
+ }
+
+ public DateTimeOffset Now
+ {
+ get
+ {
+ lock (_gate)
+ {
+ return _now;
+ }
+ }
+ }
+
+ public TimeZoneInfo LocalZone { get; }
+
+ /// When true, advances time at once (no driver).
+ public bool AutoAdvance { get; set; }
+
+ /// Independent actors that wait on this clock; time advances only when all of them wait.
+ public int Actors { get; set; } = 1;
+
+ /// Real-time limit without any progress before gives up.
+ public TimeSpan StallTimeout { get; set; } = TimeSpan.FromSeconds(60);
+
+ /// Delays registered and not yet completed or cancelled.
+ public int PendingTimers
+ {
+ get
+ {
+ lock (_gate)
+ {
+ return _active;
+ }
+ }
+ }
+
+ /// Delays that completed (a measure of how much the simulation did).
+ public long FiredTimers { get; private set; }
+
+ public Task Delay(TimeSpan time, CancellationToken ct)
+ {
+ if (ct.IsCancellationRequested)
+ {
+ return Task.FromCanceled(ct);
+ }
+
+ var ticks = time.Ticks <= 0 ? 0 : ((time.Ticks + TicksPerMillisecond - 1) / TicksPerMillisecond) * TicksPerMillisecond;
+ if (ticks == 0)
+ {
+ return Task.CompletedTask;
+ }
+
+ lock (_gate)
+ {
+ if (AutoAdvance)
+ {
+ _now = _now.AddTicks(ticks);
+ return Task.CompletedTask;
+ }
+ }
+
+ // Registered before the timer is queued, so the registration is complete before anyone can fire it.
+ var delay = new PendingDelay();
+ if (ct.CanBeCanceled)
+ {
+ delay.Registration = ct.Register(() => Cancel(delay, ct));
+ }
+
+ lock (_gate)
+ {
+ if (delay.Done)
+ {
+ return delay.Completion.Task;
+ }
+
+ delay.Due = _now.AddTicks(ticks);
+ delay.Queued = true;
+ _timers.Enqueue(delay, (delay.Due.UtcTicks, _sequence++));
+ _active++;
+ }
+
+ _registered.Release();
+ return delay.Completion.Task;
+ }
+
+ /// Moves time forward by hand, firing in order the timers that fall due on the way.
+ public void Advance(TimeSpan time) => AdvanceTo(Now + time);
+
+ /// Moves time to , firing in order the timers that fall due on the way.
+ public void AdvanceTo(DateTimeOffset target)
+ {
+ while (TryFireNext(target))
+ {
+ }
+
+ lock (_gate)
+ {
+ if (target > _now)
+ {
+ _now = target;
+ }
+ }
+ }
+
+ ///
+ /// Runs the simulation until : whenever all actors wait on a timer, time jumps to the
+ /// earliest one and fires it. Returns with time at and the actors waiting. If an actor
+ /// fails, its exception is thrown here.
+ ///
+ /// Virtual instant to reach.
+ /// Cancellation.
+ /// The actors' tasks: a finished actor no longer counts, a failed one stops the run.
+ public async Task RunUntilAsync(DateTimeOffset target, CancellationToken ct = default, params Task[] actors)
+ {
+ ArgumentNullException.ThrowIfNull(actors);
+ while (true)
+ {
+ await WaitQuiescentAsync(actors, ct).ConfigureAwait(false);
+ if (actors.FirstOrDefault(a => a.IsFaulted) is { } failed)
+ {
+ await failed.ConfigureAwait(false);
+ }
+
+ if (!TryFireNext(target))
+ {
+ lock (_gate)
+ {
+ if (target > _now)
+ {
+ _now = target;
+ }
+ }
+
+ return;
+ }
+ }
+ }
+
+ private async Task WaitQuiescentAsync(Task[] actors, CancellationToken ct)
+ {
+ var stopwatch = Stopwatch.StartNew();
+ while (true)
+ {
+ ct.ThrowIfCancellationRequested();
+ if (actors.Any(a => a.IsFaulted))
+ {
+ return;
+ }
+
+ var running = Actors - actors.Count(a => a.IsCompleted);
+ if (running <= 0 || PendingTimers >= running)
+ {
+ return;
+ }
+
+ if (await _registered.WaitAsync(TimeSpan.FromMilliseconds(100), ct).ConfigureAwait(false))
+ {
+ stopwatch.Restart();
+ continue;
+ }
+
+ if (stopwatch.Elapsed > StallTimeout)
+ {
+ throw new TimeoutException(
+ $"La simulazione non avanza da {StallTimeout.TotalSeconds:0} secondi: un attore aspetta qualcosa che non è un timer dell'orologio virtuale.");
+ }
+ }
+ }
+
+ private bool TryFireNext(DateTimeOffset limit)
+ {
+ PendingDelay? fired = null;
+ lock (_gate)
+ {
+ while (_timers.TryPeek(out var next, out _))
+ {
+ if (next.Done)
+ {
+ _timers.Dequeue();
+ continue;
+ }
+
+ if (next.Due > limit)
+ {
+ break;
+ }
+
+ _timers.Dequeue();
+ next.Done = true;
+ _active--;
+ if (next.Due > _now)
+ {
+ _now = next.Due;
+ }
+
+ fired = next;
+ FiredTimers++;
+ break;
+ }
+ }
+
+ if (fired is null)
+ {
+ return false;
+ }
+
+ fired.Registration.Dispose();
+ fired.Completion.TrySetResult();
+ return true;
+ }
+
+ private void Cancel(PendingDelay delay, CancellationToken ct)
+ {
+ lock (_gate)
+ {
+ if (delay.Done)
+ {
+ return;
+ }
+
+ delay.Done = true;
+ if (delay.Queued)
+ {
+ _active--;
+ }
+ }
+
+ delay.Completion.TrySetCanceled(ct);
+ }
+
+ private sealed class PendingDelay
+ {
+ public DateTimeOffset Due { get; set; }
+
+ public bool Queued { get; set; }
+
+ public TaskCompletionSource Completion { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+ public CancellationTokenRegistration Registration { get; set; }
+
+ public bool Done { get; set; }
+ }
+}
diff --git a/src/Febe.Server/Program.cs b/src/Febe.Server/Program.cs
index 8bd7dfc..1a60459 100644
--- a/src/Febe.Server/Program.cs
+++ b/src/Febe.Server/Program.cs
@@ -1,2 +1,11 @@
// Composition root for Linux and Docker. Filled in by milestones M3–M5.
+using Febe.Server;
+
+if (SimulateCommand.Matches(args))
+{
+ Console.OutputEncoding = System.Text.Encoding.UTF8;
+ return await SimulateCommand.RunAsync(args, Console.Out, Console.Error);
+}
+
Console.WriteLine("Febe");
+return 0;
diff --git a/src/Febe.Server/SimulateCommand.cs b/src/Febe.Server/SimulateCommand.cs
new file mode 100644
index 0000000..e223768
--- /dev/null
+++ b/src/Febe.Server/SimulateCommand.cs
@@ -0,0 +1,136 @@
+using System.Globalization;
+using Febe.Core.Domain;
+using Febe.Core.Simulation;
+using Febe.Data;
+
+namespace Febe.Server;
+
+///
+/// --simula 30g --profilo prudente [--csv percorso] [--seme n] (spec §14.3): runs the engine under the virtual
+/// clock against the fake world, in a temporary database, and prints the Italian report. Never opens a browser and
+/// never contacts any site. Exit code 0 when no budget was exceeded, 1 otherwise, 2 for wrong arguments.
+///
+internal static class SimulateCommand
+{
+ public const string Flag = "--simula";
+
+ public static bool Matches(string[] args) => args.Any(a => string.Equals(a, Flag, StringComparison.OrdinalIgnoreCase));
+
+ public static async Task RunAsync(string[] args, TextWriter output, TextWriter error, CancellationToken ct = default)
+ {
+ if (!TryParse(args, out var options, out var csv, out var problem))
+ {
+ await error.WriteLineAsync(problem).ConfigureAwait(false);
+ await error.WriteLineAsync("Uso: --simula 30g --profilo prudente|equilibrato|rapido [--csv percorso.csv] [--seme numero]").ConfigureAwait(false);
+ return 2;
+ }
+
+ var folder = Path.Combine(Path.GetTempPath(), "febe-simulazione-" + Guid.NewGuid().ToString("N")[..10]);
+ Directory.CreateDirectory(folder);
+ try
+ {
+ var report = await EngineSimulation.RunAsync(
+ options,
+ async token => await FebeDatabase.OpenAsync(folder, token).ConfigureAwait(false),
+ ct).ConfigureAwait(false);
+ await output.WriteAsync(report.ToText()).ConfigureAwait(false);
+ if (csv is not null)
+ {
+ await report.WriteCsvAsync(csv, ct).ConfigureAwait(false);
+ await output.WriteLineAsync($"Resoconto CSV scritto in {csv}").ConfigureAwait(false);
+ }
+
+ return report.Overruns == 0 && report.OverrunsOfFullBudgets == 0 ? 0 : 1;
+ }
+ finally
+ {
+ try
+ {
+ Directory.Delete(folder, recursive: true);
+ }
+ catch (IOException)
+ {
+ }
+ catch (UnauthorizedAccessException)
+ {
+ }
+ }
+ }
+
+ internal static bool TryParse(string[] args, out SimulationOptions options, out string? csv, out string problem)
+ {
+ options = new SimulationOptions();
+ csv = null;
+ problem = string.Empty;
+ for (var i = 0; i < args.Length; i++)
+ {
+ var arg = args[i];
+ string? Next() => i + 1 < args.Length ? args[++i] : null;
+ switch (arg.ToLowerInvariant())
+ {
+ case Flag:
+ {
+ var value = Next();
+ var digits = value?.TrimEnd('g', 'G');
+ if (!int.TryParse(digits, NumberStyles.Integer, CultureInfo.InvariantCulture, out var days) || days < 1 || days > 366)
+ {
+ problem = $"Durata non valida: «{value}». Scrivi per esempio 30g.";
+ return false;
+ }
+
+ options = options with { Days = days };
+ break;
+ }
+
+ case "--profilo":
+ {
+ var value = Next();
+ CautionProfileKind? kind = value?.ToLowerInvariant() switch
+ {
+ "prudente" => CautionProfileKind.Prudent,
+ "equilibrato" => CautionProfileKind.Balanced,
+ "rapido" => CautionProfileKind.Fast,
+ _ => null,
+ };
+ if (kind is null)
+ {
+ problem = $"Profilo sconosciuto: «{value}». I profili sono prudente, equilibrato, rapido.";
+ return false;
+ }
+
+ options = options with { Profile = kind.Value };
+ break;
+ }
+
+ case "--csv":
+ csv = Next();
+ if (string.IsNullOrWhiteSpace(csv))
+ {
+ problem = "Dopo --csv serve il percorso del file.";
+ return false;
+ }
+
+ break;
+
+ case "--seme":
+ {
+ var value = Next();
+ if (!int.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out var seed))
+ {
+ problem = $"Seme non valido: «{value}».";
+ return false;
+ }
+
+ options = options with { Seed = seed };
+ break;
+ }
+
+ default:
+ problem = $"Argomento sconosciuto: «{arg}».";
+ return false;
+ }
+ }
+
+ return true;
+ }
+}
diff --git a/tests/Febe.Tests/Engine/AccountPlanCalculatorTests.cs b/tests/Febe.Tests/Engine/AccountPlanCalculatorTests.cs
new file mode 100644
index 0000000..b3b158d
--- /dev/null
+++ b/tests/Febe.Tests/Engine/AccountPlanCalculatorTests.cs
@@ -0,0 +1,120 @@
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Tests.Engine.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class AccountPlanCalculatorTests
+{
+ private static Account Make(string name, bool followed, Frequency frequency = Frequency.Normal, AccountState state = AccountState.UpToDate, int? posts = null, long id = 0) =>
+ Account.Create(name, StartingPoint.EverythingAndKeepUpdated, EngineTestBed.Noon, EngineTestBed.Zone) with
+ {
+ Id = id,
+ IsFollowed = followed,
+ Frequency = frequency,
+ State = state,
+ PostCount = posts,
+ };
+
+ [TestMethod]
+ public void AProfileNotFollowedIsCheckedEveryThreeHoursAtNormalFrequency()
+ {
+ var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("studio.lumen.demo", followed: false) with { ContentTypes = ContentTypes.PostPhotos | ContentTypes.PostVideos },
+ Profile = CautionProfile.Prudent with { GradualStart = false },
+ });
+
+ Assert.AreEqual(TimeSpan.FromHours(3), estimate.ProfileCheckWanted);
+ Assert.IsTrue(estimate.ProfileCheckEvery!.Value.TotalHours is > 2.9 and < 3.3);
+ Assert.IsFalse(estimate.OverBudget);
+ Assert.AreEqual(100, estimate.DailyProfileBudget);
+ var posts = estimate.Lines.Single(l => l.Title == "Nuovi post").Text;
+ StringAssert.Contains(posts, "ogni 3 ore circa");
+ StringAssert.Contains(posts, "tra le 7:30 e le 23:30");
+ Assert.AreEqual("spente.", estimate.Lines.Single(l => l.Title == "Storie").Text);
+ Assert.IsEmpty(estimate.Warnings);
+ }
+
+ [TestMethod]
+ public void FollowedProfilesAreDiscoveredByTheSweepAndStoriesGetThreeChecksADay()
+ {
+ var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("marta.demo", followed: true, Frequency.Low),
+ Profile = CautionProfile.Prudent,
+ });
+
+ StringAssert.Contains(estimate.Lines.Single(l => l.Title == "Nuovi post").Text, "giro dei profili che segui");
+ StringAssert.Contains(estimate.Lines.Single(l => l.Title == "Nuovi post").Text, "20–90 minuti");
+ Assert.IsTrue(estimate.StoryInterval <= TimeSpan.FromHours(16) / 3);
+ Assert.IsTrue(estimate.StoryChecksPerDay >= 3);
+ StringAssert.Contains(estimate.Lines.Single(l => l.Title == "Storie").Text, "almeno 3 volte al giorno");
+ Assert.IsTrue(estimate.Warnings.Any(w => w.Contains("avvio graduale", StringComparison.Ordinal)));
+ }
+
+ [TestMethod]
+ public void TheBackfillEstimateUsesThePostCountWhenKnown()
+ {
+ var profile = CautionProfile.Prudent with { GradualStart = false };
+ var known = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("storico.demo", followed: true, state: AccountState.Backfilling, posts: 2000) with { BackfillCompletedAt = null },
+ Profile = profile,
+ ArchivedPosts = 500,
+ });
+ Assert.AreEqual(1500, known.BackfillRemainingPosts);
+ Assert.AreEqual(5, known.BackfillDays, "1.500 posts at 300 a day.");
+ StringAssert.Contains(known.Lines.Single(l => l.Title == "Storico").Text, "mancano 1.500 post, servono circa 5 giorni");
+
+ var unknown = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("nuovo.demo", followed: true, state: AccountState.Backfilling) with { BackfillCompletedAt = null },
+ Profile = profile,
+ });
+ Assert.IsNull(unknown.BackfillDays);
+ StringAssert.Contains(unknown.Lines.Single(l => l.Title == "Storico").Text, "non è ancora noto");
+
+ // Shared with other accounts in backfill, within the daily budget of history pages (100 × 12 posts).
+ var others = Enumerable.Range(1, 7).Select(i => Make($"altro{i}.demo", true, state: AccountState.Backfilling, id: i) with { BackfillCompletedAt = null }).ToList();
+ var shared = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("storico.demo", followed: true, state: AccountState.Backfilling, posts: 2000, id: 100) with { BackfillCompletedAt = null },
+ OtherAccounts = others,
+ Profile = profile,
+ });
+ Assert.AreEqual(14, shared.BackfillDays, "2.000 posts at 150 a day (1.200 shared by 8 accounts).");
+ }
+
+ [TestMethod]
+ public void TooManyAccountsMakeTheChecksSparserWithAWarning()
+ {
+ var others = Enumerable.Range(1, 40).Select(i => Make($"pubblico{i}.demo", false, Frequency.High, id: i)).ToList();
+ var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("studio.demo", followed: false, id: 500),
+ OtherAccounts = others,
+ Profile = CautionProfile.Prudent with { GradualStart = false },
+ });
+
+ Assert.IsTrue(estimate.OverBudget);
+ Assert.IsTrue(estimate.TotalProfileOpensPerDay > 100);
+ Assert.IsTrue(estimate.ProfileCheckEvery > estimate.ProfileCheckWanted, "Sparser, not forced.");
+ Assert.IsTrue(estimate.Warnings.Any(w => w.Contains("si diradano", StringComparison.Ordinal)));
+ Assert.IsTrue(estimate.ShareOfDailyBudget < 0.1);
+ }
+
+ [TestMethod]
+ public void AccountsThatAreNotContactedCostNothing()
+ {
+ var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
+ {
+ Account = Make("archivio.demo", followed: false, state: AccountState.ArchiveOnly),
+ Profile = CautionProfile.Prudent,
+ });
+ Assert.IsFalse(estimate.Contacted);
+ Assert.AreEqual(0, estimate.ProfileOpensPerDay);
+ StringAssert.Contains(estimate.Lines[0].Text, "Solo archivio");
+ }
+}
diff --git a/tests/Febe.Tests/Engine/CircuitBreakerTests.cs b/tests/Febe.Tests/Engine/CircuitBreakerTests.cs
new file mode 100644
index 0000000..e69d07b
--- /dev/null
+++ b/tests/Febe.Tests/Engine/CircuitBreakerTests.cs
@@ -0,0 +1,165 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Storage;
+using Febe.Tests.Engine.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class CircuitBreakerTests
+{
+ private static Signal Throttle(DateTimeOffset at) => new(SignalLevel.Throttle, "http-429", "https://sito.prova/api", at);
+
+ [TestMethod]
+ public async Task ThrottlesStopOneSixAndTwentyFourHoursThenHalveTheBudgets()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var breaker = bed.Breaker;
+ var t0 = bed.Clock.Now;
+
+ await breaker.ReportAsync(Throttle(t0));
+ Assert.AreEqual(BreakerStatus.Throttled, breaker.State.Status);
+ Assert.AreEqual(t0 + TimeSpan.FromHours(1), breaker.State.Until);
+ Assert.IsFalse(breaker.State.AllowsSiteActions);
+
+ bed.Clock.Advance(TimeSpan.FromHours(1));
+ Assert.AreEqual(BreakerStatus.Closed, breaker.State.Status);
+ Assert.AreEqual(t0 + TimeSpan.FromHours(1) + TimeSpan.FromHours(48), breaker.State.HalvedBudgetsUntil);
+
+ bed.Clock.Advance(TimeSpan.FromHours(1));
+ await breaker.ReportAsync(Throttle(bed.Clock.Now));
+ Assert.AreEqual(bed.Clock.Now + TimeSpan.FromHours(6), breaker.State.Until, "Second within 24 hours: 6 hours.");
+
+ bed.Clock.Advance(TimeSpan.FromHours(7));
+ Assert.IsTrue(breaker.State.AllowsSiteActions);
+ await breaker.ReportAsync(Throttle(bed.Clock.Now));
+ Assert.AreEqual(bed.Clock.Now + TimeSpan.FromHours(24), breaker.State.Until, "Third within 24 hours: 24 hours.");
+
+ bed.Clock.Advance(TimeSpan.FromHours(24));
+ Assert.IsTrue(breaker.State.AllowsSiteActions);
+ await breaker.FlushAsync();
+
+ var incidents = await bed.Db.Incidents.ListAsync(t0, bed.Clock.Now.AddSeconds(1));
+ Assert.HasCount(3, incidents);
+ Assert.IsTrue(incidents.All(i => i.Level == SignalLevel.Throttle && i.Signal == "http-429" && i.Url == "https://sito.prova/api"));
+ Assert.AreEqual(t0 + TimeSpan.FromHours(1), incidents[0].StoppedUntil);
+ Assert.AreEqual(incidents[0].StoppedUntil, incidents[0].ResolvedAt);
+ Assert.IsTrue(incidents.All(i => i.ResolvedAt is not null));
+ Assert.HasCount(0, await bed.Db.Incidents.ListOpenAsync());
+
+ var events = await bed.Db.Events.ListAsync(new EventQuery());
+ Assert.AreEqual(3, events.Count(e => e.Code == EngineEventCodes.ThrottleStop));
+ Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.ThrottleEnd));
+ }
+
+ [TestMethod]
+ public async Task AThrottleDuringAStopDoesNotEscalateIt()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ var until = bed.Breaker.State.Until;
+ bed.Clock.Advance(TimeSpan.FromMinutes(10));
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ Assert.AreEqual(until, bed.Breaker.State.Until);
+ await bed.Breaker.FlushAsync();
+ Assert.HasCount(1, await bed.Db.Incidents.ListAsync(bed.Clock.Now.AddDays(-1), bed.Clock.Now.AddDays(1)));
+ }
+
+ [TestMethod]
+ [DataRow(SignalLevel.Challenge, BreakerStatus.Challenge, EngineEventCodes.ChallengeStop)]
+ [DataRow(SignalLevel.Disconnect, BreakerStatus.Disconnected, EngineEventCodes.DisconnectStop)]
+ public async Task VerificationAndDisconnectionNeverRestartAlone(SignalLevel level, BreakerStatus status, string code)
+ {
+ await using var bed = await EngineTestBed.CreateAsync(gradualStart: true);
+ await bed.Breaker.ReportAsync(new Signal(level, "segnale-prova", "https://sito.prova/x", bed.Clock.Now));
+ Assert.AreEqual(status, bed.Breaker.State.Status);
+
+ bed.Clock.Advance(TimeSpan.FromDays(5));
+ Assert.AreEqual(status, bed.Breaker.State.Status);
+ Assert.IsFalse(bed.Breaker.State.AllowsSiteActions);
+ var open = await bed.Db.Incidents.ListOpenAsync();
+ Assert.HasCount(1, open);
+ Assert.AreEqual(level, open[0].Level);
+ Assert.IsNull(open[0].StoppedUntil);
+
+ var resumedAt = bed.Clock.Now;
+ Assert.IsTrue(await bed.Breaker.ResumeAsync());
+ Assert.AreEqual(BreakerStatus.Closed, bed.Breaker.State.Status);
+ Assert.HasCount(0, await bed.Db.Incidents.ListOpenAsync());
+
+ // The resume starts the gradual start again, persisted.
+ Assert.AreEqual(resumedAt, bed.Runtime.RampStart);
+ Assert.AreEqual(resumedAt.ToUnixTimeMilliseconds(), await bed.Db.Settings.GetInt64Async(EngineSettingKeys.RampStart));
+ Assert.AreEqual(0.5, bed.Governor.GetEffectiveBudgets(bed.Clock.Now).Factor, 1e-9);
+
+ var events = await bed.Db.Events.ListAsync(new EventQuery());
+ Assert.IsTrue(events.Any(e => e.Code == code && e.Severity == EventSeverity.Error));
+ Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.Resumed));
+ }
+
+ [TestMethod]
+ public async Task AThrottleStopCannotBeShortenedByResume()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ Assert.IsFalse(await bed.Breaker.ResumeAsync());
+ Assert.AreEqual(BreakerStatus.Throttled, bed.Breaker.State.Status);
+ }
+
+ [TestMethod]
+ public async Task TheStateIsRestoredFromTheDatabase()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ var until = bed.Breaker.State.Until;
+ await bed.Breaker.FlushAsync();
+
+ var restarted = await bed.ReopenAsync(seed: 99);
+ Assert.AreEqual(BreakerStatus.Throttled, restarted.Breaker.State.Status);
+ Assert.AreEqual(until, restarted.Breaker.State.Until);
+
+ bed.Clock.Advance(TimeSpan.FromHours(2));
+ await restarted.Breaker.ReportAsync(new Signal(SignalLevel.Challenge, "challenge-url", null, bed.Clock.Now));
+ var again = await bed.ReopenAsync(seed: 100);
+ Assert.AreEqual(BreakerStatus.Challenge, again.Breaker.State.Status);
+ Assert.IsNotNull(again.Breaker.State.HalvedBudgetsUntil, "The halving of the earlier throttle is restored too.");
+
+ // The expired throttle was resolved; resuming the verification leaves nothing open.
+ bed.Clock.Advance(TimeSpan.FromHours(1));
+ Assert.IsTrue(await again.Breaker.ResumeAsync());
+ Assert.HasCount(0, await bed.Db.Incidents.ListOpenAsync());
+ }
+
+ [TestMethod]
+ public async Task ThreeThrottlesInSevenDaysProposeAMorePrudentProfile()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(profile: CautionProfileKind.Fast);
+ for (var i = 0; i < 3; i++)
+ {
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ bed.Clock.Advance(TimeSpan.FromDays(2));
+ _ = bed.Breaker.State;
+ }
+
+ await bed.Breaker.FlushAsync();
+ var proposals = (await bed.Db.Events.ListAsync(new EventQuery())).Where(e => e.Code == EngineEventCodes.ProposeMorePrudence).ToList();
+ Assert.HasCount(1, proposals);
+ StringAssert.Contains(proposals[0].Message, "«Equilibrato»");
+ }
+
+ [TestMethod]
+ public async Task TwoThrottlesInSevenDaysAreNotYetAProposal()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ bed.Clock.Advance(TimeSpan.FromDays(8));
+ _ = bed.Breaker.State;
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ bed.Clock.Advance(TimeSpan.FromDays(2));
+ _ = bed.Breaker.State;
+ await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
+ await bed.Breaker.FlushAsync();
+ Assert.IsFalse((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.ProposeMorePrudence));
+ }
+}
diff --git a/tests/Febe.Tests/Engine/DayPlannerTests.cs b/tests/Febe.Tests/Engine/DayPlannerTests.cs
new file mode 100644
index 0000000..d69c861
--- /dev/null
+++ b/tests/Febe.Tests/Engine/DayPlannerTests.cs
@@ -0,0 +1,93 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Tests.Engine.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class DayPlannerTests
+{
+ [TestMethod]
+ public async Task TheWindowMovesEveryDayWithinTheJitterAndNotUniformly()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var planner = bed.Services.Planner;
+ var profile = CautionProfile.Prudent;
+ var day = new DateOnly(2026, 10, 14);
+ var starts = new List();
+ for (var i = 0; i < 300; i++)
+ {
+ var d = day.AddDays(i);
+ var window = await planner.GetWindowAsync(d);
+ Assert.IsNotNull(window);
+ var baseStart = LocalCalendar.FromLocal(d.ToDateTime(profile.WindowStart), EngineTestBed.Zone);
+ var baseEnd = LocalCalendar.FromLocal(d.ToDateTime(profile.WindowEnd), EngineTestBed.Zone);
+ var shiftStart = (window!.Start - baseStart).TotalMinutes;
+ var shiftEnd = (window.End - baseEnd).TotalMinutes;
+ Assert.IsTrue(Math.Abs(shiftStart) <= 40, $"start shift {shiftStart}");
+ Assert.IsTrue(Math.Abs(shiftEnd) <= 40, $"end shift {shiftEnd}");
+ starts.Add(shiftStart);
+ }
+
+ Assert.IsTrue(starts.Distinct().Count() > 250, "Every day has its own shift.");
+
+ // A normal shape: far more draws in the central half than a uniform draw would give (50%).
+ var central = starts.Count(s => Math.Abs(s) <= 20) / (double)starts.Count;
+ Assert.IsTrue(central > 0.62, $"central share {central}");
+ }
+
+ [TestMethod]
+ public async Task TheDailyShiftIsNotRedrawnAfterARestart()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var day = new DateOnly(2026, 10, 20);
+ var before = await bed.Services.Planner.GetWindowAsync(day);
+ var restarted = await bed.ReopenAsync(seed: 12345);
+ var after = await restarted.Planner.GetWindowAsync(day);
+ Assert.AreEqual(before, after);
+ }
+
+ [TestMethod]
+ public async Task AWindowMayEndAfterMidnight()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(profile: CautionProfileKind.Fast);
+ var day = new DateOnly(2026, 10, 14);
+ var window = await bed.Services.Planner.GetWindowAsync(day);
+ Assert.IsNotNull(window);
+ Assert.AreEqual(day.AddDays(1), LocalCalendar.Today(window!.End, EngineTestBed.Zone), "06:30–00:30 ends on the next day.");
+
+ // Ten minutes before the end, after midnight, the instant belongs to the window of the previous day.
+ var lateNight = window.End - TimeSpan.FromMinutes(10);
+ var found = await bed.Services.Planner.GetWindowAtAsync(lateNight);
+ Assert.AreEqual(window, found);
+ Assert.IsNull(await bed.Services.Planner.GetWindowAtAsync(window.End + TimeSpan.FromMinutes(10)));
+ }
+
+ [TestMethod]
+ public async Task InactiveDaysHaveNoWindow()
+ {
+ var weekdays = new HashSet { DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Wednesday, DayOfWeek.Thursday, DayOfWeek.Friday };
+ await using var bed = await EngineTestBed.CreateAsync(settings: new EngineSettings { GradualStart = false, ActiveDays = weekdays });
+ var saturday = new DateOnly(2026, 10, 17);
+ Assert.IsNull(await bed.Services.Planner.GetWindowAsync(saturday));
+ var next = await bed.Services.Planner.GetNextWindowAsync(LocalCalendar.StartOfDay(saturday, EngineTestBed.Zone).AddHours(12));
+ Assert.AreEqual(new DateOnly(2026, 10, 19), next!.Day);
+ }
+
+ [TestMethod]
+ public void WindowsAreComputedAcrossDaylightSavingTime()
+ {
+ // 25 October 2026: clocks go back in Rome at 3:00; the window is still 07:30–23:30 local time.
+ var profile = CautionProfile.Prudent with { WindowJitter = TimeSpan.Zero };
+ var window = DayPlanner.Compute(new DateOnly(2026, 10, 25), profile, 42, EngineTestBed.Zone);
+ Assert.AreEqual(new TimeOnly(7, 30), TimeOnly.FromDateTime(LocalCalendar.ToLocal(window.Start, EngineTestBed.Zone)));
+ Assert.AreEqual(new TimeOnly(23, 30), TimeOnly.FromDateTime(LocalCalendar.ToLocal(window.End, EngineTestBed.Zone)));
+ Assert.AreEqual(TimeSpan.FromHours(16), window.Length);
+
+ // 28 March 2027: clocks go forward at 2:00; a window from 22:00 to 6:00 loses that hour.
+ var night = profile with { WindowStart = new TimeOnly(22, 0), WindowEnd = new TimeOnly(6, 0) };
+ var spring = DayPlanner.Compute(new DateOnly(2027, 3, 27), night, 42, EngineTestBed.Zone);
+ Assert.AreEqual(TimeSpan.FromHours(7), spring.Length);
+ }
+}
diff --git a/tests/Febe.Tests/Engine/EngineHostTests.cs b/tests/Febe.Tests/Engine/EngineHostTests.cs
new file mode 100644
index 0000000..b7abe54
--- /dev/null
+++ b/tests/Febe.Tests/Engine/EngineHostTests.cs
@@ -0,0 +1,473 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Storage;
+using Febe.Tests.Engine.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class EngineHostTests
+{
+ private static readonly DateTimeOffset Morning = EngineTestBed.Local(2026, 10, 14, 6, 0);
+
+ private static async Task> SessionsAsync(EngineTestBed bed) =>
+ await bed.Db.Sessions.ListAsync(bed.Clock.Now.AddDays(-30), bed.Clock.Now.AddDays(1));
+
+ [TestMethod]
+ public async Task SessionsStayInsideTheWindowAndRespectThePauseFloor()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ await bed.AddAccountAsync("uno.demo", followed: false, Frequency.High);
+ await bed.AddAccountAsync("due.demo", followed: true);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(2));
+
+ var sessions = await SessionsAsync(bed);
+ Assert.IsTrue(sessions.Count > 20, $"{sessions.Count} sessions");
+ for (var i = 1; i < sessions.Count; i++)
+ {
+ var pause = sessions[i].StartedAt - sessions[i - 1].EndedAt!.Value;
+ Assert.IsTrue(pause >= TimeSpan.FromMinutes(20), $"pause of {pause}");
+ }
+
+ foreach (var session in sessions)
+ {
+ Assert.IsNotNull(await bed.Services.Planner.GetWindowAtAsync(session.StartedAt), $"session at {session.StartedAt:O}");
+ }
+
+ Assert.HasCount(0, await BudgetAudit.OutsideWindowAsync(bed.Db, bed.Services.Planner, Morning, bed.Clock.Now));
+ Assert.HasCount(0, await BudgetAudit.OverrunsAsync(bed.Db, bed.Runtime.Profile, EngineTestBed.Zone, Morning, bed.Clock.Now));
+ Assert.AreEqual(sessions.Count(s => s.EndedAt is not null), runner.Rests, "Every session ends on the empty page.");
+
+ // The first session comes 2–10 minutes after the start, but not before the window.
+ var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
+ Assert.IsTrue(sessions[0].StartedAt >= window!.Start);
+ }
+
+ [TestMethod]
+ public async Task TheFirstSessionComesTwoToTenMinutesAfterTheStart()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Noon);
+ await bed.AddAccountAsync("uno.demo", followed: true);
+ bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunForAsync(TimeSpan.FromMinutes(30));
+ var first = (await SessionsAsync(bed))[0].StartedAt - EngineTestBed.Noon;
+ Assert.IsTrue(first >= TimeSpan.FromMinutes(2) && first <= TimeSpan.FromMinutes(10), $"first session after {first}");
+ }
+
+ [TestMethod]
+ public async Task ARestartResetsNoCountsAndDoesNotShortenPauses()
+ {
+ // 60 profiles a day, and no hourly limit in the way: demand is far above it.
+ var custom = CautionProfile.Prudent with
+ {
+ Budgets = new Dictionary(CautionProfile.Prudent.Budgets) { [ActionKind.ProfileOpen] = new Budget(60, 60) },
+ };
+ await using var bed = await EngineTestBed.CreateAsync(Morning, settings: new EngineSettings { GradualStart = false }.WithCustomValues(custom));
+ for (var i = 0; i < 30; i++)
+ {
+ await bed.AddAccountAsync($"pubblico{i}.demo", followed: false, Frequency.High, types: ContentTypes.PostPhotos | ContentTypes.PostVideos);
+ }
+
+ await bed.AddAccountAsync("seguito.demo", followed: true);
+ bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
+ await bed.RunUntilAsync(window!.Start + TimeSpan.FromMinutes(70));
+ var openedBefore = await bed.Db.ActionLog.SumAsync(ActionKind.ProfileOpen, Morning, bed.Clock.Now);
+ Assert.IsTrue(openedBefore is > 0 and < 60, $"{openedBefore} profiles opened before the restart");
+
+ await bed.StopAsync();
+ var plannedNext = DateTimeOffset.FromUnixTimeMilliseconds((await bed.Db.Settings.GetInt64Async(EngineSettingKeys.NextSession))!.Value);
+ var lastEnd = (await SessionsAsync(bed)).Max(s => s.EndedAt!.Value);
+ var restartAt = bed.Clock.Now + TimeSpan.FromMinutes(1);
+ bed.Clock.AdvanceTo(restartAt);
+ await bed.ReopenAsync(seed: 4242);
+ bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 15, 0, 0));
+
+ var after = (await SessionsAsync(bed)).Where(s => s.StartedAt >= restartAt).ToList();
+ Assert.IsNotEmpty(after);
+ Assert.IsTrue(after[0].StartedAt >= plannedNext, "Not earlier than the session planned before the restart.");
+ Assert.IsTrue(after[0].StartedAt - lastEnd >= TimeSpan.FromMinutes(20), "The pause floor holds across the restart.");
+ Assert.IsTrue(after[0].StartedAt - restartAt >= TimeSpan.FromMinutes(2));
+
+ // Demand is far above the budget: the day ends exactly at the daily budget, counting the morning before the restart.
+ var openedToday = await bed.Db.ActionLog.SumAsync(ActionKind.ProfileOpen, Morning, bed.Clock.Now);
+ Assert.AreEqual(60L, openedToday);
+ Assert.HasCount(0, await BudgetAudit.OverrunsAsync(bed.Db, bed.Runtime.Profile, EngineTestBed.Zone, Morning, bed.Clock.Now));
+ }
+
+ [TestMethod]
+ public async Task RepeatedRestartsDoNotProduceMoreSessions()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ await bed.AddAccountAsync("uno.demo", followed: true);
+ var seed = 500;
+ for (var hour = 0; hour < 18; hour++)
+ {
+ bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunForAsync(TimeSpan.FromMinutes(59));
+ await bed.StopAsync();
+ await bed.ReopenAsync(++seed);
+ }
+
+ var sessions = await SessionsAsync(bed);
+ for (var i = 1; i < sessions.Count; i++)
+ {
+ Assert.IsTrue(sessions[i].StartedAt - sessions[i - 1].EndedAt!.Value >= TimeSpan.FromMinutes(20));
+ }
+
+ // A program that stays on makes at most 16 h / 20 min sessions in a window; restarts every hour stay well below.
+ Assert.IsTrue(sessions.Count <= 48, $"{sessions.Count} sessions");
+ }
+
+ [TestMethod]
+ public async Task MostSessionsOpenWithTheSweepAndAccountsComeInRandomOrder()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ for (var i = 0; i < 8; i++)
+ {
+ await bed.AddAccountAsync($"pubblico{i}.demo", followed: false, Frequency.High, types: ContentTypes.PostPhotos | ContentTypes.PostVideos);
+ }
+
+ await bed.AddAccountAsync("seguito.demo", followed: true);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(3));
+
+ var bySession = runner.Runs.GroupBy(r => r.SessionId).ToList();
+ var openedWithSweep = bySession.Count(g => g.First().Request.Kind == RecipeKind.FollowingSweep) / (double)bySession.Count;
+ Assert.IsTrue(openedWithSweep is > 0.75 and < 0.99, $"sweep first in {openedWithSweep:P0} of sessions");
+
+ var orders = bySession
+ .Select(g => string.Join(",", g.Where(r => r.Request.Kind == RecipeKind.ProfileCheck).Select(r => r.Request.AccountId)))
+ .Where(o => o.Contains(',', StringComparison.Ordinal))
+ .ToList();
+ Assert.IsTrue(orders.Distinct().Count() > orders.Count / 2, "The order of the accounts changes from session to session.");
+
+ // About one session in three stops after sweep and stories even with profile checks due.
+ var withChecks = bySession.Count(g => g.Any(r => r.Request.Kind == RecipeKind.ProfileCheck)) / (double)bySession.Count;
+ Assert.IsTrue(withChecks is > 0.45 and < 0.85, $"{withChecks:P0} of sessions with profile checks");
+ }
+
+ [TestMethod]
+ public async Task BackfillWaitsWhileTheAccountHasMoreThanSixtyFilesToDownload()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ var account = await bed.AddAccountAsync("storico.demo", followed: true, state: AccountState.Backfilling, postCount: 3000);
+ for (var i = 0; i < 61; i++)
+ {
+ await bed.Db.Entries.AddAsync(
+ new Entry { AccountId = account.Id, Kind = EntryKind.Post, InstagramId = "attesa" + i, PublishedAt = Morning.AddDays(-400 + i), DiscoveredAt = Morning.AddDays(-1) },
+ [new Media { Position = 1, Kind = MediaKind.Photo, State = MediaState.ToDownload }]);
+ }
+
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(1));
+ Assert.IsFalse(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill));
+ Assert.IsTrue((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.BackfillWaiting && e.AccountId == account.Id));
+
+ // Down to 60 waiting files: the backfill goes on.
+ var pending = await bed.Db.Media.ListPendingDownloadsAsync(10);
+ await bed.Db.Media.MarkStoredAsync(pending[0].Media.Id, new StoredFile("post/a.jpg", 10, new string('a', 64)), MediaState.Downloaded, bed.Clock.Now);
+ await bed.RunUntilAsync(Morning.AddDays(2));
+ Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill && r.Request.AccountId == account.Id));
+ }
+
+ [TestMethod]
+ public async Task BackfillWaitsWhenTheDataBudgetIsReached()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ await bed.AddAccountAsync("storico.demo", followed: true, state: AccountState.Backfilling, postCount: 3000);
+ await bed.Governor.RecordAsync(4L * 1024 * 1024 * 1024, null, CancellationToken.None);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ bed.Start(runner);
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 15, 0, 0));
+ Assert.IsFalse(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill));
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 15, 23, 0));
+ Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill));
+ }
+
+ [TestMethod]
+ public async Task BackfillAlternatesAmongAccountsAndPausesAfterTheSingleDownload()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ var first = await bed.AddAccountAsync("primo.demo", followed: true, state: AccountState.Backfilling, postCount: 500);
+ var second = await bed.AddAccountAsync("secondo.demo", followed: true, state: AccountState.Backfilling, postCount: 500);
+ await bed.Db.Accounts.UpdateAsync((await bed.Db.Accounts.GetAsync(second.Id))! with { KeepUpdated = false });
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var backfills = 0;
+ DateTimeOffset? finishedAt = null;
+ runner.Script = request =>
+ {
+ if (request.Kind != RecipeKind.Backfill || request.AccountId != second.Id || ++backfills < 3)
+ {
+ return null;
+ }
+
+ finishedAt = bed.Clock.Now;
+ return new RecipeOutcome(RecipeStatus.Completed, 1, 12) { BackfillFinished = true };
+ };
+ bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(1));
+
+ var sequence = runner.Runs.Where(r => r.Request.Kind == RecipeKind.Backfill).Select(r => r.Request.AccountId!.Value).Take(4).ToList();
+ CollectionAssert.AreEqual(new[] { first.Id, second.Id, first.Id, second.Id }, sequence, "One account per session, alternating.");
+ Assert.IsTrue(runner.Runs.GroupBy(r => r.SessionId).All(g => g.Count(r => r.Request.Kind == RecipeKind.Backfill) <= 1));
+
+ var finished = await bed.Db.Accounts.GetAsync(second.Id);
+ Assert.AreEqual(AccountState.Paused, finished!.State, "«Tieni aggiornato» off: one download, then paused.");
+ Assert.IsNotNull(finished.BackfillCompletedAt);
+ Assert.IsTrue((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.BackfillCompleted));
+ Assert.IsFalse(runner.Runs.Any(r => r.Request.AccountId == second.Id && r.At > finishedAt), "A paused account is not contacted.");
+ }
+
+ [TestMethod]
+ public async Task ThreeUnrecognizedFormatsInARowSuspendTheRecipe()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ var account = await bed.AddAccountAsync("strano.demo", followed: false, Frequency.High);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock)
+ {
+ Script = r => r.Kind == RecipeKind.ProfileCheck ? new RecipeOutcome(RecipeStatus.UnrecognizedFormat, 1, 0) : null,
+ };
+ var host = bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(2));
+
+ Assert.AreEqual(3, runner.Runs.Count(r => r.Request.Kind == RecipeKind.ProfileCheck));
+ Assert.IsTrue(host.SuspendedRecipes.ContainsKey(RecipeKind.ProfileCheck));
+ var events = await bed.Db.Events.ListAsync(new EventQuery());
+ Assert.AreEqual(3, events.Count(e => e.Code == EngineEventCodes.FormatUnrecognized));
+ Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.RecipeSuspended && e.Severity == EventSeverity.Error));
+ Assert.IsTrue((await bed.Db.Accounts.GetAsync(account.Id))!.Notices.HasFlag(AccountNotices.UnrecognizedFormat));
+ var snapshot = await host.Monitor.GetSnapshotAsync();
+ Assert.HasCount(1, snapshot.SuspendedRecipes);
+
+ runner.Script = null;
+ Assert.IsTrue(await host.ResumeRecipeAsync(RecipeKind.ProfileCheck));
+ await bed.RunUntilAsync(Morning.AddDays(3));
+ Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.ProfileCheck && r.Status == RecipeStatus.Completed));
+ }
+
+ [TestMethod]
+ public async Task AnUnreachableAccountIsNotContactedAnyMore()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ var account = await bed.AddAccountAsync("sparito.demo", followed: false, Frequency.High);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock)
+ {
+ Script = r => r.AccountId == account.Id ? new RecipeOutcome(RecipeStatus.AccountUnreachable, 1, 0) : null,
+ };
+ bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(1));
+ Assert.AreEqual(1, runner.Runs.Count(r => r.Request.AccountId == account.Id));
+ Assert.AreEqual(AccountState.Unreachable, (await bed.Db.Accounts.GetAsync(account.Id))!.State);
+ Assert.IsTrue((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.AccountUnreachable));
+ }
+
+ [TestMethod]
+ public async Task AThrottleClosesTheSessionAtOnceAndStopsForAnHour()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ await bed.AddAccountAsync("uno.demo", followed: false, Frequency.High);
+ await bed.AddAccountAsync("due.demo", followed: false, Frequency.High);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ DateTimeOffset? throttledAt = null;
+ runner.AfterGrant = r =>
+ {
+ if (throttledAt is null && r.Kind == RecipeKind.ProfileCheck)
+ {
+ throttledAt = bed.Clock.Now;
+ bed.Breaker.Report(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
+ }
+ };
+ bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(1));
+
+ Assert.IsNotNull(throttledAt);
+ var sessions = await SessionsAsync(bed);
+ var stopped = sessions.Single(s => s.StartedAt <= throttledAt && s.EndedAt >= throttledAt);
+ Assert.AreEqual(SessionOutcome.Throttled, stopped.Outcome);
+ Assert.IsTrue(stopped.EndedAt - throttledAt < TimeSpan.FromSeconds(30), "The session closes at once.");
+ var during = await bed.Db.ActionLog.ListAsync(throttledAt.Value.AddMilliseconds(1), throttledAt.Value + TimeSpan.FromHours(1));
+ Assert.HasCount(0, during.Where(a => a.Category != ActionKind.DataDownload).ToList());
+ Assert.IsTrue(sessions.Any(s => s.StartedAt > throttledAt.Value + TimeSpan.FromHours(1)), "It starts again by itself.");
+ }
+
+ [TestMethod]
+ public async Task AfterAVerificationNothingStartsUntilResumeWhichRestartsTheGradualStart()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning, gradualStart: true);
+ await bed.AddAccountAsync("uno.demo", followed: false, Frequency.High);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var challenged = false;
+ runner.AfterGrant = r =>
+ {
+ if (!challenged)
+ {
+ challenged = true;
+ bed.Breaker.Report(new Signal(SignalLevel.Challenge, "challenge-url", "https://sito.prova/challenge", bed.Clock.Now));
+ }
+ };
+ var host = bed.Start(runner);
+ await bed.RunUntilAsync(Morning.AddDays(3));
+
+ Assert.IsTrue(challenged);
+ Assert.AreEqual(1, runner.Runs.Count, "Nothing after the verification signal.");
+ Assert.AreEqual(0, runner.Rests, "The page is left as it is.");
+ var snapshot = await host.Monitor.GetSnapshotAsync();
+ Assert.AreEqual(EngineMode.StoppedForVerification, snapshot.Mode);
+ Assert.IsNotNull(snapshot.Banner);
+ Assert.AreEqual(BannerLevel.Error, snapshot.Banner!.Level);
+
+ var resume = await host.ResumeAsync();
+ Assert.IsTrue(resume.Resumed);
+ Assert.AreEqual(0.5, bed.Governor.GetEffectiveBudgets(bed.Clock.Now).Factor, 1e-9);
+ await bed.RunForAsync(TimeSpan.FromHours(6));
+ Assert.IsTrue(runner.Runs.Count > 1, "Work goes on after «Riprendi».");
+ }
+
+ [TestMethod]
+ public async Task PauseStopsEverythingUntilResume()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ await bed.AddAccountAsync("uno.demo", followed: true);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var host = bed.Start(runner);
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 10, 0));
+ await host.PauseAsync();
+ var count = runner.Runs.Count;
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 20, 0));
+ Assert.AreEqual(count, runner.Runs.Count);
+ Assert.AreEqual(EngineMode.Paused, (await host.Monitor.GetSnapshotAsync()).Mode);
+ Assert.IsTrue(await bed.Db.Settings.GetBoolAsync(EngineSettingKeys.Paused, false));
+
+ await host.ResumeAsync();
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 22, 0));
+ Assert.IsTrue(runner.Runs.Count > count);
+ }
+
+ [TestMethod]
+ public async Task WhileAlbertoUsesTheBrowserTheEngineDoesNotAct()
+ {
+ var driving = false;
+ await using var bed = await EngineTestBed.CreateAsync(Morning, userIsDriving: () => driving);
+ await bed.AddAccountAsync("uno.demo", followed: true);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var host = bed.Start(runner);
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 10, 0));
+ driving = true;
+ host.NotifyUserDrivingChanged();
+ var count = runner.Runs.Count;
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 14, 0));
+ Assert.AreEqual(count, runner.Runs.Count);
+ Assert.AreEqual(EngineMode.UserDriving, (await host.Monitor.GetSnapshotAsync()).Mode);
+ driving = false;
+ host.NotifyUserDrivingChanged();
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 16, 0));
+ Assert.IsTrue(runner.Runs.Count > count);
+ }
+
+ [TestMethod]
+ public async Task WithoutAnInstagramSessionNothingStarts()
+ {
+ var connected = false;
+ await using var bed = await EngineTestBed.CreateAsync(Morning, isConnected: () => connected);
+ await bed.AddAccountAsync("uno.demo", followed: true);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var host = bed.Start(runner);
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 14, 0));
+ Assert.IsEmpty(runner.Runs);
+ Assert.AreEqual(EngineMode.NotConnected, (await host.Monitor.GetSnapshotAsync()).Mode);
+
+ connected = true;
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 16, 0));
+ Assert.IsNotEmpty(runner.Runs);
+ }
+
+ [TestMethod]
+ public async Task CheckNowOutsideTheWindowNeedsConfirmationAndRunsOnlyThatCheck()
+ {
+ var night = EngineTestBed.Local(2026, 10, 14, 1, 0);
+ await using var bed = await EngineTestBed.CreateAsync(night);
+ var asked = await bed.AddAccountAsync("chiesto.demo", followed: false);
+ await bed.AddAccountAsync("altro.demo", followed: false, Frequency.High);
+ await bed.AddAccountAsync("seguito.demo", followed: true);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var host = bed.Start(runner);
+ await bed.RunForAsync(TimeSpan.FromMinutes(20));
+ Assert.IsEmpty(runner.Runs, "Nothing at night on the engine's initiative.");
+
+ var first = await host.CheckNowAsync(asked.Id);
+ Assert.AreEqual(CheckNowStatus.NeedsConfirmation, first.Status);
+ Assert.IsNotNull(first.ConfirmationToken);
+ StringAssert.Contains(first.Message, "fuori dalla fascia");
+ Assert.AreEqual(CheckNowStatus.NeedsConfirmation, (await host.CheckNowAsync(asked.Id, "gettone-sbagliato")).Status);
+
+ var confirmed = await host.CheckNowAsync(asked.Id, first.ConfirmationToken);
+ Assert.AreEqual(CheckNowStatus.Queued, confirmed.Status);
+ await bed.RunForAsync(TimeSpan.FromHours(2));
+
+ Assert.IsNotEmpty(runner.Runs);
+ Assert.IsTrue(runner.Runs.All(r => r.Request.AccountId == asked.Id), "Only the confirmed check.");
+ Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.ProfileCheck && r.Request.Manual));
+ Assert.HasCount(1, runner.Runs.Select(r => r.SessionId).Distinct().ToList());
+ var actions = await bed.Db.ActionLog.ListAsync(night, bed.Clock.Now);
+ Assert.IsTrue(actions.All(a => a.AccountId == asked.Id));
+
+ // The token was used: a second check needs a new confirmation.
+ Assert.AreEqual(CheckNowStatus.NeedsConfirmation, (await host.CheckNowAsync(asked.Id, first.ConfirmationToken)).Status);
+
+ // Normal work waits for the window.
+ var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
+ await bed.RunUntilAsync(window!.Start + TimeSpan.FromHours(2));
+ Assert.IsTrue(runner.Runs.Where(r => r.Request.AccountId != asked.Id).All(r => r.At >= window.Start));
+ Assert.IsTrue(runner.Runs.Any(r => r.Request.AccountId != asked.Id));
+ }
+
+ [TestMethod]
+ public async Task CheckNowInsideTheWindowGoesOnTopOfTheQueueButAfterThePauseFloor()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ var asked = await bed.AddAccountAsync("chiesto.demo", followed: true, Frequency.Low);
+ var runner = new ScriptedRunner(bed.Governor, bed.Clock);
+ var host = bed.Start(runner);
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 12, 0));
+ var before = runner.Runs.Count(r => r.Request.Manual);
+
+ var askedAt = bed.Clock.Now;
+ var result = await host.CheckNowAsync(asked.Id);
+ Assert.AreEqual(CheckNowStatus.Queued, result.Status);
+ StringAssert.Contains(result.Message, "cima alla coda");
+ await bed.RunForAsync(TimeSpan.FromMinutes(45));
+ var manual = runner.Runs.Where(r => r.Request.Manual).ToList();
+ Assert.AreEqual(before + 2, manual.Count, "Profile check and stories, on request.");
+ var session = (await SessionsAsync(bed)).Single(s => s.Id == manual[^1].SessionId);
+ var previous = (await SessionsAsync(bed)).Where(s => s.EndedAt <= session.StartedAt).Max(s => s.EndedAt!.Value);
+ Assert.IsTrue(session.StartedAt - previous >= TimeSpan.FromMinutes(20));
+ if (session.StartedAt >= askedAt)
+ {
+ Assert.IsTrue(runner.Runs.First(r => r.SessionId == session.Id).Request.Manual, "First thing of the session.");
+ }
+ }
+
+ [TestMethod]
+ public async Task CheckNowWithTheBudgetExhaustedIsRefused()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(Morning);
+ var asked = await bed.AddAccountAsync("chiesto.demo", followed: false);
+ for (var i = 0; i < 100; i++)
+ {
+ await bed.Db.ActionLog.AppendAsync(new ActionLogRecord { At = Morning.AddSeconds(i), Category = ActionKind.ProfileOpen });
+ }
+
+ var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 12, 0));
+ var result = await host.CheckNowAsync(asked.Id);
+ Assert.AreEqual(CheckNowStatus.Refused, result.Status);
+ StringAssert.Contains(result.Message, "tetto giornaliero");
+ }
+}
diff --git a/tests/Febe.Tests/Engine/EngineMonitorTests.cs b/tests/Febe.Tests/Engine/EngineMonitorTests.cs
new file mode 100644
index 0000000..a2ed6ac
--- /dev/null
+++ b/tests/Febe.Tests/Engine/EngineMonitorTests.cs
@@ -0,0 +1,127 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Tests.Engine.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class EngineMonitorTests
+{
+ [TestMethod]
+ public async Task AtNightTheMonitorSaysWhenWorkResumes()
+ {
+ var night = EngineTestBed.Local(2026, 10, 14, 2, 0);
+ await using var bed = await EngineTestBed.CreateAsync(night);
+ await bed.AddAccountAsync("marta.demo", followed: true);
+ var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunForAsync(TimeSpan.FromMinutes(15));
+
+ var snapshot = await host.Monitor.GetSnapshotAsync();
+ Assert.AreEqual(EngineMode.OutsideWindow, snapshot.Mode);
+ Assert.AreEqual("Fuori fascia", snapshot.Headline);
+ StringAssert.Contains(snapshot.SidebarLine, "Riprende verso le ");
+ var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
+ Assert.AreEqual(window!.Start, snapshot.ResumesAround);
+ Assert.IsNull(snapshot.Banner);
+ Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.OutsideWindow && s.Start == snapshot.Today.Start));
+ Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.PlannedSession && s.Indicative));
+ Assert.IsTrue(snapshot.Queue.All(q => q.When.StartsWith("verso le", StringComparison.Ordinal)));
+ Assert.AreEqual(4, snapshot.MainBudgets.Count);
+ CollectionAssert.AreEqual(
+ new[] { ActionKind.ProfileOpen, ActionKind.StoryView, ActionKind.BackfillPage, ActionKind.DataDownload },
+ snapshot.MainBudgets.Select(b => b.Kind).ToArray());
+ Assert.AreEqual(Enum.GetValues().Length, snapshot.AllBudgets.Count);
+ Assert.AreEqual("Profili aperti", snapshot.ProfilesOpenedToday.Label);
+ Assert.AreEqual("di 100", snapshot.ProfilesOpenedToday.LimitText);
+ }
+
+ [TestMethod]
+ public async Task DuringTheDayTheStripShowsSessionsRestsAndTheSummary()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 6, 0));
+ await bed.AddAccountAsync("marta.demo", followed: true);
+ await bed.AddAccountAsync("luca.demo", followed: false, Frequency.High);
+ var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 15, 0));
+
+ var snapshot = await host.Monitor.GetSnapshotAsync();
+ Assert.IsTrue(snapshot.Mode is EngineMode.Resting or EngineMode.InSession);
+ Assert.IsTrue(snapshot.Today.Spans.Count(s => s.Kind is StripSpanKind.Session or StripSpanKind.CurrentSession) >= 5);
+ Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.Rest));
+ StringAssert.Contains(snapshot.Today.Summary, "sessioni");
+ StringAssert.Contains(snapshot.Today.Summary, "nessun rallentamento");
+ Assert.IsNotEmpty(snapshot.RecentActions);
+ Assert.IsTrue(snapshot.RecentActions.Any(a => a.Title == "Giro dei profili che segui" || a.Title.StartsWith('@')));
+ if (snapshot.Mode == EngineMode.Resting)
+ {
+ Assert.AreEqual("In ascolto", snapshot.Headline);
+ StringAssert.StartsWith(snapshot.Details[0], "Riprende verso le ");
+ }
+
+ var profiles = snapshot.ProfilesOpenedToday;
+ Assert.IsTrue(profiles.UsedToday > 0);
+ StringAssert.StartsWith(profiles.Note, "In questa ora ");
+ }
+
+ [TestMethod]
+ public async Task AThrottleShowsAnAmberStripAndSuspendsTheQueue()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ await bed.AddAccountAsync("marta.demo", followed: true);
+ var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ await bed.RunForAsync(TimeSpan.FromMinutes(1));
+ await bed.Breaker.ReportAsync(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
+
+ var snapshot = await host.Monitor.GetSnapshotAsync();
+ Assert.AreEqual(EngineMode.Throttled, snapshot.Mode);
+ Assert.AreEqual(BannerLevel.Warning, snapshot.Banner!.Level);
+ StringAssert.Contains(snapshot.Banner.Message, "tetti dimezzati");
+ Assert.IsTrue(snapshot.Queue.All(q => q.Suspended && q.When == "Sospeso"));
+ Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.Throttle));
+ StringAssert.StartsWith(snapshot.ProfilesOpenedToday.Note, "Fermo dalle ");
+ StringAssert.Contains(snapshot.ReductionNote!, "Tetti dimezzati");
+ }
+
+ [TestMethod]
+ public async Task TheEventStreamDeliversTimelineLines()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
+ using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(20));
+ var received = new List();
+ var reading = Task.Run(async () =>
+ {
+ await foreach (var notification in host.Monitor.SubscribeAsync(cts.Token))
+ {
+ received.Add(notification);
+ if (notification.Kind == EngineNotificationKind.Event && notification.Event!.Code == EngineEventCodes.Paused)
+ {
+ break;
+ }
+ }
+ });
+ await Task.Delay(100);
+ await host.PauseAsync();
+ await reading;
+ Assert.IsTrue(received.Any(n => n.Event?.Code == EngineEventCodes.Paused));
+ StringAssert.Contains(received.Last().Event!.Message, "Riprendi");
+ }
+
+ [TestMethod]
+ public void ItalianTextUsesDotsCommasAndVersoLe()
+ {
+ Assert.AreEqual("7.682", ItalianText.Number(7682));
+ Assert.AreEqual("1.234.567", ItalianText.Number(1234567));
+ Assert.AreEqual("1,3 GB", ItalianText.Bytes((long)(1.3 * 1024 * 1024 * 1024)));
+ Assert.AreEqual("0,5", ItalianText.Decimal(0.5));
+ var zone = EngineTestBed.Zone;
+ var now = EngineTestBed.Local(2026, 10, 14, 12, 0);
+ Assert.AreEqual("verso le 15:30", ItalianText.Around(EngineTestBed.Local(2026, 10, 14, 15, 30), now, zone));
+ Assert.AreEqual("domani verso le 7:42", ItalianText.Around(EngineTestBed.Local(2026, 10, 15, 7, 42), now, zone));
+ Assert.AreEqual("verso l'1:05", ItalianText.Around(EngineTestBed.Local(2026, 10, 14, 13, 5).AddHours(12), now.AddHours(12), zone));
+ Assert.AreEqual("1 ora e 20 minuti", ItalianText.Duration(TimeSpan.FromMinutes(80)));
+ Assert.AreEqual("ogni 75 minuti", ItalianText.Every(TimeSpan.FromMinutes(75)));
+ Assert.AreEqual("ogni 3 ore", ItalianText.Every(TimeSpan.FromHours(3)));
+ }
+}
diff --git a/tests/Febe.Tests/Engine/EngineSettingsTests.cs b/tests/Febe.Tests/Engine/EngineSettingsTests.cs
new file mode 100644
index 0000000..5c44138
--- /dev/null
+++ b/tests/Febe.Tests/Engine/EngineSettingsTests.cs
@@ -0,0 +1,95 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Data;
+using Febe.Tests.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class EngineSettingsTests
+{
+ [TestMethod]
+ public async Task SettingsAreStoredAndReadBackWithACustomProfile()
+ {
+ using var folder = new TempFolder("impostazioni");
+ await using var db = await FebeDatabase.OpenAsync(folder.Combine("dati"));
+ Assert.AreEqual(CautionProfileKind.Prudent, (await EngineSettingsStore.LoadAsync(db.Settings)).ProfileKind, "«Prudente» is the default.");
+
+ var custom = CautionProfile.Balanced with
+ {
+ PauseMin = TimeSpan.FromMinutes(15),
+ WindowStart = new TimeOnly(8, 0),
+ WindowEnd = new TimeOnly(0, 30),
+ Budgets = new Dictionary(CautionProfile.Balanced.Budgets) { [ActionKind.ProfileOpen] = new Budget(18, 150) },
+ };
+ var settings = new EngineSettings { Pace = GesturePace.Slow, GradualStart = false, ActiveDays = new HashSet { DayOfWeek.Monday, DayOfWeek.Saturday } }
+ .WithCustomValues(custom);
+ await EngineSettingsStore.SaveAsync(db.Settings, settings);
+
+ var loaded = await EngineSettingsStore.LoadAsync(db.Settings);
+ Assert.AreEqual(CautionProfileKind.Custom, loaded.ProfileKind);
+ Assert.AreEqual(GesturePace.Slow, loaded.Pace);
+ Assert.IsFalse(loaded.GradualStart);
+ CollectionAssert.AreEquivalent(new[] { DayOfWeek.Monday, DayOfWeek.Saturday }, loaded.ActiveDays.ToArray());
+ var effective = loaded.EffectiveProfile;
+ Assert.AreEqual(CautionProfileKind.Custom, effective.Kind);
+ Assert.AreEqual(TimeSpan.FromMinutes(15), effective.PauseMin);
+ Assert.AreEqual(new TimeOnly(0, 30), effective.WindowEnd);
+ Assert.AreEqual(new Budget(18, 150), effective.Budgets[ActionKind.ProfileOpen]);
+ Assert.AreEqual(CautionProfile.Balanced.DataPerDayBytes, effective.DataPerDayBytes);
+ Assert.AreEqual(GesturePace.Slow, effective.Pace);
+ }
+
+ [TestMethod]
+ public void TheLimitsOfTheInterfaceAreEnforced()
+ {
+ var bad = CautionProfile.Fast with
+ {
+ PauseMin = TimeSpan.FromMinutes(4),
+ SessionMax = TimeSpan.FromMinutes(31),
+ WindowStart = new TimeOnly(5, 0),
+ WindowEnd = new TimeOnly(2, 0),
+ Budgets = new Dictionary(CautionProfile.Fast.Budgets) { [ActionKind.StoryView] = new Budget(241, 800) },
+ DataPerDayBytes = CautionProfile.Limits.MaxDataPerDayBytes + 1,
+ };
+ var errors = CautionProfileRules.Validate(bad);
+ Assert.IsTrue(errors.Any(e => e.Contains("5 minuti", StringComparison.Ordinal)));
+ Assert.IsTrue(errors.Any(e => e.Contains("30 minuti", StringComparison.Ordinal)));
+ Assert.IsTrue(errors.Any(e => e.Contains("20 ore", StringComparison.Ordinal)));
+ Assert.IsTrue(errors.Any(e => e.Contains("storie viste", StringComparison.Ordinal)));
+ Assert.IsTrue(errors.Any(e => e.Contains("dati scaricati", StringComparison.Ordinal)));
+ Assert.HasCount(0, CautionProfileRules.Validate(CautionProfile.Fast));
+ Assert.HasCount(0, CautionProfileRules.Validate(CautionProfile.Prudent));
+ Assert.HasCount(0, CautionProfileRules.Validate(CautionProfile.Balanced));
+ Assert.AreEqual(TimeSpan.FromHours(18), CautionProfileRules.WindowLength(new TimeOnly(6, 30), new TimeOnly(0, 30)));
+ }
+
+ [TestMethod]
+ public async Task InvalidSettingsAreNotStored()
+ {
+ using var folder = new TempFolder("impostazioni");
+ await using var db = await FebeDatabase.OpenAsync(folder.Combine("dati"));
+ var settings = new EngineSettings().WithCustomValues(CautionProfile.Prudent with { PauseMin = TimeSpan.FromMinutes(1) });
+ var error = await Assert.ThrowsAsync(() => EngineSettingsStore.SaveAsync(db.Settings, settings));
+ StringAssert.Contains(error.Message, "pausa minima");
+ Assert.IsNull(await db.Settings.GetAsync(EngineSettingKeys.Profile));
+ }
+
+ [TestMethod]
+ public void TheCustomProfileSurvivesTheJsonRoundTrip()
+ {
+ var custom = CautionProfile.Fast with { Kind = CautionProfileKind.Custom, WindowJitter = TimeSpan.FromMinutes(25), RampUpDays = 10 };
+ var decoded = CautionProfileCodec.TryDecode(CautionProfileCodec.Encode(custom));
+ Assert.IsNotNull(decoded);
+ Assert.AreEqual(custom.WindowJitter, decoded!.WindowJitter);
+ Assert.AreEqual(10, decoded.RampUpDays);
+ foreach (var (kind, budget) in custom.Budgets)
+ {
+ Assert.AreEqual(budget, decoded.Budgets[kind]);
+ }
+
+ Assert.IsNull(CautionProfileCodec.TryDecode("{non è json"));
+ Assert.IsNull(CautionProfileCodec.TryDecode("{}"));
+ }
+}
diff --git a/tests/Febe.Tests/Engine/EngineSimulationTests.cs b/tests/Febe.Tests/Engine/EngineSimulationTests.cs
new file mode 100644
index 0000000..a8bf74b
--- /dev/null
+++ b/tests/Febe.Tests/Engine/EngineSimulationTests.cs
@@ -0,0 +1,174 @@
+using System.Text;
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Simulation;
+using Febe.Core.Storage;
+using Febe.Data;
+using Febe.Tests.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class EngineSimulationTests
+{
+ private static async Task SimulateAsync(SimulationOptions options)
+ {
+ using var folder = new TempFolder("simula");
+ return await EngineSimulation.RunAsync(options, async ct => await FebeDatabase.OpenAsync(folder.Combine("dati"), ct));
+ }
+
+ [TestMethod]
+ [DataRow(CautionProfileKind.Prudent)]
+ [DataRow(CautionProfileKind.Balanced)]
+ [DataRow(CautionProfileKind.Fast)]
+ public async Task EveryProfileRunsAWeekWithoutExceedingAnyBudget(CautionProfileKind profile)
+ {
+ var report = await SimulateAsync(new SimulationOptions { Days = 7, Profile = profile, Seed = 3 });
+
+ Assert.AreEqual(0, report.Overruns, string.Join("\n", report.OverrunDetails));
+ Assert.AreEqual(0, report.OverrunsOfFullBudgets);
+ Assert.AreEqual(0, report.ActionsOutsideWindow);
+ Assert.AreEqual(0, report.PauseFloorViolations);
+ Assert.IsTrue(report.ShortestPause >= CautionProfile.For(profile).PauseMin);
+ Assert.IsTrue(report.SessionStartCv >= 0.35, $"CV {report.SessionStartCv}");
+ Assert.IsTrue(report.SessionsPerDayMean > 5);
+ Assert.IsTrue(report.BackfillStored > 0);
+ Assert.IsTrue(report.FollowedPosts.Count > 0 && report.Stories.Count > 0);
+
+ var text = report.ToText();
+ StringAssert.Contains(text, "Sessioni");
+ StringAssert.Contains(text, "superamenti dei tetti: 0");
+ StringAssert.Contains(text, "Storico di 2.000 post");
+ var csv = report.ToCsv();
+ Assert.HasCount(report.Days.Count + 1, csv.Split('\n', StringSplitOptions.RemoveEmptyEntries));
+ StringAssert.StartsWith(csv, "giorno;sessioni;");
+ }
+
+ [TestMethod]
+ public async Task HeavyDemandSmallDataBudgetAndFrequentThrottlesStillExceedNothing()
+ {
+ var custom = CautionProfile.Prudent with
+ {
+ Kind = CautionProfileKind.Custom,
+ DataPerDayBytes = 150L * 1024 * 1024,
+ Budgets = new Dictionary(CautionProfile.Prudent.Budgets) { [ActionKind.StoryView] = new Budget(10, 40) },
+ };
+ var report = await SimulateAsync(new SimulationOptions
+ {
+ Days = 5,
+ Seed = 11,
+ Settings = new EngineSettings().WithCustomValues(custom),
+ World = new SimulatedWorldOptions
+ {
+ Seed = 11,
+ FollowedAccounts = 15,
+ NotFollowedAccounts = 25,
+ MeanPostsPerDay = 1.5,
+ StoryAccountShare = 1,
+ HistoricalPosts = 3000,
+ ThrottleProbabilityPerAction = 0.004,
+ FrequencyOf = _ => Frequency.High,
+ },
+ });
+
+ Assert.AreEqual(0, report.Overruns, string.Join("\n", report.OverrunDetails));
+ Assert.AreEqual(0, report.ActionsOutsideWindow);
+ Assert.AreEqual(0, report.PauseFloorViolations);
+ Assert.IsNotEmpty(report.Throttles);
+ var data = report.CategoryTotals.Single(c => c.Kind == ActionKind.DataDownload);
+ // Gradual start and throttles halve it: under pressure means near half of the full budget at least.
+ Assert.IsTrue(data.MaxPerDay > data.DailyLimit * 0.45, "The data budget was really under pressure.\n" + report.ToText());
+ Assert.IsTrue(data.MaxPerDay <= data.DailyLimit);
+ var stories = report.CategoryTotals.Single(c => c.Kind == ActionKind.StoryView);
+ Assert.IsTrue(stories.MaxPerDay <= 40);
+ var profiles = report.CategoryTotals.Single(c => c.Kind == ActionKind.ProfileOpen);
+ Assert.IsTrue(profiles.WorstHour >= 6, "The hourly profile budget (halved at first) was reached.");
+ Assert.IsTrue(profiles.WorstHour <= 12 && profiles.MaxPerDay <= 100);
+ }
+
+ [TestMethod]
+ [DataRow(true)]
+ [DataRow(false)]
+ public async Task WithStoriesOnEveryAccountGetsAtLeastThreeStoryChecksADay(bool sweepCoversFollowedStories)
+ {
+ var report = await SimulateAsync(new SimulationOptions
+ {
+ Days = 4,
+ Seed = 5,
+ Engine = EngineOptions.Default with { SweepCoversFollowedStories = sweepCoversFollowedStories },
+ World = new SimulatedWorldOptions
+ {
+ Seed = 5,
+ FollowedAccounts = 3,
+ NotFollowedAccounts = 3,
+ StoryAccountShare = 1,
+ HistoricalPosts = 0,
+ ThrottleProbabilityPerAction = 0,
+ FrequencyOf = i => i % 2 == 0 ? Frequency.Low : Frequency.Normal,
+ },
+ });
+
+ var stats = report.World;
+ foreach (var day in report.Days.Skip(1))
+ {
+ foreach (var account in report.WorldAccounts)
+ {
+ var explicitChecks = stats.StoryChecks.GetValueOrDefault((account.Id, day.Day));
+ var bySweep = account.Followed && sweepCoversFollowedStories ? stats.Sweeps.GetValueOrDefault(day.Day) : 0;
+ Assert.IsTrue(explicitChecks + bySweep >= 3, $"{account.Username} on {day.Day}: {explicitChecks} checks, {bySweep} sweeps");
+ }
+ }
+
+ Assert.AreEqual(0, report.MissedStories);
+ }
+
+ [TestMethod]
+ public async Task TheSameSeedGivesTheSameSimulation()
+ {
+ var first = await SimulateAsync(new SimulationOptions { Days = 2, Seed = 9 });
+ var second = await SimulateAsync(new SimulationOptions { Days = 2, Seed = 9 });
+ Assert.AreEqual(first.SessionCount, second.SessionCount);
+ Assert.AreEqual(first.VirtualEvents, second.VirtualEvents);
+ CollectionAssert.AreEqual(first.Days.Select(d => d.Actions[ActionKind.ProfileOpen]).ToList(), second.Days.Select(d => d.Actions[ActionKind.ProfileOpen]).ToList());
+ }
+
+ [TestMethod]
+ public async Task TheCsvIsUtf8WithBomAndSemicolons()
+ {
+ var report = await SimulateAsync(new SimulationOptions { Days = 1, Seed = 2 });
+ using var folder = new TempFolder("csv");
+ var path = folder.Combine("resoconto.csv");
+ await report.WriteCsvAsync(path);
+ var bytes = await File.ReadAllBytesAsync(path);
+ CollectionAssert.AreEqual(new byte[] { 0xEF, 0xBB, 0xBF }, bytes.Take(3).ToArray());
+ var text = Encoding.UTF8.GetString(bytes, 3, bytes.Length - 3);
+ StringAssert.Contains(text, "minuti di attività");
+ Assert.IsTrue(text.Split('\n')[1].Split(';').Length > 10);
+ }
+
+ [TestMethod]
+ public void TheCommandLineIsParsed()
+ {
+ Assert.IsTrue(Febe.Server.SimulateCommand.TryParse(["--simula", "30g", "--profilo", "equilibrato", "--csv", "x.csv", "--seme", "4"], out var options, out var csv, out _));
+ Assert.AreEqual(30, options.Days);
+ Assert.AreEqual(CautionProfileKind.Balanced, options.Profile);
+ Assert.AreEqual("x.csv", csv);
+ Assert.AreEqual(4, options.Seed);
+ Assert.IsFalse(Febe.Server.SimulateCommand.TryParse(["--simula", "trenta"], out _, out _, out var problem));
+ StringAssert.Contains(problem, "Durata non valida");
+ Assert.IsFalse(Febe.Server.SimulateCommand.TryParse(["--simula", "7g", "--profilo", "spericolato"], out _, out _, out problem));
+ StringAssert.Contains(problem, "Profilo sconosciuto");
+ }
+
+ [TestMethod]
+ public async Task TheCommandPrintsTheItalianReport()
+ {
+ using var output = new StringWriter();
+ using var error = new StringWriter();
+ var code = await Febe.Server.SimulateCommand.RunAsync(["--simula", "1g", "--profilo", "rapido"], output, error);
+ Assert.AreEqual(0, code, error.ToString());
+ StringAssert.Contains(output.ToString(), "profilo «Rapido»");
+ Assert.AreEqual(2, await Febe.Server.SimulateCommand.RunAsync(["--simula", "0g"], output, error));
+ }
+}
diff --git a/tests/Febe.Tests/Engine/GovernorTests.cs b/tests/Febe.Tests/Engine/GovernorTests.cs
new file mode 100644
index 0000000..bb5f05b
--- /dev/null
+++ b/tests/Febe.Tests/Engine/GovernorTests.cs
@@ -0,0 +1,320 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Tests.Engine.Support;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class GovernorTests
+{
+ [TestMethod]
+ public async Task GrantsInsideTheWindowDuringASessionAndRecordsTheAction()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var account = await bed.AddAccountAsync("marta.demo", followed: false);
+ var session = await bed.BeginSessionAsync();
+
+ var permit = await bed.Governor.RequestAsync(ActionKind.ProfileOpen, account.Id, CancellationToken.None);
+
+ Assert.IsTrue(permit.Granted, permit.Message);
+ var logged = await bed.Db.ActionLog.ListAsync(bed.Clock.Now.AddMinutes(-1), bed.Clock.Now.AddMinutes(1));
+ Assert.HasCount(1, logged);
+ Assert.AreEqual(ActionKind.ProfileOpen, logged[0].Category);
+ Assert.AreEqual(account.Id, logged[0].AccountId);
+ Assert.AreEqual(session.SessionId, logged[0].SessionId);
+ Assert.AreEqual(1, session.ActionCount);
+ }
+
+ [TestMethod]
+ public async Task RefusesWithoutASession()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var permit = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
+ Assert.IsFalse(permit.Granted);
+ Assert.AreEqual(DenialReason.NoSession, permit.Reason);
+ Assert.IsFalse(string.IsNullOrWhiteSpace(permit.Message));
+ Assert.HasCount(0, await bed.Db.ActionLog.ListAsync(bed.Clock.Now.AddDays(-1), bed.Clock.Now.AddDays(1)));
+ }
+
+ [TestMethod]
+ public async Task RefusesOutsideTheWindowWithTheNextWindowAsRetryTime()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 3, 0));
+ await bed.BeginSessionAsync();
+
+ var permit = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
+
+ Assert.AreEqual(DenialReason.OutsideActiveWindow, permit.Reason);
+ Assert.IsNotNull(permit.RetryAfter);
+ var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
+ Assert.AreEqual(window!.Start, permit.RetryAfter);
+ StringAssert.Contains(permit.Message!, "verso le");
+ }
+
+ [TestMethod]
+ public async Task TheBreakerIsCheckedFirst()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 3, 0));
+ await bed.Breaker.ReportAsync(new Signal(SignalLevel.Challenge, "challenge-url", "https://sito.prova/challenge", bed.Clock.Now));
+
+ // Outside the window and without a session too: the breaker comes first.
+ var permit = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
+ Assert.AreEqual(DenialReason.BreakerOpen, permit.Reason);
+ StringAssert.Contains(permit.Message!, "verifica");
+ }
+
+ [TestMethod]
+ public async Task PauseAndAlbertoAtTheBrowserRefuse()
+ {
+ var driving = false;
+ await using var bed = await EngineTestBed.CreateAsync(userIsDriving: () => driving);
+ await bed.BeginSessionAsync();
+
+ bed.Runtime.IsPaused = true;
+ Assert.AreEqual(DenialReason.Paused, (await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Reason);
+ bed.Runtime.IsPaused = false;
+ driving = true;
+ Assert.AreEqual(DenialReason.UserIsDriving, (await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Reason);
+ driving = false;
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Granted);
+ }
+
+ [TestMethod]
+ public async Task TheHourlyBudgetIsARolling60MinuteWindow()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ bed.Clock.AutoAdvance = true;
+ await bed.BeginSessionAsync();
+ var first = bed.Clock.Now;
+
+ // «Prudente»: 4 home pages per hour.
+ for (var i = 0; i < 4; i++)
+ {
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Granted);
+ }
+
+ var denied = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
+ Assert.AreEqual(DenialReason.HourlyBudgetReached, denied.Reason);
+ Assert.AreEqual(first + TimeSpan.FromHours(1), denied.RetryAfter);
+ StringAssert.Contains(denied.Message!, "tetto orario");
+
+ // Other categories go on.
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None)).Granted);
+
+ bed.Clock.AdvanceTo(first + TimeSpan.FromHours(1));
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Granted);
+ }
+
+ [TestMethod]
+ public async Task TheDailyBudgetUsesTheLocalCalendarDayAndComesFromTheDatabase()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var account = await bed.AddAccountAsync("luca.demo", followed: false);
+ var morning = EngineTestBed.Local(2026, 10, 14, 8, 0);
+ for (var i = 0; i < 100; i++)
+ {
+ await bed.Db.ActionLog.AppendAsync(new ActionLogRecord { At = morning.AddSeconds(i * 20), Category = ActionKind.ProfileOpen, AccountId = account.Id });
+ }
+
+ // Yesterday's actions do not count today.
+ await bed.Db.ActionLog.AppendAsync(new ActionLogRecord { At = morning.AddDays(-1), Category = ActionKind.StoryView });
+
+ await bed.BeginSessionAsync();
+ var denied = await bed.Governor.RequestAsync(ActionKind.ProfileOpen, account.Id, CancellationToken.None);
+ Assert.AreEqual(DenialReason.DailyBudgetReached, denied.Reason);
+ Assert.IsTrue(denied.RetryAfter >= EngineTestBed.Local(2026, 10, 15, 0, 0));
+ StringAssert.Contains(denied.Message!, "domani");
+
+ var events = await bed.Db.Events.ListAsync(new Febe.Core.Storage.EventQuery());
+ Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.BudgetReached));
+ }
+
+ [TestMethod]
+ [DataRow(GesturePace.Natural, 4000)]
+ [DataRow(GesturePace.Brisk, 3000)]
+ [DataRow(GesturePace.Slow, 5400)]
+ public async Task TheMinimumSpacingIsWaitedAndScaledByThePace(GesturePace pace, int spacingMs)
+ {
+ await using var bed = await EngineTestBed.CreateAsync(settings: new EngineSettings { GradualStart = false, Pace = pace });
+ bed.Clock.AutoAdvance = true;
+ await bed.BeginSessionAsync();
+
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None)).Granted);
+ var evaluation = await bed.Governor.EvaluateAsync(ActionKind.StoryView, null);
+ Assert.AreEqual(DenialReason.MinimumSpacing, evaluation.Reason);
+
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None)).Granted);
+ var log = await bed.Db.ActionLog.ListAsync(bed.Clock.Now.AddHours(-1), bed.Clock.Now.AddSeconds(1));
+ Assert.HasCount(2, log);
+ Assert.AreEqual(TimeSpan.FromMilliseconds(spacingMs), log[1].At - log[0].At);
+ }
+
+ [TestMethod]
+ public async Task TheAccountBackfillLimitCountsPostsDiscoveredToday()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var account = await bed.AddAccountAsync("storico.demo", followed: true, state: AccountState.Backfilling, backfillPerDay: 24);
+ for (var i = 0; i < 24; i++)
+ {
+ await bed.Db.Entries.AddAsync(
+ new Entry { AccountId = account.Id, Kind = EntryKind.Post, InstagramId = "p" + i, PublishedAt = bed.Clock.Now.AddDays(-100 - i), DiscoveredAt = bed.Clock.Now.AddMinutes(-30) },
+ [new Media { Position = 1, Kind = MediaKind.Photo }]);
+ }
+
+ await bed.BeginSessionAsync();
+ var denied = await bed.Governor.RequestAsync(ActionKind.BackfillPage, account.Id, CancellationToken.None);
+ Assert.AreEqual(DenialReason.AccountLimitReached, denied.Reason);
+ StringAssert.Contains(denied.Message!, "@storico.demo");
+
+ // Other categories of the same account are not limited by the backfill limit.
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.ProfileOpen, account.Id, CancellationToken.None)).Granted);
+ }
+
+ [TestMethod]
+ public async Task AccountsThatMustNotBeContactedAreRefused()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var archive = await bed.AddAccountAsync("archivio.demo", followed: false, state: AccountState.ArchiveOnly);
+ var paused = await bed.AddAccountAsync("pausa.demo", followed: false, state: AccountState.Paused);
+ var session = await bed.BeginSessionAsync();
+
+ Assert.AreEqual(DenialReason.AccountNotContactable, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, archive.Id, CancellationToken.None)).Reason);
+ Assert.AreEqual(DenialReason.AccountNotContactable, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, paused.Id, CancellationToken.None)).Reason);
+
+ // «Controlla ora» on a paused account is allowed; on an archive-only one never.
+ session.ManualAccountId = paused.Id;
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.ProfileOpen, paused.Id, CancellationToken.None)).Granted);
+ session.ManualAccountId = archive.Id;
+ bed.Clock.Advance(TimeSpan.FromSeconds(10));
+ Assert.AreEqual(DenialReason.AccountNotContactable, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, archive.Id, CancellationToken.None)).Reason);
+ }
+
+ [TestMethod]
+ public async Task AConfirmedManualCheckOutsideTheWindowAllowsOnlyThatAccount()
+ {
+ await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 2, 0));
+ var asked = await bed.AddAccountAsync("chiesto.demo", followed: false);
+ var other = await bed.AddAccountAsync("altro.demo", followed: false);
+ await bed.BeginSessionAsync(outsideWindowAccountId: asked.Id);
+
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.ProfileOpen, asked.Id, CancellationToken.None)).Granted);
+ bed.Clock.Advance(TimeSpan.FromSeconds(10));
+ Assert.AreEqual(DenialReason.OutsideActiveWindow, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, other.Id, CancellationToken.None)).Reason);
+ Assert.AreEqual(DenialReason.OutsideActiveWindow, (await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Reason);
+ }
+
+ [TestMethod]
+ public void TheGradualStartGoesFromHalfToFullLinearly()
+ {
+ var profile = CautionProfile.Prudent;
+ var start = EngineTestBed.Noon;
+ Assert.AreEqual(0.5, BudgetLimits.GradualStartFactor(profile, start, start), 1e-9);
+ Assert.AreEqual(0.75, BudgetLimits.GradualStartFactor(profile, start, start.AddDays(3.5)), 1e-9);
+ Assert.AreEqual(1.0, BudgetLimits.GradualStartFactor(profile, start, start.AddDays(7)), 1e-9);
+ Assert.AreEqual(1.0, BudgetLimits.GradualStartFactor(profile with { GradualStart = false }, start, start), 1e-9);
+
+ var budgets = BudgetLimits.Compute(profile, start, null, start);
+ Assert.AreEqual(BudgetReduction.GradualStart, budgets.Reduction);
+ Assert.AreEqual(new Budget(6, 50), budgets.Budgets[ActionKind.ProfileOpen]);
+ Assert.AreEqual(2L * 1024 * 1024 * 1024, budgets.DataPerDayBytes);
+ Assert.AreEqual(150, budgets.BackfillPostsPerAccountPerDay);
+ }
+
+ [TestMethod]
+ public void TheStrongestReductionWinsNeverTheProduct()
+ {
+ var profile = CautionProfile.Prudent;
+ var start = EngineTestBed.Noon;
+ var now = start.AddDays(2);
+ var halvedUntil = now.AddHours(10);
+
+ var both = BudgetLimits.Compute(profile, start, halvedUntil, now);
+ Assert.AreEqual(0.5, both.Factor, 1e-9, "Halved (0.5) is stronger than the ramp at day 2 (0.64): 0.5, not 0.32.");
+ Assert.AreEqual(BudgetReduction.HalvedAfterThrottle, both.Reduction);
+ Assert.AreEqual(new Budget(6, 50), both.Budgets[ActionKind.ProfileOpen]);
+
+ var rampOnly = BudgetLimits.Compute(profile, start, halvedUntil, halvedUntil);
+ Assert.AreEqual(0.5 + (0.5 * (2 + (10.0 / 24)) / 7), rampOnly.Factor, 1e-9);
+ Assert.AreEqual(BudgetReduction.GradualStart, rampOnly.Reduction);
+
+ var none = BudgetLimits.Compute(profile, start, halvedUntil, start.AddDays(8));
+ Assert.AreEqual(1, none.Factor);
+ Assert.AreEqual(BudgetReduction.None, none.Reduction);
+ }
+
+ [TestMethod]
+ public async Task HalvedBudgetsApplyAfterAThrottle()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ await bed.Breaker.ReportAsync(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
+ bed.Clock.Advance(TimeSpan.FromHours(1));
+ var budgets = bed.Governor.GetEffectiveBudgets(bed.Clock.Now);
+ Assert.AreEqual(BudgetReduction.HalvedAfterThrottle, budgets.Reduction);
+ Assert.AreEqual(new Budget(2, 15), budgets.Budgets[ActionKind.Home]);
+ bed.Clock.Advance(TimeSpan.FromHours(48));
+ Assert.AreEqual(BudgetReduction.None, bed.Governor.GetEffectiveBudgets(bed.Clock.Now).Reduction);
+ }
+
+ [TestMethod]
+ public async Task TheDataBudgetIsDailyInBytesAndWorksDuringAStop()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ var full = 4L * 1024 * 1024 * 1024;
+ Assert.AreEqual(full, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
+
+ // After a throttle the data budget is halved too.
+ await bed.Breaker.ReportAsync(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
+ Assert.AreEqual(full / 2, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
+ await bed.Governor.RecordAsync((full / 2) - 1000, null, CancellationToken.None);
+ Assert.AreEqual(1000L, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
+
+ // Queued downloads may complete during a stop: the data budget does not look at the breaker.
+ Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.DataDownload, null, CancellationToken.None)).Granted);
+
+ await bed.Governor.RecordAsync(1000, null, CancellationToken.None);
+ var denied = await bed.Governor.RequestAsync(ActionKind.DataDownload, null, CancellationToken.None);
+ Assert.AreEqual(DenialReason.DailyBudgetReached, denied.Reason);
+ Assert.AreEqual(0L, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
+
+ bed.Clock.AdvanceTo(EngineTestBed.Local(2026, 10, 15, 0, 0));
+ Assert.IsTrue(await bed.Governor.RemainingTodayAsync(CancellationToken.None) > 0);
+ }
+
+ [TestMethod]
+ public async Task RemainingSaysHowMuchRoomIsLeft()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ bed.Clock.AutoAdvance = true;
+ await bed.BeginSessionAsync();
+ Assert.AreEqual(50L, await bed.Governor.RemainingAsync(ActionKind.StoryView));
+ for (var i = 0; i < 45; i++)
+ {
+ await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None);
+ }
+
+ Assert.AreEqual(5L, await bed.Governor.RemainingAsync(ActionKind.StoryView), "Not room for ten stories in this hour.");
+ }
+
+ [TestMethod]
+ public async Task BudgetsTurnAmberFrom80Percent()
+ {
+ await using var bed = await EngineTestBed.CreateAsync();
+ bed.Clock.AutoAdvance = true;
+ await bed.BeginSessionAsync();
+ for (var i = 0; i < 3; i++)
+ {
+ await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
+ }
+
+ var statuses = await bed.Governor.GetBudgetStatusAsync();
+ var home = statuses.Single(s => s.Kind == ActionKind.Home);
+ Assert.AreEqual(3L, home.UsedLastHour);
+ Assert.IsFalse(home.IsAmber, "3 of 4 is 75%.");
+ await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
+ home = (await bed.Governor.GetBudgetStatusAsync()).Single(s => s.Kind == ActionKind.Home);
+ Assert.IsTrue(home.IsAmber);
+ Assert.IsTrue(home.HourlyReached);
+ Assert.IsFalse(statuses.Single(s => s.Kind == ActionKind.StoryView).IsAmber);
+ }
+}
diff --git a/tests/Febe.Tests/Engine/Support/BudgetAudit.cs b/tests/Febe.Tests/Engine/Support/BudgetAudit.cs
new file mode 100644
index 0000000..3b03a6d
--- /dev/null
+++ b/tests/Febe.Tests/Engine/Support/BudgetAudit.cs
@@ -0,0 +1,71 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Storage;
+
+namespace Febe.Tests.Engine.Support;
+
+///
+/// Independent check of the budgets from action_log: at every action, the rolling hour and the local day so far
+/// must stay within the profile's full limits (reductions only make them lower).
+///
+internal static class BudgetAudit
+{
+ private static readonly TimeSpan Hour = TimeSpan.FromMinutes(60);
+
+ public static async Task> OverrunsAsync(IFebeStorage storage, CautionProfile profile, TimeZoneInfo zone, DateTimeOffset from, DateTimeOffset to)
+ {
+ var actions = await storage.ActionLog.ListAsync(from, to);
+ var problems = new List();
+ foreach (var kind in Enum.GetValues())
+ {
+ var list = actions.Where(a => a.Category == kind).OrderBy(a => a.At).ThenBy(a => a.Id).ToList();
+ var first = 0;
+ long hour = 0;
+ long day = 0;
+ DateOnly? current = null;
+ foreach (var action in list)
+ {
+ hour += action.Amount;
+ while (list[first].At <= action.At - Hour)
+ {
+ hour -= list[first].Amount;
+ first++;
+ }
+
+ var today = LocalCalendar.Today(action.At, zone);
+ if (today != current)
+ {
+ current = today;
+ day = 0;
+ }
+
+ day += action.Amount;
+ var over = kind == ActionKind.DataDownload
+ ? day > profile.DataPerDayBytes
+ : hour > profile.Budgets[kind].PerHour || day > profile.Budgets[kind].PerDay;
+ if (over)
+ {
+ problems.Add($"{kind} at {action.At:O}: hour {hour}, day {day}");
+ }
+ }
+ }
+
+ return problems;
+ }
+
+ /// Actions (data excluded) that fall outside the active window of their day.
+ public static async Task> OutsideWindowAsync(IFebeStorage storage, DayPlanner planner, DateTimeOffset from, DateTimeOffset to)
+ {
+ var outside = new List();
+ foreach (var action in (await storage.ActionLog.ListAsync(from, to)).Where(a => a.Category != ActionKind.DataDownload))
+ {
+ if (await planner.GetWindowAtAsync(action.At) is null)
+ {
+ outside.Add(action);
+ }
+ }
+
+ return outside;
+ }
+}
diff --git a/tests/Febe.Tests/Engine/Support/EngineTestBed.cs b/tests/Febe.Tests/Engine/Support/EngineTestBed.cs
new file mode 100644
index 0000000..e3236a5
--- /dev/null
+++ b/tests/Febe.Tests/Engine/Support/EngineTestBed.cs
@@ -0,0 +1,172 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Domain;
+using Febe.Core.Engine;
+using Febe.Core.Simulation;
+using Febe.Data;
+using Febe.Tests.Support;
+
+namespace Febe.Tests.Engine.Support;
+
+///
+/// A temporary database, a virtual clock in Rome's zone and the engine services on top, with a fixed seed.
+/// builds new engine objects on the same database, as a restart of the program does.
+///
+internal sealed class EngineTestBed : IAsyncDisposable
+{
+ private readonly TempFolder _folder;
+ private EngineHost? _host;
+ private CancellationTokenSource? _loopCts;
+ private Task? _loop;
+
+ private EngineTestBed(TempFolder folder, FebeDatabase db, VirtualClock clock, EngineServices services, EngineOptions options, int seed)
+ {
+ _folder = folder;
+ Db = db;
+ Clock = clock;
+ Services = services;
+ Options = options;
+ Seed = seed;
+ }
+
+ public static TimeZoneInfo Zone => SimulationZones.Rome;
+
+ /// Wednesday 14 October 2026 at 12:00 in Rome: inside every profile's window whatever the daily shift.
+ public static DateTimeOffset Noon { get; } = Local(2026, 10, 14, 12, 0);
+
+ public FebeDatabase Db { get; }
+
+ public VirtualClock Clock { get; }
+
+ public EngineServices Services { get; private set; }
+
+ public EngineOptions Options { get; }
+
+ public int Seed { get; }
+
+ public Governor Governor => Services.Governor;
+
+ public CircuitBreaker Breaker => Services.Breaker;
+
+ public EngineRuntime Runtime => Services.Runtime;
+
+ public static DateTimeOffset Local(int year, int month, int day, int hour, int minute) =>
+ LocalCalendar.FromLocal(new DateTime(year, month, day, hour, minute, 0), Zone);
+
+ /// A bed with the given profile; the gradual start is off unless asked, so budgets are the profile's.
+ public static async Task CreateAsync(
+ DateTimeOffset? start = null,
+ CautionProfileKind profile = CautionProfileKind.Prudent,
+ bool gradualStart = false,
+ int seed = 7,
+ EngineOptions? options = null,
+ EngineSettings? settings = null,
+ Func? userIsDriving = null,
+ Func? isConnected = null)
+ {
+ var folder = new TempFolder("motore");
+ var db = await FebeDatabase.OpenAsync(folder.Combine("dati"));
+ var clock = new VirtualClock(start ?? Noon, Zone);
+ settings ??= new EngineSettings { ProfileKind = profile, GradualStart = gradualStart };
+ await EngineSettingsStore.SaveAsync(db.Settings, settings);
+ options ??= EngineOptions.Default;
+ var services = await EngineServices.CreateAsync(db, clock, new SeededRandom(seed), options, userIsDriving, isConnected);
+ return new EngineTestBed(folder, db, clock, services, options, seed);
+ }
+
+ /// New engine objects on the same database (a restart), with a different random stream.
+ public async Task ReopenAsync(int seed, Func? userIsDriving = null)
+ {
+ await StopAsync();
+ Services = await EngineServices.CreateAsync(Db, Clock, new SeededRandom(seed), Options, userIsDriving);
+ return Services;
+ }
+
+ public async Task AddAccountAsync(
+ string username,
+ bool followed,
+ Frequency frequency = Frequency.Normal,
+ AccountState state = AccountState.UpToDate,
+ ContentTypes? types = null,
+ int? postCount = null,
+ int? backfillPerDay = null)
+ {
+ var account = Account.Create(username, StartingPoint.EverythingAndKeepUpdated, Clock.Now, Zone, Runtime.Profile) with
+ {
+ InstagramId = "77" + ((uint)username.GetHashCode(StringComparison.Ordinal)).ToString(System.Globalization.CultureInfo.InvariantCulture),
+ IsFollowed = followed,
+ Frequency = frequency,
+ State = state,
+ BackfillCompletedAt = state == AccountState.Backfilling ? null : Clock.Now,
+ PostCount = postCount,
+ };
+ if (types is { } t)
+ {
+ account = account with { ContentTypes = t };
+ }
+
+ if (backfillPerDay is { } perDay)
+ {
+ account = account with { Limits = account.Limits with { BackfillPostsPerDay = perDay } };
+ }
+
+ return await Db.Accounts.AddAsync(account);
+ }
+
+ /// A session as the engine opens it, for testing the Governor alone.
+ public async Task BeginSessionAsync(long? outsideWindowAccountId = null)
+ {
+ var record = await Db.Sessions.StartAsync(Clock.Now);
+ var session = new SessionContext(record.Id, 1, Clock.Now, Clock.Now + TimeSpan.FromMinutes(10), outsideWindowAccountId);
+ Runtime.CurrentSession = session;
+ return session;
+ }
+
+ /// Starts the engine loop on the virtual clock (no time passes until ).
+ public EngineHost Start(IRecipeRunner runner)
+ {
+ _host = new EngineHost(Services, runner);
+ _loopCts = new CancellationTokenSource();
+ _loop = _host.RunAsync(_loopCts.Token);
+ return _host;
+ }
+
+ public EngineHost Host => _host ?? throw new InvalidOperationException("Engine not started.");
+
+ /// Advances virtual time to , letting the engine run.
+ public Task RunUntilAsync(DateTimeOffset target) =>
+ _loop is null ? Task.Run(() => Clock.AdvanceTo(target)) : Clock.RunUntilAsync(target, CancellationToken.None, _loop);
+
+ public Task RunForAsync(TimeSpan span) => RunUntilAsync(Clock.Now + span);
+
+ /// Stops the loop as a shutdown would (a session in progress ends interrupted).
+ public async Task StopAsync()
+ {
+ if (_loop is null)
+ {
+ return;
+ }
+
+ await _loopCts!.CancelAsync();
+ try
+ {
+ await _loop;
+ }
+ catch (OperationCanceledException)
+ {
+ }
+
+ await _host!.DisposeAsync();
+ _loopCts.Dispose();
+ _loop = null;
+ _loopCts = null;
+ _host = null;
+ await Breaker.FlushAsync();
+ }
+
+ public async ValueTask DisposeAsync()
+ {
+ await StopAsync();
+ await Db.DisposeAsync();
+ _folder.Dispose();
+ }
+}
diff --git a/tests/Febe.Tests/Engine/Support/ScriptedRunner.cs b/tests/Febe.Tests/Engine/Support/ScriptedRunner.cs
new file mode 100644
index 0000000..43f620a
--- /dev/null
+++ b/tests/Febe.Tests/Engine/Support/ScriptedRunner.cs
@@ -0,0 +1,101 @@
+using Febe.Core.Abstractions;
+using Febe.Core.Engine;
+
+namespace Febe.Tests.Engine.Support;
+
+/// A recipe run seen by .
+internal sealed record RunRecord(DateTimeOffset At, RecipeRequest Request, long SessionId, RecipeStatus Status);
+
+///
+/// A recipe runner for engine tests: asks the Governor for one counted action like the real recipes (stories:
+/// none, as if no story was active), spends a little virtual time and completes, unless says
+/// otherwise. Records every run.
+///
+internal sealed class ScriptedRunner(IGovernor governor, IClock clock) : IRecipeRunner
+{
+ private readonly Lock _gate = new();
+ private readonly List _runs = [];
+
+ /// Forced outcome for a request (null: default behaviour). Runs before the Governor is asked.
+ public Func? Script { get; set; }
+
+ /// Called after the counted action was granted (e.g. to report a signal).
+ public Action? AfterGrant { get; set; }
+
+ /// Accounts the stories bar flags in every sweep.
+ public IReadOnlyList FlaggedStories { get; set; } = [];
+
+ public int Rests { get; private set; }
+
+ public IReadOnlyList Runs
+ {
+ get
+ {
+ lock (_gate)
+ {
+ return [.. _runs];
+ }
+ }
+ }
+
+ public async Task RunAsync(RecipeRequest request, ISessionContext session, CancellationToken ct)
+ {
+ RecipeOutcome outcome;
+ try
+ {
+ outcome = Script?.Invoke(request) ?? await DefaultAsync(request, ct);
+ }
+ catch (OperationCanceledException)
+ {
+ lock (_gate)
+ {
+ _runs.Add(new RunRecord(clock.Now, request, session.SessionId, RecipeStatus.Cancelled));
+ }
+
+ throw;
+ }
+
+ lock (_gate)
+ {
+ _runs.Add(new RunRecord(clock.Now, request, session.SessionId, outcome.Status));
+ }
+
+ return outcome;
+ }
+
+ public Task RestAsync(CancellationToken ct)
+ {
+ Rests++;
+ return Task.CompletedTask;
+ }
+
+ private async Task DefaultAsync(RecipeRequest request, CancellationToken ct)
+ {
+ if (request.Kind == RecipeKind.AccountStories)
+ {
+ await clock.Delay(TimeSpan.FromSeconds(2), ct);
+ return new RecipeOutcome(RecipeStatus.Completed, 0, 0);
+ }
+
+ var kind = CheckPolicy.CategoryOf(request.Kind);
+ var pages = request.Kind == RecipeKind.Backfill ? Math.Max(1, request.MaxPages ?? 1) : 1;
+ var counted = 0;
+ for (var i = 0; i < pages; i++)
+ {
+ var permit = await governor.RequestAsync(kind, request.AccountId, ct);
+ if (!permit.Granted)
+ {
+ return new RecipeOutcome(counted > 0 ? RecipeStatus.Completed : RecipeStatus.Denied, counted, 0);
+ }
+
+ counted++;
+ AfterGrant?.Invoke(request);
+ await clock.Delay(TimeSpan.FromSeconds(5), ct);
+ }
+
+ return new RecipeOutcome(RecipeStatus.Completed, counted, 0)
+ {
+ AccountsWithStories = request.Kind == RecipeKind.FollowingSweep ? FlaggedStories : [],
+ };
+ }
+}
diff --git a/tests/Febe.Tests/Engine/VirtualClockTests.cs b/tests/Febe.Tests/Engine/VirtualClockTests.cs
new file mode 100644
index 0000000..dcf1512
--- /dev/null
+++ b/tests/Febe.Tests/Engine/VirtualClockTests.cs
@@ -0,0 +1,93 @@
+using Febe.Core.Simulation;
+
+namespace Febe.Tests.Engine;
+
+[TestClass]
+public sealed class VirtualClockTests
+{
+ private static readonly DateTimeOffset Start = new(2026, 10, 14, 10, 0, 0, TimeSpan.Zero);
+
+ [TestMethod]
+ public async Task DelaysCompleteOnlyWhenTimeReachesThem()
+ {
+ var clock = new VirtualClock(Start);
+ var late = clock.Delay(TimeSpan.FromMinutes(10), CancellationToken.None);
+ var early = clock.Delay(TimeSpan.FromMinutes(5), CancellationToken.None);
+ Assert.AreEqual(2, clock.PendingTimers);
+ Assert.IsFalse(early.IsCompleted);
+
+ clock.Advance(TimeSpan.FromMinutes(6));
+ await early;
+ Assert.IsFalse(late.IsCompleted);
+ Assert.AreEqual(Start.AddMinutes(6), clock.Now);
+
+ clock.Advance(TimeSpan.FromMinutes(10));
+ await late;
+ Assert.AreEqual(0, clock.PendingTimers);
+ }
+
+ [TestMethod]
+ public async Task ACancelledDelayLeavesTheQueue()
+ {
+ var clock = new VirtualClock(Start);
+ using var cts = new CancellationTokenSource();
+ var delay = clock.Delay(TimeSpan.FromHours(1), cts.Token);
+ Assert.AreEqual(1, clock.PendingTimers);
+ await cts.CancelAsync();
+ Assert.AreEqual(0, clock.PendingTimers);
+ await Assert.ThrowsAsync(() => delay);
+ }
+
+ [TestMethod]
+ public async Task RunUntilJumpsFromTimerToTimerWhileTheActorWaits()
+ {
+ var clock = new VirtualClock(Start);
+ var seen = new List();
+ using var cts = new CancellationTokenSource();
+ async Task Actor()
+ {
+ for (var i = 0; i < 5; i++)
+ {
+ await Task.Yield();
+ await clock.Delay(TimeSpan.FromMinutes(30), cts.Token);
+ seen.Add(clock.Now);
+ }
+
+ await clock.Delay(TimeSpan.FromDays(10), cts.Token);
+ }
+
+ var actor = Actor();
+ await clock.RunUntilAsync(Start.AddHours(2), CancellationToken.None, actor);
+ Assert.AreEqual(Start.AddHours(2), clock.Now);
+ CollectionAssert.AreEqual(new[] { Start.AddMinutes(30), Start.AddMinutes(60), Start.AddMinutes(90), Start.AddMinutes(120) }, seen);
+
+ await clock.RunUntilAsync(Start.AddHours(3), CancellationToken.None, actor);
+ Assert.HasCount(5, seen);
+ await cts.CancelAsync();
+ await Assert.ThrowsAsync(() => actor);
+ }
+
+ [TestMethod]
+ public async Task AFailingActorStopsTheRun()
+ {
+ var clock = new VirtualClock(Start);
+ async Task Actor()
+ {
+ await clock.Delay(TimeSpan.FromMinutes(1), CancellationToken.None);
+ throw new InvalidOperationException("guasto");
+ }
+
+ var actor = Actor();
+ await Assert.ThrowsAsync(() => clock.RunUntilAsync(Start.AddHours(1), CancellationToken.None, actor));
+ }
+
+ [TestMethod]
+ public async Task AutoAdvanceMovesTimeAtOnceAndRoundsToMilliseconds()
+ {
+ var clock = new VirtualClock(Start) { AutoAdvance = true };
+ await clock.Delay(TimeSpan.FromTicks(1), CancellationToken.None);
+ Assert.AreEqual(Start.AddMilliseconds(1), clock.Now);
+ await clock.Delay(TimeSpan.FromSeconds(4), CancellationToken.None);
+ Assert.AreEqual(Start.AddMilliseconds(4001), clock.Now);
+ }
+}