@econ-v1/domain 7.6.157 → 7.6.159

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/dist/index.d.ts CHANGED
@@ -288,4 +288,5 @@ export { safeOpenPath, parsePushPayload, derivePushDeviceStatus, isPushTag } fro
288
288
  export { classifyOrigin, routeOrder } from "./network/route-order.js";
289
289
  export { ROUTE_SPEED_TIERS, speedTier } from "./network/route-speed.js";
290
290
  export { formatNodeLabel, shortNodeId } from "./services/node-label.js";
291
+ export { DEFAULT_ROUTE_SELECTION_POLICY, ROUTE_SELECTION_DEFAULTS } from "./network/route-selection.js";
291
292
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,26 @@
1
+ /** @import { RouteDecision, RouteSelectionInput, RouteSelectionRung, TransportRungName } from '@econ-v1/ports' */
2
+ /** All thresholds for the default strategy (ADR-218 Amendment 12). */
3
+ export const ROUTE_SELECTION_DEFAULTS: Readonly<{
4
+ rank: Readonly<{
5
+ lan: 0;
6
+ wan: 1;
7
+ punch: 2;
8
+ relay: 3;
9
+ }>;
10
+ promotionSuccesses: 2;
11
+ promotionStabilityMs: 10000;
12
+ speedRatio: 0.7;
13
+ speedMinDeltaMs: 50;
14
+ speedStabilityMs: 10000;
15
+ measurementMaxAgeMs: 60000;
16
+ dropThreshold: 3;
17
+ dropWindowMs: 300000;
18
+ unstableCooldownMs: 300000;
19
+ }>;
20
+ /** @type {Readonly<import('@econ-v1/ports').RouteSelectionPolicy> & { decide: (input: RouteSelectionInput) => RouteDecision }} */
21
+ export const DEFAULT_ROUTE_SELECTION_POLICY: Readonly<import("@econ-v1/ports").RouteSelectionPolicy> & {
22
+ decide: (input: RouteSelectionInput) => RouteDecision;
23
+ };
24
+ import type { RouteSelectionInput } from '@econ-v1/ports';
25
+ import type { RouteDecision } from '@econ-v1/ports';
26
+ //# sourceMappingURL=route-selection.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"route-selection.d.ts","sourceRoot":"","sources":["../../src/network/route-selection.js"],"names":[],"mappings":"AAEA,kHAAkH;AAElH,sEAAsE;AACtE;;;;;;;;;;;;;;;;GAWG;AA0FH,kIAAkI;AAClI,6CADW,QAAQ,CAAC,OAAO,gBAAgB,EAAE,oBAAoB,CAAC,GAAG;IAAE,MAAM,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,aAAa,CAAA;CAAE,CACpC;yCAzGK,gBAAgB;mCAAhB,gBAAgB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@econ-v1/domain",
3
- "version": "7.6.157",
3
+ "version": "7.6.159",
4
4
  "description": "Platform-neutral domain contracts and errors for Node clients",
5
5
  "license": "MIT OR Apache-2.0",
6
6
  "author": "Node contributors",
@@ -57,6 +57,6 @@
57
57
  "access": "public"
58
58
  },
59
59
  "dependencies": {
60
- "@econ-v1/ports": "7.6.157"
60
+ "@econ-v1/ports": "7.6.159"
61
61
  }
62
62
  }
package/src/index.js CHANGED
@@ -595,3 +595,5 @@ export { classifyOrigin, routeOrder } from "./network/route-order.js";
595
595
  export { ROUTE_SPEED_TIERS, speedTier } from "./network/route-speed.js";
596
596
 
597
597
  export { formatNodeLabel, shortNodeId } from "./services/node-label.js";
