dexbot 1.6.8 → 1.6.9

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.
Files changed (37) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/claw/package.json +1 -1
  3. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  4. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  5. package/dist/dexbot.js +44 -21
  6. package/dist/market_adapter/core/market_adapter_service.d.ts +81 -1
  7. package/dist/market_adapter/core/market_adapter_service.js +225 -18
  8. package/dist/market_adapter/core/signals/hurst_analyzer.d.ts +10 -1
  9. package/dist/market_adapter/core/signals/hurst_analyzer.js +40 -18
  10. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.d.ts +26 -2
  11. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.js +132 -29
  12. package/dist/market_adapter/core/strategies/regime_gate.d.ts +61 -3
  13. package/dist/market_adapter/core/strategies/regime_gate.js +207 -7
  14. package/dist/market_adapter/interval_utils.d.ts +18 -1
  15. package/dist/market_adapter/interval_utils.js +31 -1
  16. package/dist/market_adapter/market_adapter.d.ts +151 -2
  17. package/dist/market_adapter/market_adapter.js +378 -62
  18. package/dist/market_adapter/test_helpers.d.ts +2 -2
  19. package/dist/market_adapter/test_helpers.js +2 -2
  20. package/dist/market_adapter/utils/file_json_cache.d.ts +29 -0
  21. package/dist/market_adapter/utils/file_json_cache.js +106 -0
  22. package/dist/modules/config.d.ts +6 -0
  23. package/dist/modules/config.js +1 -0
  24. package/dist/modules/constants.d.ts +5 -1
  25. package/dist/modules/constants.js +41 -14
  26. package/dist/modules/order/grid.js +95 -25
  27. package/dist/modules/version_notice.d.ts +166 -20
  28. package/dist/modules/version_notice.js +401 -56
  29. package/dist/pm2.js +9 -2
  30. package/dist/unlock.js +7 -7
  31. package/docs/DEXBOT_COMPARISON.md +3 -3
  32. package/docs/EVOLUTION.md +13 -12
  33. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  34. package/docs/GRID_RECALCULATION.md +6 -2
  35. package/docs/README.md +2 -2
  36. package/market_adapter/README.md +28 -0
  37. package/package.json +1 -1
