heybash-xdpool 1.0.5 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.ts CHANGED
@@ -572,8 +572,17 @@ export declare class WorkBuddyUpstreamClient {
572
572
  * list is missing half its entries for the rest of the session".
573
573
  */
574
574
  private fetchModelsOnce;
575
- /** Read-only credits query, aggregated by package. Does not consume credits. */
576
- fetchCredits(credential: WorkBuddyCredential): Promise<WorkBuddyCredits>;
575
+ /**
576
+ * Read-only credits query, aggregated by package. Does not consume credits.
577
+ *
578
+ * `signal` is the caller's cancellation, merged with the built-in timeout
579
+ * rather than replacing it: the pool's background warm must give up when the
580
+ * host shuts down, and a caller that has already gone away must not leave a
581
+ * 30 s request running. `AbortSignal.any` is already the repo's way of
582
+ * combining these (see the pricing probe in the shim), and the timeout stays
583
+ * in force so a signal-less caller keeps the old behaviour exactly.
584
+ */
585
+ fetchCredits(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<WorkBuddyCredits>;
577
586
  /** Query today's check-in status without changing account state. */
578
587
  fetchCheckinStatus(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinStatus>;
579
588
  /** Claim today's check-in reward. The browser route guards this mutation. */
@@ -835,6 +844,41 @@ interface TokenRefresher {
835
844
  domain?: string;
836
845
  }>;
837
846
  }
847
+ /**
848
+ * Minimal billing surface the pool needs to fill `creditExpiry` itself.
849
+ *
850
+ * Declared here for the same reason as {@link TokenRefresher}: the pool knows
851
+ * about accounts, not about HTTP, and importing `WorkBuddyUpstreamClient` would
852
+ * make the two modules circular. `fetchCredits` is OPTIONAL so every existing
853
+ * `TokenRefresher` — the test stubs, and any host that only wired token refresh
854
+ * — keeps working untouched; a client without it simply warms nothing.
855
+ */
856
+ interface CreditReader {
857
+ fetchCredits(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<{
858
+ total: number;
859
+ /** Absent (or undefined) when no one-off pack has a deadline. */
860
+ nearestExpiryMs?: number | undefined;
861
+ }>;
862
+ }
863
+ /**
864
+ * What the pool knows about one account's one-off pack deadlines.
865
+ *
866
+ * The three `state`s are the whole point of the B+ fix: "never asked", "asked,
867
+ * nothing has a deadline" and "asked, here is the deadline" need different
868
+ * handling, and collapsing them into one absent-key predicate is what made a
869
+ * pure monthly-pack account be re-read forever (S1 in
870
+ * `EXPIRY-ADVERSARIAL-20261111.md`). `stale` is orthogonal: the reading is real
871
+ * but older than {@link EXPIRY_READING_TTL_MS}, so it describes the past.
872
+ */
873
+ interface ExpiryReading {
874
+ state: 'unread' | 'none' | 'at';
875
+ /** Deadline, epoch ms; present exactly when `state === 'at'`. */
876
+ at?: number;
877
+ /** When this reading was written, epoch ms; absent for `unread`. */
878
+ readAtMs?: number;
879
+ /** True when the reading is older than {@link EXPIRY_READING_TTL_MS}. */
880
+ stale: boolean;
881
+ }
838
882
  /** Live auth file name the WorkBuddy desktop app writes. */
839
883
  export declare const WORKBUDDY_LIVE_FILENAME = "workbuddy-desktop.info";
840
884
  /** Snapshot files left behind by previous logins share this prefix. */
@@ -963,9 +1007,16 @@ interface AccountPoolOptions {
963
1007
  */
964
1008
  credentialDeadCooldownMs?: number;
965
1009
  /** Upstream client used to refresh near-expiry tokens. */
966
- client?: TokenRefresher;
1010
+ client?: TokenRefresher & Partial<CreditReader>;
967
1011
  /** Refresh this long before actual expiry; default five minutes. */
968
1012
  refreshMarginMs?: number;
1013
+ /**
1014
+ * How long a credit-pack deadline reading is trusted, in ms.
1015
+ *
1016
+ * Defaults to {@link EXPIRY_READING_TTL_MS}; overridable so a test can age a
1017
+ * reading without sleeping for an hour.
1018
+ */
1019
+ expiryReadingTtlMs?: number;
969
1020
  /**
970
1021
  * How requests are spread across the pool.
971
1022
  *
@@ -1017,6 +1068,7 @@ export declare class WorkBuddyAccountPool {
1017
1068
  private credentialDeadCooldownMs;
1018
1069
  private readonly client;
1019
1070
  private readonly refreshMarginMs;
1071
+ private readonly expiryReadingTtlMs;
1020
1072
  private accounts;
1021
1073
  /**
1022
1074
  * Files the last scan could not read, with the reason.
@@ -1112,10 +1164,41 @@ export declare class WorkBuddyAccountPool {
1112
1164
  * their own cycle and are therefore never urgent — which is why this is
1113
1165
  * written from the same `fetchCredits` reading that fills `creditBalances`.
1114
1166
  *
1115
- * An absent entry means "never probed, or nothing is about to expire". Both
1116
- * are the same thing to `expiry` mode: not urgent, so it sorts last.
1167
+ * A positive value is a deadline. The two other states are kept in
1168
+ * {@link creditExpiryNone} and {@link creditExpiryReadAt} rather than as a
1169
+ * missing key, because a missing key cannot tell "we never looked" from "we
1170
+ * looked and nothing has a deadline" — and only the first is worth reading
1171
+ * again. An account whose packs are all monthly reads as `none` forever, which
1172
+ * is exactly right: asking again cannot change the answer (S1).
1117
1173
  */
1118
1174
  private creditExpiry;
1175
+ /**
1176
+ * Accounts whose last reading found NO one-off deadline (all monthly packs, or
1177
+ * none at all). Written instead of deleting the key, so the account stops
1178
+ * being a candidate for re-reading.
1179
+ */
1180
+ private creditExpiryNone;
1181
+ /** When each account's deadline reading was taken, epoch ms. */
1182
+ private creditExpiryReadAt;
1183
+ /**
1184
+ * Accounts whose deadline reading is being fetched right now.
1185
+ *
1186
+ * Same de-duplication idea as {@link refreshInflight}, for the same reason: a
1187
+ * scan-triggered warm and a request-triggered top-up must not both spend a
1188
+ * billing round trip on the same account. A Set rather than a Map of promises
1189
+ * because no caller ever awaits the warm — the point is only that a second
1190
+ * pass skips it.
1191
+ */
1192
+ private expiryWarmInflight;
1193
+ /**
1194
+ * Last time the pool tried to warm an account's deadline reading, epoch ms.
1195
+ *
1196
+ * The TTL is the success gate, not a retry gate: a failed read writes nothing,
1197
+ * so without this a permanently failing billing endpoint would be hit on every
1198
+ * scan and every served request. One attempt per account per minute is cheap
1199
+ * and still recovers quickly from a transient failure.
1200
+ */
1201
+ private expiryWarmAttemptAt;
1119
1202
  /**
1120
1203
  * Last time each account served a request, epoch ms. Drives the idle term
1121
1204
  * of the priority-mode weighting below: an account that just served loses to
@@ -1210,6 +1293,47 @@ export declare class WorkBuddyAccountPool {
1210
1293
  private pruneExpiredSnapshots;
1211
1294
  /** Rescan the auth directories and merge newly discovered accounts. */
1212
1295
  scan(): Promise<WorkBuddyAccount[]>;
1296
+ /**
1297
+ * Warm the deadline readings that `expiry` mode sorts on.
1298
+ *
1299
+ * Fire-and-forget on purpose, from `scan()`: the pool's first request arrives
1300
+ * before any reading exists, and the honest answer to that is the documented
1301
+ * fallback plus a log line, not a stalled request. Everything about the call
1302
+ * is chosen to be unable to make things worse:
1303
+ *
1304
+ * - `this.client` may not exist (a host that wired only token refresh), in
1305
+ * which case there is nothing to read with and the pass is a no-op — the
1306
+ * same guard `ensureFresh` uses;
1307
+ * - a dead sign-in is skipped, and a successful read NEVER calls
1308
+ * `clearCredentialDead`. That is the difference between this and
1309
+ * `reviveBenched`: the billing endpoint answers 200 for a banned account
1310
+ * (observed on 11140), so treating a read as proof of health is what got a
1311
+ * banned account revived six times in a day (S2). Only a token refresh or a
1312
+ * fresh sign-in may clear that mark;
1313
+ * - accounts whose reading is fresh enough are skipped, and so are accounts
1314
+ * already being read (S10's de-duplication, mirroring `refreshInflight`);
1315
+ * - a failed read writes nothing and only warns, so the next pass tries
1316
+ * again without the failure being mistaken for a reading.
1317
+ */
1318
+ private warmExpiryReadings;
1319
+ /** One account's warm read; see {@link warmExpiryReadings} for the rules. */
1320
+ private warmOneExpiryReading;
1321
+ /**
1322
+ * Top up one account's deadline reading, from wherever the pool notices it is
1323
+ * missing or stale.
1324
+ *
1325
+ * The request path is the second caller (after `scan()`), because a reading
1326
+ * ages out while the pool is busy too: the shim calls this for the account that
1327
+ * just served a request, which is the one whose spend is most likely to have
1328
+ * moved its deadline. No timer is created — the existing balance refresh is
1329
+ * already the natural heartbeat, and this rides on it.
1330
+ *
1331
+ * Every gate lives here rather than in the callers, so both paths obey exactly
1332
+ * the same rules: no client, no account, a rejected sign-in, an already-running
1333
+ * read, a finished "nothing expires" answer, a fresh reading, or an attempt
1334
+ * made within the last minute all mean "do nothing".
1335
+ */
1336
+ warmExpiryReadingFor(accountId: string): void;
1213
1337
  /** All accounts, cooldown state included. */
1214
1338
  list(region?: WorkBuddyRegion): readonly WorkBuddyAccount[];
1215
1339
  /**
@@ -1331,6 +1455,14 @@ export declare class WorkBuddyAccountPool {
1331
1455
  * A pool where nobody has a known expiry therefore behaves exactly like
1332
1456
  * priority, which is the honest degradation: without a reading there is
1333
1457
  * nothing to sort by.
1458
+ *
1459
+ * What this method must NOT do is pretend. With only SOME readings in hand it
1460
+ * still has to fall back to `pool[0]`, because picking the earliest of the
1461
+ * accounts that happen to have answered would silently drop the account that
1462
+ * really dies first — the failure mode S0 in `EXPIRY-ADVERSARIAL-20261111.md`
1463
+ * called "worse than not fixing it", since the pick looks plausible and is
1464
+ * wrong. So the incomplete case is announced instead: the caller keeps the old
1465
+ * semantics and the log says which accounts were not read.
1334
1466
  */
1335
1467
  private pickByExpiry;
1336
1468
  /**
@@ -1423,10 +1555,50 @@ export declare class WorkBuddyAccountPool {
1423
1555
  * merged: a pack that has been spent or has died disappears from the next
1424
1556
  * reading, and keeping the stale deadline would pin the pool to an account
1425
1557
  * whose credits are already gone — the opposite of what `expiry` mode wants.
1558
+ *
1559
+ * "Nothing expires" is a real answer, not the absence of one: it is stored as
1560
+ * {@link creditExpiryNone} so the account is not read again on every pass.
1426
1561
  */
1427
1562
  noteCredits(accountId: string, balance: number, nearestExpiryMs?: number): void;
1563
+ /**
1564
+ * Record ONLY the deadline, never the balance.
1565
+ *
1566
+ * The scan-triggered warm exists to fill `expiry` mode's sort key. Writing the
1567
+ * balance as a side effect would change what the reserve floor decides — an
1568
+ * account could be pulled out of rotation by a background read the user never
1569
+ * asked for, which is a behaviour change outside this fix's scope (S7 in
1570
+ * `EXPIRY-ADVERSARIAL-20261111.md`; the reserve's own cold-start hole is V4,
1571
+ * fixed separately).
1572
+ */
1573
+ noteExpiryOnly(accountId: string, nearestExpiryMs?: number): void;
1574
+ /**
1575
+ * The three-state writer both entry points funnel through.
1576
+ *
1577
+ * One place, so the invariant "a finished reading always leaves a state" can be
1578
+ * read off a single function: either a deadline is stored, or the account joins
1579
+ * `creditExpiryNone`. Nothing here deletes the read stamp — that is what makes
1580
+ * "read, found nothing" distinguishable from "never read".
1581
+ */
1582
+ private noteExpiryReading;
1428
1583
  /** Nearest one-off pack expiry for one account, or undefined when none known. */
1429
1584
  creditExpiryOf(accountId: string): number | undefined;
1585
+ /**
1586
+ * The full three-state reading for one account, including staleness.
1587
+ *
1588
+ * `stale` is evaluated against {@link EXPIRY_READING_TTL_MS} here rather than
1589
+ * baked into the stored value, so the TTL stays a constant of the policy and
1590
+ * not of the data.
1591
+ *
1592
+ * Only a real deadline can go stale. "We never asked" is not a reading, and
1593
+ * "nothing here has a deadline" does not become less true with age: a monthly
1594
+ * pack does not grow an expiry date by waiting. Keeping `none` permanently
1595
+ * valid is what makes the S1 loop impossible — an account that answered once
1596
+ * is never read again by the expiry machinery, so there is no predicate that
1597
+ * can stay true forever and re-read it on every pass. If such an account does
1598
+ * gain a one-off pack later, the card refresh (which writes through
1599
+ * `noteCredits` on every poll) is what notices.
1600
+ */
1601
+ expiryReadingOf(accountId: string, now?: number): ExpiryReading;
1430
1602
  /** Last known balance for one account, or undefined when never read. */
1431
1603
  creditsOf(accountId: string): number | undefined;
1432
1604
  /** The credit floor the user set for one account; 0 when unset. */
@@ -3664,6 +3836,17 @@ export declare class WorkBuddyScheduler {
3664
3836
  private travelHours;
3665
3837
  private compensationHours;
3666
3838
  private timer;
3839
+ /** The one-shot kick scheduled just after `start`; cleared by `stop`. */
3840
+ private settleTimer;
3841
+ /**
3842
+ * Deadline for the start-of-day window described in {@link dueSlot}.
3843
+ *
3844
+ * Zero until {@link start} sets it, so a manual `tick` before the loop starts
3845
+ * keeps the original "only past hours" behaviour.
3846
+ */
3847
+ private startupCatchUpUntilMs;
3848
+ /** A startup pass is extra work; it never spends a future scheduled slot. */
3849
+ private readonly startupCompleted;
3667
3850
  private running;
3668
3851
  /** Guards against a slow run overlapping the next tick. */
3669
3852
  private busy;
@@ -3798,6 +3981,8 @@ export declare class WorkBuddyScheduler {
3798
3981
  * PASSED and its slot is still unconsumed, so a laptop that slept through
3799
3982
  * 10:00 still runs the job when it wakes, on the same day.
3800
3983
  *
3984
+ * Startup runs are handled separately in tick and do not spend a future slot.
3985
+ *
3801
3986
  * The EARLIEST unconsumed candidate wins, which is what keeps a two-hour job
3802
3987
  * (`travelHours: [9, 21]`) whole: consuming the earliest due slot leaves the
3803
3988
  * later one for its own hour.