598
+
599
+ export { DEFAULT_ROUTE_SELECTION_POLICY, ROUTE_SELECTION_DEFAULTS } from "./network/route-selection.js";
@@ -0,0 +1,108 @@
1
+ // @ts-check
2
+
3
+ /** @import { RouteDecision, RouteSelectionInput, RouteSelectionRung, TransportRungName } from '@econ-v1/ports' */
4
+
5
+ /** All thresholds for the default strategy (ADR-218 Amendment 12). */
6
+ export const ROUTE_SELECTION_DEFAULTS = Object.freeze({
7
+ rank: Object.freeze({ lan: 0, wan: 1, punch: 2, relay: 3 }),
8
+ promotionSuccesses: 2,
9
+ promotionStabilityMs: 10_000,
10
+ speedRatio: 0.7,
11
+ speedMinDeltaMs: 50,
12
+ speedStabilityMs: 10_000,
13
+ measurementMaxAgeMs: 60_000,
14
+ dropThreshold: 3,
15
+ dropWindowMs: 300_000,
16
+ unstableCooldownMs: 300_000,
17
+ });
18
+
19
+ /** @type {readonly TransportRungName[]} */
20
+ const RUNGS = Object.freeze(['lan', 'wan', 'punch', 'relay']);
21
+ /** @type {RouteDecision} */
22
+ const STAY = Object.freeze({ kind: 'stay' });
23
+
24
+ /** @param {RouteSelectionRung} rung @param {number} now */
25
+ function fresh(rung, now) {
26
+ const checked = Date.parse(rung.checkedAt ?? '');
27
+ const expires = Date.parse(rung.expiresAt ?? '');
28
+ return Number.isFinite(checked) && checked <= now && now - checked <= ROUTE_SELECTION_DEFAULTS.measurementMaxAgeMs
29
+ && Number.isFinite(expires) && expires > now;
30
+ }
31
+
32
+ /** @param {RouteSelectionInput} input @param {TransportRungName} name */
33
+ function working(input, name) {
34
+ const rung = input.rungs[name];
35
+ if (rung.status === 'active' && input.active === name) return true;
36
+ return rung.status === 'ok' && (input.active === name || fresh(rung, input.now));
37
+ }
38
+
39
+ /** A cooldown starts on each drop that completes a recent threshold episode.
40
+ * Keeping the whole window plus cooldown avoids shortening it when the first
41
+ * drop ages out. Future timestamps never count.
42
+ * @param {RouteSelectionRung} rung @param {number} now
43
+ */
44
+ function unstable(rung, now) {
45
+ const drops = rung.drops.filter(at => Number.isFinite(at) && at <= now).slice().sort((a, b) => a - b);
46
+ for (let index = drops.length - 1; index >= ROUTE_SELECTION_DEFAULTS.dropThreshold - 1; index -= 1) {
47
+ const at = drops[index];
48
+ const first = drops[index - ROUTE_SELECTION_DEFAULTS.dropThreshold + 1];
49
+ if (at !== undefined && first !== undefined && now - at < ROUTE_SELECTION_DEFAULTS.unstableCooldownMs
50
+ && at - first < ROUTE_SELECTION_DEFAULTS.dropWindowMs) return true;
51
+ }
52
+ return false;
53
+ }
54
+
55
+ /** @param {RouteSelectionRung} rung @param {number} now */
56
+ function measured(rung, now) {
57
+ return fresh(rung, now) && rung.rttMs !== undefined && Number.isFinite(rung.rttMs) && rung.rttMs >= 0;
58
+ }
59
+
60
+ /** Selects deterministically without mutating the snapshot or doing I/O.
61
+ * Rank breaks ties; a sustained materially faster route may beat that order.
62
+ * @param {RouteSelectionInput} input @returns {RouteDecision}
63
+ */
64
+ function decide(input) {
65
+ const { active, now } = input;
66
+ const activeWorks = active !== undefined && working(input, active);
67
+ // Owner intent wins while working, even over automatic reliability heuristics.
68
+ if (input.pinned !== undefined && working(input, input.pinned)) {
69
+ return input.pinned === active ? STAY : { kind: 'switch', to: input.pinned, reason: { code: active !== undefined && !activeWorks ? 'failed' : 'pinned' } };
70
+ }
71
+ const eligible = RUNGS.filter(name => working(input, name) && !unstable(input.rungs[name], now));
72
+ const alternatives = eligible.filter(name => name !== active);
73
+ const best = alternatives[0];
74
+ if (best === undefined) return STAY;
75
+ if (!activeWorks || active === undefined) return { kind: 'switch', to: best, reason: { code: 'failed' } };
76
+ const current = input.rungs[active];
77
+ if (unstable(current, now)) {
78
+ return { kind: 'switch', to: best, reason: { code: 'unstable', drops: current.drops.filter(at => at <= now && now - at < ROUTE_SELECTION_DEFAULTS.dropWindowMs).length } };
79
+ }
80
+ // Test speed before rank so telemetry can explain a clear improvement.
81
+ const faster = alternatives.filter(name => {
82
+ const candidate = input.rungs[name];
83
+ return measured(candidate, now) && measured(current, now)
84
+ && candidate.speedStableSinceMs !== undefined && candidate.speedStableSinceMs <= now
85
+ && now - candidate.speedStableSinceMs >= ROUTE_SELECTION_DEFAULTS.speedStabilityMs
86
+ && candidate.rttMs !== undefined && current.rttMs !== undefined
87
+ && candidate.rttMs <= current.rttMs * ROUTE_SELECTION_DEFAULTS.speedRatio
88
+ && current.rttMs - candidate.rttMs >= ROUTE_SELECTION_DEFAULTS.speedMinDeltaMs;
89
+ }).sort((a, b) => (input.rungs[a].rttMs ?? Infinity) - (input.rungs[b].rttMs ?? Infinity)
90
+ || ROUTE_SELECTION_DEFAULTS.rank[a] - ROUTE_SELECTION_DEFAULTS.rank[b])[0];
91
+ if (faster !== undefined) return { kind: 'switch', to: faster, reason: { code: 'faster', fromMs: /** @type {number} */ (current.rttMs), toMs: /** @type {number} */ (input.rungs[faster].rttMs) } };
92
+ const higher = alternatives.find(name => {
93
+ const candidate = input.rungs[name];
94
+ // Do not undo a speed-driven switch merely because the slower route ranks higher.
95
+ const materiallySlower = measured(current, now) && measured(candidate, now)
96
+ && current.rttMs !== undefined && candidate.rttMs !== undefined
97
+ && current.rttMs <= candidate.rttMs * ROUTE_SELECTION_DEFAULTS.speedRatio
98
+ && candidate.rttMs - current.rttMs >= ROUTE_SELECTION_DEFAULTS.speedMinDeltaMs;
99
+ return !materiallySlower && ROUTE_SELECTION_DEFAULTS.rank[name] < ROUTE_SELECTION_DEFAULTS.rank[active]
100
+ && candidate.okStreak >= ROUTE_SELECTION_DEFAULTS.promotionSuccesses
101
+ && candidate.stableSinceMs !== undefined && candidate.stableSinceMs <= now
102
+ && now - candidate.stableSinceMs >= ROUTE_SELECTION_DEFAULTS.promotionStabilityMs;
103
+ });
104
+ return higher === undefined ? STAY : { kind: 'switch', to: higher, reason: { code: 'higher-rank' } };
105
+ }
106
+
107
+ /** @type {Readonly<import('@econ-v1/ports').RouteSelectionPolicy> & { decide: (input: RouteSelectionInput) => RouteDecision }} */
108
+ export const DEFAULT_ROUTE_SELECTION_POLICY = Object.freeze({ id: 'default-v1', decide });