@econ-v1/domain 7.6.158 → 7.6.160

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
@@ -273,7 +273,7 @@ export { OutboxIdempotencyConflictError, OutboxRevalidationRequiredError, Outbox
273
273
  export { ExpiredInvoiceError, InsufficientWalletBalanceError, OfflineWalletCommandError, WalletCommandRejectedError, WalletFreshStateRequiredError, WalletMirrorService } from "./services/wallet-mirror-service.js";
274
274
  export { canonicalHttpCandidateOrigin, isPotentiallyTrustworthyOrigin, transportStateChanged, TransportManager } from "./services/transport-manager.js";
275
275
  export { normalizeAdvertisement, nodeMetadataCandidates, PeerDirectoryService, uniqueAddresses } from "./services/peer-directory-service.js";
276
- export { addressMoveTargets, isPublicIpOrigin } from "./network/address-move.js";
276
+ export { addressMoveTargets, isPublicIpOrigin, signalFromRtt } from "./network/address-move.js";
277
277
  export { DiscoveryProbeService, secureLanOrigin } from "./services/discovery-probe-service.js";
278
278
  export { createDiscoveryCandidatesQuery, DISCOVERY_CANDIDATES_QUERY } from "./queries/discovery.js";
279
279
  export { createOnboardingStatusQuery, ONBOARDING_STATUS_QUERY } from "./queries/onboarding-status.js";
@@ -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
@@ -20,4 +20,11 @@ export function addressMoveTargets({ pageOrigin, wanOrigins, wanOrigin, onDirect
20
20
  wanOrigin?: string;
21
21
  onDirectToPage: boolean;
22
22
  }): readonly string[];
23
+ /** Signal bars for an address-move option, derived purely from the measured
24
+ * direct-check round-trip time. Kept here, not in the kernel or UI, so both the
25
+ * offer-building service and the presentation layer share one threshold table.
26
+ * @param {number} rttMs
27
+ * @returns {1 | 2 | 3 | 4}
28
+ */
29
+ export function signalFromRtt(rttMs: number): 1 | 2 | 3 | 4;
23
30
  //# sourceMappingURL=address-move.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"address-move.d.ts","sourceRoot":"","sources":["../../src/network/address-move.js"],"names":[],"mappings":"AAuDA;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,OAAO,CAUnB;AAED;;;;;;;;GAQG;AACH,0FAHW;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GACjG,SAAS,MAAM,EAAE,CAU7B"}
1
+ {"version":3,"file":"address-move.d.ts","sourceRoot":"","sources":["../../src/network/address-move.js"],"names":[],"mappings":"AAuDA;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,OAAO,CAUnB;AAED;;;;;;;;GAQG;AACH,0FAHW;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GACjG,SAAS,MAAM,EAAE,CAU7B;AAED;;;;;GAKG;AACH,qCAHW,MAAM,GACJ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAOzB"}
@@ -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"}
@@ -1 +1 @@
1
- {"version":3,"file":"device-boot-state-service.d.ts","sourceRoot":"","sources":["../../src/services/device-boot-state-service.js"],"names":[],"mappings":"AACA,wEAAwE;AACxE,wEAAwE;AACxE,wLAAwL;AACxL;IAKI,qDAAqD;IACrD,qBADY,6BAA6B,EAIxC;IACD,0CAA0C;IAC1C,SADc,OAAO,CAAC,eAAe,CAAC,CAiDrC;;CACJ;4CA7Dc;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,gBAAgB,GAAG,eAAe,GAAG,0BAA0B,CAAC,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAAE;qCADjH,gCAAgC;kCADhB,gBAAgB"}
1
+ {"version":3,"file":"device-boot-state-service.d.ts","sourceRoot":"","sources":["../../src/services/device-boot-state-service.js"],"names":[],"mappings":"AACA,wEAAwE;AACxE,wEAAwE;AACxE,wLAAwL;AACxL;IAKI,qDAAqD;IACrD,qBADY,6BAA6B,EAIxC;IACD,0CAA0C;IAC1C,SADc,OAAO,CAAC,eAAe,CAAC,CAsDrC;;CACJ;4CAlEc;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,gBAAgB,GAAG,eAAe,GAAG,0BAA0B,CAAC,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAAE;qCADjH,gCAAgC;kCADhB,gBAAgB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@econ-v1/domain",
3
- "version": "7.6.158",
3
+ "version": "7.6.160",
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.158"
60
+ "@econ-v1/ports": "7.6.160"
61
61
  }
62
62
  }
package/src/index.js CHANGED
@@ -543,7 +543,7 @@ export { OwnerViewService } from "./services/owner-view-service.js";
543
543
  export { OwnerViewRefreshService } from "./services/owner-view-refresh-service.js";