@@ -0,0 +1,106 @@
1
+ 'use strict';
2
+ import { getStorage } from '../../modules/storage/index.js';
3
+ /**
4
+ * market_adapter/utils/file_json_cache.ts — write-through JSON read cache
5
+ *
6
+ * The hourly cycle re-read every bot's candle file (6 x ~250 KiB) before writing
7
+ * it straight back, which cost ~1.4 ms of JSON.parse per file per cycle for data
8
+ * this process had just serialized itself. Nothing else normally writes those
9
+ * files, but "normally" is not "never" (a gap-repair run, ama_signal_runner or
10
+ * the clear script can), so the cache never trusts process-local state blindly:
11
+ *
12
+ * - Entries exist only for files THIS process wrote (`noteJsonWritten`), so
13
+ * the cached value is known to be what was just serialized to disk.
14
+ * - A cached entry is served only while the file's mtime still matches the
15
+ * stamp taken right after that write, and its size still matches wherever
16
+ * the storage adapter reports one. Any other writer invalidates it. (The
17
+ * browser storage adapter's stat() has no size, so in a browser bundle this
18
+ * degrades to mtime-only; the cache is only wired into the Node runtime.)
19
+ * - A served entry is consumed (deleted). A cycle that reads the file, mutates
20
+ * the object and then fails before writing therefore cannot poison the next
21
+ * cycle: the entry is already gone, and the next read re-parses.
22
+ * - When the file cannot be stat'ed (missing, no storage adapter, or a test
23
+ * injecting its own loader) nothing is cached and the loader always runs.
24
+ *
25
+ * Net effect for the hourly loop: the parse this process would have paid to read
26
+ * back its own previous output disappears, with no path to stale data.
27
+ */
28
+ // Resolved per call, not at import time, so a later setAdapter() (DI in tests, a
29
+ // different bundle entry point) is honoured instead of silently ignored.
30
+ function statOf(filePath) {
31
+ try {
32
+ const st = getStorage().stat(filePath);
33
+ if (!st || !Number.isFinite(st.mtimeMs))
34
+ return null;
35
+ return { mtimeMs: st.mtimeMs, size: Number(st.size) || 0 };
36
+ }
37
+ catch (_) {
38
+ return null;
39
+ }
40
+ }
41
+ // Bounded: one entry per candle file the process has written. 32 covers far more
42
+ // bots than any deployment runs, and each entry is a few hundred KB at most.
43
+ const CACHE_LIMIT = 32;
44
+ const _cache = new Map();
45
+ function _store(filePath, entry) {
46
+ _cache.delete(filePath);
47
+ _cache.set(filePath, entry);
48
+ while (_cache.size > CACHE_LIMIT) {
49
+ const oldest = _cache.keys().next();
50
+ if (oldest.done)
51
+ break;
52
+ _cache.delete(oldest.value);
53
+ }
54
+ }
55
+ /**
56
+ * Read and parse a JSON file through `loader`, reusing the value this process
57
+ * wrote earlier only while the file is provably unchanged. The entry is
58
+ * consumed on use, so at most one cycle benefits from any single write.
59
+ */
60
+ function readCachedJson(filePath, loader) {
61
+ const stamp = statOf(filePath);
62
+ if (!stamp) {
63
+ // Cannot validate -> never serve, and forget anything we had.
64
+ _cache.delete(filePath);
65
+ return loader();
66
+ }
67
+ const hit = _cache.get(filePath);
68
+ if (hit && hit.mtimeMs === stamp.mtimeMs && hit.size === stamp.size) {
69
+ _cache.delete(filePath);
70
+ return hit.value;
71
+ }
72
+ _cache.delete(filePath);
73
+ return loader();
74
+ }
75
+ /**
76
+ * Record that `filePath` now holds exactly `value` on disk, so the next read can
77
+ * skip the parse. Call this right after writing.
78
+ *
79
+ * CONTRACT: `value` is held by reference and there is no copy. The caller must
80
+ * not mutate it afterwards (and must not hand the same object to anything else
81
+ * that will), otherwise the cache would serve something that no longer matches
82
+ * the file. The current call site serializes `value` and then never touches it
83
+ * again, so it satisfies this.
84
+ *
85
+ * KNOWN RACE (accepted): the stamp is taken after the write, so another writer
86
+ * landing between our write and our stat() would make this entry carry its
87
+ * stamp with our value, and a later read could serve that stale payload. The
88
+ * window is sub-millisecond and the adapter is the only writer of these files
89
+ * in-process, so this is not worth a hash of a 250 KiB payload; a genuine
90
+ * cross-process writer is far better served by the mtime check failing on its
91
+ * own write than by a cache that guesses.
92
+ */
93
+ function noteJsonWritten(filePath, value) {
94
+ const stamp = statOf(filePath);
95
+ if (!stamp) {
96
+ _cache.delete(filePath);
97
+ return;
98
+ }
99
+ _store(filePath, { mtimeMs: stamp.mtimeMs, size: stamp.size, value });
100
+ }
101
+ /** Drop every cached entry (config reload, tests, explicit cache busting). */
102
+ function clearJsonCache() {
103
+ _cache.clear();
104
+ }
105
+ export { readCachedJson, noteJsonWritten, clearJsonCache };
106
+ //# sourceMappingURL=file_json_cache.js.map
@@ -11,6 +11,12 @@ declare const Config: {
11
11
  DEXBOT_LAUNCHER_WORKER: boolean;
12
12
  DEXBOT_UPDATE_SKIP_RELOAD: boolean;
13
13
  DEXBOT_SKIP_VERSION_NOTICE: boolean;
14
+ /** Bypass the version-probe cache for one run (`dexbot stat` with
15
+ * DEXBOT_VERSION_CHECK_FORCE=1 re-probes instead of answering from the
16
+ * 12h cache). The diagnostic escape hatch for "is the registry reachable
17
+ * right now?" — a stale cached failure otherwise looks identical to a
18
+ * live one. */
19
+ DEXBOT_VERSION_CHECK_FORCE: boolean;
14
20
  NO_COLOR: string | undefined;
15
21
  PM2_HOME: string | undefined;
16
22
  DEXBOT_SUPERVISOR_SOCKET: string | undefined;
@@ -54,6 +54,7 @@ const Config = {
54
54
  DEXBOT_LAUNCHER_WORKER: bool('DEXBOT_LAUNCHER_WORKER'),
55
55
  DEXBOT_UPDATE_SKIP_RELOAD: bool('DEXBOT_UPDATE_SKIP_RELOAD'),
56
56
  DEXBOT_SKIP_VERSION_NOTICE: bool('DEXBOT_SKIP_VERSION_NOTICE'),
57
+ DEXBOT_VERSION_CHECK_FORCE: bool('DEXBOT_VERSION_CHECK_FORCE'),
57
58
  NO_COLOR: str('NO_COLOR'),
58
59
  // ── Paths ───────────────────────────────────────────────────────
59
60
  PM2_HOME: str('PM2_HOME'),
@@ -73,7 +73,7 @@
73
73
  * AMA_DELTA_THRESHOLD_PERCENT: % change in AMA center price that triggers grid reset
74
74
  * DEFAULT_AMA_KEY: Default AMA profile used for `gridPrice: "ama"`
75
75
  * AMAS: Built-in AMA1..AMA4 presets for market adapter defaults
76
- * Related to bot AMA configuration (profiles/bots.json: ama.enabled, erPeriod, etc.)
76
+ * Related to bot AMA configuration (profiles/bots.json: gridPrice keyword, ama.erPeriod, etc.)
77
77
  * Stored in: profiles/general.settings.json
78
78
  *
79
79
  * MAINTENANCE & MONITORING:
@@ -574,9 +574,13 @@ declare let UPDATER: {
574
574
  SCHEDULE: string;
575
575
  NOTICE_ENABLED: boolean;
576
576
  NOTICE_INTERVAL_MS: number;
577
+ NOTICE_RETRY_MS: number;
577
578
  NOTICE_TIMEOUT_MS: number;
578
579
  NOTICE_STATUS_TIMEOUT_MS: number;
580
+ NOTICE_STAGE_GRACE_MS: number;
579
581
  REGISTRY_URL: string;
582
+ GITHUB_RELEASE_URL: string;
583
+ GITHUB_API_BASE: string;
580
584
  };
581
585
  declare let LAUNCHER: {
582
586
  MONOLITHIC: {
@@ -74,7 +74,7 @@
74
74
  * AMA_DELTA_THRESHOLD_PERCENT: % change in AMA center price that triggers grid reset
75
75
  * DEFAULT_AMA_KEY: Default AMA profile used for `gridPrice: "ama"`
76
76
  * AMAS: Built-in AMA1..AMA4 presets for market adapter defaults
77
- * Related to bot AMA configuration (profiles/bots.json: ama.enabled, erPeriod, etc.)
77
+ * Related to bot AMA configuration (profiles/bots.json: gridPrice keyword, ama.erPeriod, etc.)
78
78
  * Stored in: profiles/general.settings.json
79
79
  *
80
80
  * MAINTENANCE & MONITORING:
@@ -1432,19 +1432,46 @@ let UPDATER = {
1432
1432
  // switch means the default-off auto-updater does not also silence the
1433
1433
  // "you are running an outdated build" warning.
1434
1434
  NOTICE_ENABLED: true,
1435
- // Minimum gap between registry probes (24h). Also throttles failures, so an
1436
- // offline node pays the network timeout at most once a day, not per start.
1437
- // Set 0 to probe on every launcher start (an explicit opt-in to always-check).
1438
- NOTICE_INTERVAL_MS: 86_400_000,
1439
- // Hard timeout for the registry request. The check never blocks startup,
1440
- // but a hung socket must not keep the launcher alive either.
1441
- NOTICE_TIMEOUT_MS: 2_000,
1442
- // Shorter cap for `dexbot status`, which awaits the probe inline (no
1443
- // startup work overlaps it), so a stale/offline probe cannot stall the
1444
- // status output for the full NOTICE_TIMEOUT_MS.
1445
- NOTICE_STATUS_TIMEOUT_MS: 750,
1446
- // Registry document queried for the published `latest` version.
1447
- REGISTRY_URL: "https://registry.npmjs.org/dexbot/latest"
1435
+ // Minimum gap between probes AFTER A SUCCESSFUL observation (12h). A
1436
+ // successful answer is stable, so it is cached and costs no request on
1437
+ // every run that consults it. Half a day rather than a full day: the
1438
+ // published version does not move under us, but `dexbot stat` is the
1439
+ // command an operator runs to ask "am I current?", and 24h let that answer
1440
+ // come from an observation taken the previous morning. Set 0 to probe on
1441
+ // every run (an explicit opt-in to always-check, which disables the
1442
+ // failure backoff too).
1443
+ NOTICE_INTERVAL_MS: 43_200_000,
1444
+ // Backoff after a FAILED probe. A failure is the one observation that
1445
+ // decays fastest: throttling it for the full NOTICE_INTERVAL_MS turned a
1446
+ // 5s network hiccup into a permanent gray "?" for a day, with no retry to
1447
+ // disprove it. A failure is therefore re-tried after 15 minutes while the
1448
+ // last good answer is still served from the cache in the meantime.
1449
+ NOTICE_RETRY_MS: 900_000,
1450
+ // Total network budget for one probe, shared evenly across the configured
1451
+ // sources. The check never blocks startup, but a hung socket must not keep
1452
+ // the launcher alive either.
1453
+ NOTICE_TIMEOUT_MS: 4_000,
1454
+ // Budget for the final re-probe in `dexbot stat`. That command gives the
1455
+ // probe 1s at the top of the report, 1s more at the end, and then this
1456
+ // budget for a forced second attempt; when even that answers nothing the
1457
+ // verdict says "no current version information" instead of leaving the
1458
+ // operator to infer it from a missing line. Kept at 3s so the whole
1459
+ // escalation costs ~4s of waiting, all of it at the bottom of the report.
1460
+ NOTICE_STATUS_TIMEOUT_MS: 3_000,
1461
+ // How long `dexbot stat` waits for an answer before printing the rest of
1462
+ // the report. A valid cache or a quick registry answer lands inside this
1463
+ // and the command never notices the wait.
1464
+ NOTICE_STAGE_GRACE_MS: 1_000,
1465
+ // Source 1 — the npm dist-tag document. Empty disables the source.
1466
+ REGISTRY_URL: "https://registry.npmjs.org/dexbot/latest",
1467
+ // Source 2 — the GitHub "latest release" document, the fallback for a host
1468
+ // that cannot reach registry.npmjs.org. Empty DERIVES the URL from
1469
+ // REPOSITORY_URL (so a fork/self-hosted mirror is honoured); set it to a
1470
+ // non-GitHub value to pin the endpoint, or to 'off' to disable the source.
1471
+ GITHUB_RELEASE_URL: "",
1472
+ // Base for the derived GitHub source. Split out so a GitHub Enterprise
1473
+ // mirror is a config change, not a code change.
1474
+ GITHUB_API_BASE: "https://api.github.com"
1448
1475
  };
1449
1476
  let LAUNCHER = {
1450
1477
  MONOLITHIC: {
@@ -2609,29 +2609,74 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
2609
2609
  // boundary-correct type so a SPREAD slot that, after a boundary shift, now sits
2610
2610
  // in the BUY or SELL zone is excluded — it would otherwise be placed on the
2611
2611
  // correction side at a price the grid already considers the opposite side.
2612
- // Candidate ordering: window-contiguous-first when the rail has live
2613
- // orders to extend (BUY lowest first, SELL highest first, both adjacent
2614
- // to the live window top). A fully-empty rail has no window anchor —
2615
- // "lowest buy" would be the rail bottom, placing deep orders while the
2616
- // near-market gap stays open — so it falls back to spread-edge-first
2617
- // (BUY highest, SELL lowest) to close the spread near market first.
2618
- // The gap-band promotion path below stays edge-first by necessity
2619
- // (boundary derivation requires contiguity), so under fund shortage
2620
- // in-rail holes heal before band slots.
2621
- const railHasLiveOrders = allOrders.some((o) => getSlotCorrectType(o) === railType && isOrderPlaced(o));
2622
- const sortCandidates = (a, b) => {
2623
- const edgeFirst = railType === ORDER_TYPES.BUY
2624
- ? b.price - a.price
2625
- : a.price - b.price;
2626
- const windowFirst = railType === ORDER_TYPES.BUY
2627
- ? a.price - b.price
2628
- : b.price - a.price;
2629
- return railHasLiveOrders ? windowFirst : edgeFirst;
2612
+ //
2613
+ // Candidate ordering: MARKET-NEAREST FIRST, one comparator for both
2614
+ // rail states. A correction is only useful if it tightens bestBuy/bestSell,
2615
+ // which means it must land on the market side of the live window — the
2616
+ // highest empty BUY (live window is the rail top) or the lowest empty
2617
+ // SELL (live window is the rail bottom). Empty slots always sit on the
2618
+ // far side of the live window, so "adjacent to the window" and "closest
2619
+ // to market" are the same slot, and the same comparator also gives the
2620
+ // correct answer for a fully-empty rail (no window anchor, so the
2621
+ // market-nearest slot is by definition the best one to create).
2622
+ //
2623
+ // This previously had two branches — windowFirst (windowed) vs
2624
+ // edgeFirst (empty) — that were written as exact OPPOSITES, so a SELL
2625
+ // rail with a live window sorted DESCENDING and picked the grid
2626
+ // ceiling: an order ~50% above bestSell that cannot tighten the spread
2627
+ // by a single tick, and that the next resync then cancels as surplus.
2628
+ const sortCandidates = (a, b) => railType === ORDER_TYPES.BUY
2629
+ ? b.price - a.price
2630
+ : a.price - b.price;
2631
+ // SPREAD-TIGHTENING GUARD: on a rail that already has a live order, only
2632
+ // a candidate that IMPROVES that rail's best price is a spread repair at
2633
+ // all. A SELL must land below the lowest live sell, a BUY above the
2634
+ // highest live buy. Anything else merely parks funds in a slot that sits
2635
+ // beyond the live window and leaves bestBuy/bestSell — and therefore the
2636
+ // measured spread — bit-for-bit unchanged.
2637
+ //
2638
+ // Sorting alone cannot enforce this: the orphan pool is rail-wide (every
2639
+ // empty slot on the side), so market-nearest still resolves to the first
2640
+ // empty slot PAST the window, which is on the wrong side of the live
2641
+ // best. Observed on a live market-pair bot whose live sells sat at
2642
+ // 1071-1134 with 116 empty sell slots above them: correction kept
2643
+ // creating orders at 1136, 1140, ... and eventually 1600/1605, none of
2644
+ // which could narrow the spread, until the next resync cancelled them
2645
+ // all as surplus. This guard makes the grid edge structurally
2646
+ // unreachable for a correction rather than merely sorted last.
2647
+ //
2648
+ // The reference is taken from `_getOnChainOrders` — the SAME input set
2649
+ // `calculateCurrentSpread` measures the spread from — so "does this
2650
+ // placement narrow the spread" is answered against literally the same
2651
+ // book the flag was raised from, and there is no second definition of
2652
+ // "counts as an on-chain order" to drift out of sync.
2653
+ //
2654
+ // Note the deliberate classifier asymmetry: the ANCHOR is matched by
2655
+ // stored `o.type` (inherited from _getOnChainOrders), while CANDIDATES
2656
+ // below are matched by `getSlotCorrectType` geometry. That is right
2657
+ // for both: an anchor is a live on-chain order whose side is what the
2658
+ // spread is actually computed from, whereas an empty candidate slot has
2659
+ // a normalized (often SPREAD) stored type and its intended side is the
2660
+ // geometric one.
2661
+ //
2662
+ // With no live order on the side there is no reference to improve, so
2663
+ // the market-nearest slot is by definition the best available and the
2664
+ // guard stays open.
2665
+ const { onChainBuys, onChainSells } = _getOnChainOrders(manager);
2666
+ const railBestIsMax = railType === ORDER_TYPES.BUY;
2667
+ const bestLiveOnRail = railBestIsMax
2668
+ ? (onChainBuys.length ? Math.max(...onChainBuys.map((o) => o.price)) : null)
2669
+ : (onChainSells.length ? Math.min(...onChainSells.map((o) => o.price)) : null);
2670
+ const tightensSpread = (c) => {
2671
+ if (bestLiveOnRail == null || c?.price == null)
2672
+ return true;
2673
+ return railBestIsMax ? c.price > bestLiveOnRail : c.price < bestLiveOnRail;
2630
2674
  };
2631
2675
  const typedSpreadCandidates = allOrders
2632
2676
  .filter((o) => o.type === ORDER_TYPES.SPREAD
2633
2677
  && isSlotAvailable(o)
2634
2678
  && getSlotCorrectType(o) === railType)
2679
+ .filter(tightensSpread)
2635
2680
  .sort(sortCandidates)
2636
2681
  .slice(0, missingSlots);
2637
2682
  // Secondary candidates: orphaned virtual slots that have lost their
@@ -2664,6 +2709,7 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
2664
2709
  && o.state === ORDER_STATES.VIRTUAL
2665
2710
  && !o.orderId
2666
2711
  && getSlotCorrectType(o) === railType)
2712
+ .filter(tightensSpread)
2667
2713
  .sort(sortCandidates)
2668
2714
  .slice(0, missingSlots);
2669
2715
  // If the funded rail is full, the spread itself may be stale: the
@@ -2711,22 +2757,44 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
2711
2757
  if (promotedCandidates.length > 0) {
2712
2758
  manager.logger?.log?.(`[SPREAD-CORRECTION] ${promotedCandidates.length} gap slot(s) available for boundary promotion on ${sideName}`, 'info');
2713
2759
  }
2760
+ else {
2761
+ // Promotion produced nothing. Name the BINDING constraint —
2762
+ // the three are operationally different (a config change fixes
2763
+ // one, a geometry change fixes the others) and a bare "skipped"
2764
+ // makes all three look identical.
2765
+ const bandSize = Math.max(0, sellStartIdx - buyEndIdx - 1);
2766
+ const oppositeSide = railType === ORDER_TYPES.BUY ? 'sell' : 'buy';
2767
+ const reason = maxPromotionDepth <= 0
2768
+ ? `stranding cap is 0 — a boundary slide would swallow a placed ${oppositeSide} order into the implied spread band`
2769
+ : (bandSize <= spreadReserve
2770
+ ? `gap band (${bandSize} slot(s)) is at or below the MIN_SPREAD_ORDERS reserve (${spreadReserve})`
2771
+ : 'no contiguous empty run from the rail edge into the band');
2772
+ manager.logger?.log?.(`[SPREAD-CORRECTION] no gap slot available on ${sideName} — ${reason}; the spread is not correctable on this side this cycle`, 'info');
2773
+ }
2714
2774
  }
2715
- // Merge: prefer orphaned virtuals (they already occupy correct grid positions) then
2716
- // fall back to SPREAD slots for any remaining quota.
2775
+ // Merge, GAP BAND FIRST. A boundary promotion is the only candidate
2776
+ // kind that places INSIDE the empty spread band, so it is listed ahead
2777
+ // of the rail pools. In practice the promotion GATE above (only promote
2778
+ // when the rail pools under-fill the quota) already keeps the two from
2779
+ // competing: once the spread-tightening guard empties the rail pool of
2780
+ // useless far-rail slots, the gate opens and the band is asked. The
2781
+ // ordering below is the belt to that braces — if the gate is ever
2782
+ // relaxed, the band still wins by default rather than losing to a
2783
+ // rail-wide pool that is capped at missingSlots on its own and so can
2784
+ // consume the whole quota without ever entering the gap.
2717
2785
  const remainingQuota = Math.max(0, missingSlots - orphanedVirtualCandidates.length);
2718
2786
  let spreadCandidates = [
2719
- ...orphanedVirtualCandidates,
2787
+ ...promotedCandidates,
2720
2788
  ...typedSpreadCandidates.slice(0, remainingQuota),
2721
- ...promotedCandidates
2789
+ ...orphanedVirtualCandidates
2722
2790
  ];
2723
2791
  // Dedupe by slot id: an empty in-rail slot typed SPREAD (normalized) now
2724
2792
  // qualifies for BOTH orphanedVirtualCandidates and typedSpreadCandidates
2725
2793
  // (both accept SPREAD type + rail geometry), so a single slot can be
2726
2794
  // planned twice. Duplicate CREATEs would inflate the sizing denominator
2727
2795
  // (diluting every order), mislead the plan counts, and get dropped by the
2728
- // COW same-batch collision filter anyway. Keep the first occurrence
2729
- // (orphaned-priority — those already occupy correct grid positions).
2796
+ // COW same-batch collision filter anyway. Keep the first occurrence —
2797
+ // which under the gap-first merge is the band slot where one exists.
2730
2798
  {
2731
2799
  const seenSlotIds = new Set();
2732
2800
  spreadCandidates = spreadCandidates.filter((c) => {
@@ -2770,7 +2838,9 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
2770
2838
  manager.logger?.log?.(`[SPREAD-CORRECTION] Identified ${spreadCandidates.length}/${missingSlots} slot(s) for activation on ${sideName} (orphaned=${orphanedVirtualCandidates.length}, spread=${spreadCandidates.length - orphanedVirtualCandidates.length})`, 'debug');
2771
2839
  }
2772
2840
  if (!edgePartial && spreadCandidates.length === 0) {
2773
- manager.logger?.log?.(`[SPREAD-CORRECTION] No suitable partials, orphaned virtual slots, or spread slots found. Skipping.`, 'warn');
2841
+ manager.logger?.log?.(bestLiveOnRail == null
2842
+ ? `[SPREAD-CORRECTION] No suitable partials, orphaned virtual slots, or spread slots found. Skipping.`
2843
+ : `[SPREAD-CORRECTION] No spread-tightening slot on ${sideName} (best live ${bestLiveOnRail}); every remaining empty slot sits beyond the live window and cannot narrow the spread. Skipping.`, 'warn');
2774
2844
  return { ordersToPlace: [], ordersToUpdate: [], origin: 'spread-correction' };
2775
2845
  }
2776
2846
  const orphanedIds = new Set(orphanedVirtualCandidates.map((o) => o.id));
@@ -21,23 +21,40 @@
21
21
  * prompt).
22
22
  * 2. NEVER THROWS. Every failure path — offline, DNS failure, slow registry,
23
23
  * unreadable cache, browser — resolves to `null`.
24
- * 3. NO SUBPROCESSES. The registry is queried with a single HTTPS GET and a
24
+ * 3. NO SUBPROCESSES. Each source is queried with a single HTTPS GET and a
25
25
  * hard timeout. `execSync('npm view ...')` (as used by `dexbot update`)
26
26
  * costs 1-3s of spawn and hard-depends on the npm CLI, neither of which is
27
27
  * acceptable on the launcher critical path.
28
+ * 3b. MULTIPLE SOURCES, FALLBACK NOT FAILURE. One source is a single point of
29
+ * failure: a host that cannot reach registry.npmjs.org (firewall, DNS, a
30
+ * proxy only the npm CLI knows about) reported "unknown" forever even when
31
+ * the release was published on GitHub. Sources are tried in order and the
32
+ * first answer wins, so an unreachable registry degrades to a slower probe
33
+ * instead of a permanent "?". Each source is bounded by an even share of
34
+ * the total budget, so a hanging first source cannot starve the second.
35
+ * 3c. NEVER MYSTERY. Every failure path records WHY (`ENOTFOUND`, `HTTP 403`,
36
+ * `timeout`, `no fetch`, …) and the unknown verdict names it. An operator
37
+ * cannot act on "?" and used to have to guess between DNS, TLS, a proxy and
38
+ * a timeout.
28
39
  * 4. THROTTLED + NOTIFY-ONCE. A check runs at most once per
29
- * `UPDATER.NOTICE_INTERVAL_MS`, and the same version is announced only once
30
- * (`notifiedVersion` in the cache) so an ignored notice does not nag on
31
- * every restart. A new published version resets that latch. The latch is
32
- * committed by `printVersionStatus` only AFTER the notice is displayed, so a
40
+ * `UPDATER.NOTICE_INTERVAL_MS` AFTER A SUCCESS, and once per
41
+ * `UPDATER.NOTICE_RETRY_MS` after a failure (a failure is the observation
42
+ * that decays fastest — see the constant). The same version is announced
43
+ * only once (`notifiedVersion` in the cache) so an ignored notice does not
44
+ * nag on every restart. A new published version resets that latch. The latch
45
+ * is committed by `printVersionStatus` only AFTER the notice is displayed, so a
33
46
  * launcher path that returns without printing cannot silently consume it —
34
47
  * it is re-offered once the throttle window expires. A throttled run still
35
48
  * reports a status (from the cached observation) so `dexbot stat` answers
36
49
  * "am I current?" without spending a request.
50
+ * 4a. DEFERRED, NOT DROPPED. Callers that have other work to do (`dexbot stat`
51
+ * prints a process table) start the probe, do their work, and flush the
52
+ * verdict when it lands. Nothing is printed speculatively and nothing is
53
+ * ever truncated by an early `process.exit()`.
37
54
  * 4b. ONE IMPLEMENTATION. Every consumer (`unlock`, `pm2`, `dexbot stat`) goes
38
- * through `startVersionStatusCheck` → `printVersionStatus`; the colour of the
39
- * status line, the hint wording and the latch all live here, so no caller can
40
- * drift from another.
55
+ * through this module — `startVersionStatusCheck` / `startStagedVersionStatus`
56
+ * → `printVersionStatus`; the colour of the status line, the hint wording
57
+ * and the latch all live here, so no caller can drift from another.
41
58
  * 5. SILENT WHEN DISABLED. `Config.DEXBOT_SKIP_VERSION_NOTICE=1` (tests, CI,
42
59
  * automation) or `UPDATER.NOTICE_ENABLED: false` short-circuits before any
43
60
  * network or filesystem work.
@@ -71,6 +88,17 @@ export interface VersionStatus {
71
88
  latestVersion: string | null;
72
89
  installKind: InstallKind;
73
90
  state: VersionState;
91
+ /** Id of the source that answered (`npm` / `github`). */
92
+ source?: string;
93
+ /** Why the probe could not answer — `ENOTFOUND`, `HTTP 403`, `timeout`…
94
+ * Only set when `state === 'unknown'`; rendered in the verdict so the
95
+ * operator can act instead of guessing. */
96
+ reason?: string;
97
+ /** True when the staged wait gave up: nothing answered at all, so the
98
+ * information is MISSING rather than the check having failed. Rendered
99
+ * differently — "no current version information" must not read as
100
+ * "could not check", and neither may read as "up to date". */
101
+ exhausted?: boolean;
74
102
  /** Cache file backing the throttle. Plumbing; callers should not read it. */
75
103
  cacheFile: string;
76
104
  /** Present only when a NEWER version exists AND it has not been announced
@@ -83,10 +111,16 @@ export interface VersionNoticeOptions {
83
111
  currentVersion?: string;
84
112
  /** Override the cache location (tests). */
85
113
  cacheFile?: string;
86
- /** Override the throttle window in ms; `< 0` forces a check. */
114
+ /** Override the throttle window in ms for a SUCCESSFUL cached observation
115
+ * (tests). 0 disables throttling. */
87
116
  intervalMs?: number;
117
+ /** Override the backoff in ms after a FAILED observation (tests). 0
118
+ * disables throttling, so every run re-probes. */
119
+ retryMs?: number;
88
120
  /** Override the registry URL (tests). Pass '' to model an unconfigured setup. */
89
121
  registryUrl?: string;
122
+ /** Override the GitHub releases URL (tests). '' / 'off' disables it. */
123
+ githubReleaseUrl?: string;
90
124
  /** Override `UPDATER.NOTICE_ENABLED` (tests). */
91
125
  enabled?: boolean;
92
126
  /** Override install-kind detection (tests). */
@@ -114,16 +148,87 @@ export interface VersionNoticeOptions {
114
148
  export declare function compareVersions(a: string, b: string): number;
115
149
  /** Classify the running install without spawning anything. */
116
150
  export declare function detectInstallKind(projectRoot?: string): InstallKind;
151
+ /** One place the published version can be read from. */
152
+ export interface VersionSource {
153
+ id: string;
154
+ url: string;
155
+ /** Pull the version out of the source's JSON shape. Returns null when the
156
+ * document does not carry a usable version (bad payload). */
157
+ extract: (body: any) => string | null;
158
+ }
159
+ /**
160
+ * Derive the GitHub "latest release" endpoint from the configured repository
161
+ * URL, so a fork or a self-hosted mirror is honoured without a second hardcoded
162
+ * owner/repo. Returns null for anything that is not a github.com repository —
163
+ * a non-GitHub host has a different API shape and guessing it would produce a
164
+ * guaranteed-wrong request on every probe.
165
+ */
166
+ export declare function deriveGithubReleaseUrl(repositoryUrl: string | undefined, apiBase: string): string | null;
167
+ /**
168
+ * The probe's sources, in priority order.
169
+ *
170
+ * npm FIRST, GitHub second — measured, and the order is load-bearing:
171
+ *
172
+ * latency a wash. Warm, interleaved: npm p50 21ms / github p50 18ms.
173
+ * Cold process: npm 92-102ms / github 97-99ms. GitHub being
174
+ * ~3ms "faster" is noise, not a reason to reorder.
175
+ * payload npm 8KB vs github 40KB (the release document carries the
176
+ * body, assets and author objects). 5x for the same answer.
177
+ * rate limit the GitHub API is 60 requests/hour per IP unauthenticated
178
+ * and answers 403 when spent; npm has no comparable ceiling.
179
+ * Our own 12h throttle keeps us far below it, but a shared
180
+ * server IP or a retry burst is not ours to control.
181
+ * AUTHORITY the deciding one. The release pipeline creates the GitHub
182
+ * release FIRST and publishes to npm ~4-9 minutes LATER
183
+ * (1.6.8 10:15:14Z vs 10:24:00Z; 1.6.7 09:08:48 vs 09:13:15;
184
+ * 1.6.6 00:49:52 vs 00:54:27). GitHub-first would therefore
185
+ * spend that window telling operators a new version exists
186
+ * while `dexbot update` still installs the old one — a hint
187
+ * that is not merely early but wrong. npm lagging by the same
188
+ * minutes is harmless: it says "up to date" a little longer.
189
+ *
190
+ * The cost of this order is the one case that measurably suffers: on a host
191
+ * that cannot reach the registry at all, the fallback answer arrives after the
192
+ * first source's share of the budget is spent (~1.6s of the 3s), versus ~20ms
193
+ * if GitHub went first. That is the right trade — a slow answer is still an
194
+ * answer, and the alternative is an answer that is wrong for the first minutes
195
+ * of every release.
196
+ */
197
+ export declare function resolveReleaseSources(options?: {
198
+ registryUrl?: string;
199
+ githubReleaseUrl?: string;
200
+ repositoryUrl?: string;
201
+ apiBase?: string;
202
+ }): VersionSource[];
117
203
  /**
118
204
  * The single status line, shared by `dexbot stat` and every launcher start.
119
205
  *
120
- * GREEN when the install matches the registry, ORANGE when a newer release
121
- * exists, GRAY when the probe could not answer (offline / throttled with no
122
- * prior observation) — an unknown answer must never be rendered as "up to
123
- * date". The installed version is always named, so a caller never needs a
124
- * second "DEXBot2 vX.Y.Z" header of its own.
206
+ * GREEN when the install matches the published version, ORANGE when a newer
207
+ * release exists, GRAY when the probe could not answer (offline / throttled
208
+ * with no prior observation) — an unknown answer must never be rendered as
209
+ * "up to date". The installed version is always named, so a caller never needs
210
+ * a second "DEXBot2 vX.Y.Z" header of its own. The unknown verdict carries the
211
+ * probe's reason, because an unnamed "?" tells the operator nothing they can
212
+ * act on.
125
213
  */
126
- export declare function formatVersionStatusLine(status: Pick<VersionStatus, 'currentVersion' | 'latestVersion' | 'state'>): string;
214
+ export declare function formatVersionStatusLine(status: Pick<VersionStatus, 'currentVersion' | 'latestVersion' | 'state'> & {
215
+ reason?: string;
216
+ exhausted?: boolean;
217
+ }): string;
218
+ /** What the whole probe concluded. */
219
+ export interface ProbeResult {
220
+ version: string | null;
221
+ source?: string;
222
+ /** Every source's failure reason, in the order they were tried. */
223
+ reasons: string[];
224
+ }
225
+ /**
226
+ * Try the sources in order and take the first answer. The total budget is split
227
+ * EVENLY rather than spent first-come: a source that hangs until the deadline
228
+ * would otherwise leave the fallback with no time at all, which is precisely
229
+ * the case the fallback exists for.
230
+ */
231
+ export declare function probeReleaseSources(sources: VersionSource[], timeoutMs: number, fetchImpl?: any): Promise<ProbeResult>;
127
232
  /**
128
233
  * Start the check. Resolves with the installed-vs-published status, plus a
129
234
  * `notice` when a NEWER version exists and that version has not been
@@ -141,14 +246,21 @@ export declare function printVersionStatus(status: VersionStatus | null | undefi
141
246
  surround?: boolean;
142
247
  }): void;
143
248
  /**
144
- * Run the check and print the status/notice to stdout. Convenience wrapper
145
- * for call sites with nothing to overlap (e.g. `dexbot status`). Returns the
146
- * status that was printed, or null when the feature is switched off.
249
+ * The entry-point renderer: the status line when there is one, the bare
250
+ * installed-version header when the check is switched off.
251
+ *
252
+ * `printVersionStatus(null)` is a deliberate no-op, which is right for a
253
+ * caller that only wants the line — but every CLI entry point must still name
254
+ * the running build when the notice is disabled
255
+ * (`DEXBOT_SKIP_VERSION_NOTICE=1` / `UPDATER.NOTICE_ENABLED=false`), and
256
+ * re-implementing that fallback per entry point is how they drift: `dexbot
257
+ * stat` had it, `dexbot pm2` did not, so a node with the notice off learned its
258
+ * version from one command and not the other. One helper, one behaviour.
147
259
  */
148
- export declare function maybePrintVersionStatus(options?: VersionNoticeOptions & {
260
+ export declare function printVersionStatusOrHeader(status: VersionStatus | null | undefined, options?: {
149
261
  indent?: string;
150
262
  surround?: boolean;
151
- }): Promise<VersionStatus | null>;
263
+ }): void;
152
264
  /**
153
265
  * Await an already-started check and print its status. The single flush path
154
266
  * for callers (`unlock.ts`, `pm2.ts`) that start the probe early and surface it
@@ -156,10 +268,44 @@ export declare function maybePrintVersionStatus(options?: VersionNoticeOptions &
156
268
  * call site.
157
269
  */
158
270
  export declare function flushVersionStatus(pending: Promise<VersionStatus | null>): Promise<void>;
271
+ /**
272
+ * The flush counterpart of `printVersionStatusOrHeader`, for callers that start
273
+ * the probe early and surface it at a terminal point (`unlock.ts`, `pm2.ts`).
274
+ * A null status is the "check switched off" signal, so the installed version is
275
+ * still named - the same single behaviour the stat path gets.
276
+ */
277
+ export declare function flushVersionStatusOrHeader(pending: Promise<VersionStatus | null>): Promise<void>;
159
278
  /**
160
279
  * Print the status when the probe settles, WITHOUT awaiting it. For launch
161
280
  * paths that must never delay the bot start — the resident process outlives the
162
281
  * probe, so there is no `process.exit()` to truncate it.
282
+ *
283
+ * Uses the header-aware renderer: an entry point must name the running build
284
+ * even when the check is switched off, and this is the non-awaited form of the
285
+ * same contract as `flushVersionStatusOrHeader`.
163
286
  */
164
287
  export declare function printVersionStatusWhenReady(pending: Promise<VersionStatus | null>): void;
288
+ export interface StagedVersionNoticeOptions extends VersionNoticeOptions {
289
+ /** Wait at the top of the command before the caller prints anything else.
290
+ * Default `UPDATER.NOTICE_STAGE_GRACE_MS` (1s). */
291
+ graceMs?: number;
292
+ /** Budget for the final forced re-probe. Default
293
+ * `UPDATER.NOTICE_STATUS_TIMEOUT_MS`. */
294
+ finalMs?: number;
295
+ }
296
+ export interface StagedVersionWait {
297
+ /** The status if it lands within `graceMs`, else null. Await this at the
298
+ * top of a report; the value is only interesting for its TIMING. */
299
+ quick: Promise<VersionStatus | null>;
300
+ /** The status to display at the end. Never "still in flight": it resolves
301
+ * with a definitive answer, or with an exhausted status naming the
302
+ * absence of information. Resolves null only when the feature is off. */
303
+ settled: Promise<VersionStatus | null>;
304
+ }
305
+ /**
306
+ * Start the probe and expose the two moments described above. The first probe
307
+ * is started immediately; `quick` settles within the grace period and `settled`
308
+ * carries the whole escalation.
309
+ */
310
+ export declare function startStagedVersionStatus(options?: StagedVersionNoticeOptions): StagedVersionWait;
165
311
  //# sourceMappingURL=version_notice.d.ts.map