544
544
  export { OWNER_VIEW_SYNC_STRATEGIES } from "./models/owner-views.js";
545
545
  export { LanCandidateRefreshService } from "./services/lan-candidate-refresh-service.js";
546
- export { addressMoveTargets, isPublicIpOrigin } from "./network/address-move.js";
546
+ export { addressMoveTargets, isPublicIpOrigin, signalFromRtt } from "./network/address-move.js";
547
547
  export { DiscoveryProbeService, secureLanOrigin } from "./services/discovery-probe-service.js";
548
548
  export { DeviceBootStateService } from "./services/device-boot-state-service.js";
549
549
  export { createDiscoveryCandidatesQuery, DISCOVERY_CANDIDATES_QUERY } from "./queries/discovery.js";
@@ -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";
@@ -88,6 +88,19 @@ export function addressMoveTargets({ pageOrigin, wanOrigins, wanOrigin, onDirect
88
88
  return origins.sort((a, b) => Number(b.startsWith("https://[")) - Number(a.startsWith("https://[")));
89
89
  }
90
90
 
91
+ /** Signal bars for an address-move option, derived purely from the measured
92
+ * direct-check round-trip time. Kept here, not in the kernel or UI, so both the
93
+ * offer-building service and the presentation layer share one threshold table.
94
+ * @param {number} rttMs
95
+ * @returns {1 | 2 | 3 | 4}
96
+ */
97
+ export function signalFromRtt(rttMs) {
98
+ if (rttMs <= 80) return 4;
99
+ if (rttMs <= 200) return 3;
100
+ if (rttMs <= 500) return 2;
101
+ return 1;
102
+ }
103
+
91
104
  /** @param {string} origin @returns {string} */
92
105
  function normalizeOrigin(origin) {
93
106
  return origin.toLowerCase().replace(/\/$/u, "").replace(/:443$/u, "");
@@ -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 });
@@ -21,17 +21,20 @@ export class DeviceBootStateService {
21
21
  }
22
22
  catch {
23
23
  // A store we cannot read must fail toward pairing, never toward a crash or
24
- // toward rendering cached data on an unverified device (spec §5).
24
+ // toward rendering cached data on an unverified device (spec §5). "unpaired" is
25
+ // not a verdict either (ADR-258): the pairing gate first tries a signed session
26
+ // with the stored key and shows pairing only on the node's own answer.
25
27
  return { kind: "unpaired" };
26
28
  }
27
29
  if (lifecycle === "revoked")
28
30
  return { kind: "revoked" };
29
31
  if (lifecycle === "unusable") {
30
- // The key was quarantined (kept, never purged) on a failed inspection — see
31
- // docs/superpowers/plans/2026-10-08-no-silent-device-key-purge.md. Best-effort read
32
- // of WHY, mirroring the fail-toward-unpaired discipline above: a diagnostic read
33
- // failure must never escalate past "no reason/time to show", since the lifecycle
34
- // verdict itself already came back clean.
32
+ // ADR-258: only a key that is genuinely MISSING (still absent after a re-read, see
33
+ // `WebCryptoIdentity#generate`) gates the UI. A lifecycle an older release left
34
+ // `"unusable"` after a failed key CHECK is not a verdict on this device: the key is
35
+ // kept and re-verified (and self-healed to `"active"`) on every `generate()`, so it
36
+ // falls through to the delegation below like any active identity. A diagnostic read
37
+ // that fails, or carries no reason, falls through too — never toward a lockout.
35
38
  /** @type {Awaited<ReturnType<NonNullable<DeviceBootStateServiceOptions["identity"]["loadKeyInspectionFailure"]>>>} */
36
39
  let diagnostic;
37
40
  try {
@@ -40,11 +43,13 @@ export class DeviceBootStateService {
40
43
  catch {
41
44
  diagnostic = undefined;
42
45
  }
43
- return {
44
- kind: "key-unusable",
45
- ...(diagnostic?.reason === undefined ? {} : { reason: diagnostic.reason }),
46
- ...(diagnostic?.detectedAt === undefined ? {} : { detectedAt: diagnostic.detectedAt }),
47
- };
46
+ if (diagnostic?.reason === "key-material-missing") {
47
+ return {
48
+ kind: "key-unusable",
49
+ reason: diagnostic.reason,
50
+ ...(diagnostic.detectedAt === undefined ? {} : { detectedAt: diagnostic.detectedAt }),
51
+ };
52
+ }
48
53
  }
49
54
  /** @type {Awaited<ReturnType<IdentityPort["loadDelegation"]>>} */
50
55
  let delegation;