@optimystic/db-core 1.10.1 → 1.12.0

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 (129) hide show
  1. package/dist/src/cluster/structs.d.ts +48 -7
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.js +33 -13
  4. package/dist/src/cluster/structs.js.map +1 -1
  5. package/dist/src/cohort-topic/coldstart.d.ts +8 -4
  6. package/dist/src/cohort-topic/coldstart.d.ts.map +1 -1
  7. package/dist/src/cohort-topic/coldstart.js +3 -3
  8. package/dist/src/cohort-topic/coldstart.js.map +1 -1
  9. package/dist/src/cohort-topic/member-engine.d.ts +5 -1
  10. package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
  11. package/dist/src/cohort-topic/member-engine.js.map +1 -1
  12. package/dist/src/cohort-topic/registration/store.d.ts +8 -1
  13. package/dist/src/cohort-topic/registration/store.d.ts.map +1 -1
  14. package/dist/src/cohort-topic/registration/store.js +57 -0
  15. package/dist/src/cohort-topic/registration/store.js.map +1 -1
  16. package/dist/src/cohort-topic/willingness.d.ts +4 -3
  17. package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
  18. package/dist/src/cohort-topic/willingness.js.map +1 -1
  19. package/dist/src/cohort-topic/wire/primitives.d.ts +5 -0
  20. package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
  21. package/dist/src/cohort-topic/wire/primitives.js +5 -0
  22. package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
  23. package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
  24. package/dist/src/cohort-topic/wire/validate.js +1 -3
  25. package/dist/src/cohort-topic/wire/validate.js.map +1 -1
  26. package/dist/src/collection/action.d.ts +15 -1
  27. package/dist/src/collection/action.d.ts.map +1 -1
  28. package/dist/src/collection/action.js.map +1 -1
  29. package/dist/src/collection/collection.d.ts.map +1 -1
  30. package/dist/src/collection/collection.js +60 -5
  31. package/dist/src/collection/collection.js.map +1 -1
  32. package/dist/src/collection/struct.d.ts +6 -2
  33. package/dist/src/collection/struct.d.ts.map +1 -1
  34. package/dist/src/collection/struct.js.map +1 -1
  35. package/dist/src/index.d.ts +1 -0
  36. package/dist/src/index.d.ts.map +1 -1
  37. package/dist/src/index.js +1 -0
  38. package/dist/src/index.js.map +1 -1
  39. package/dist/src/matchmaking/arrival-push.d.ts +35 -0
  40. package/dist/src/matchmaking/arrival-push.d.ts.map +1 -0
  41. package/dist/src/matchmaking/arrival-push.js +56 -0
  42. package/dist/src/matchmaking/arrival-push.js.map +1 -0
  43. package/dist/src/matchmaking/config.d.ts +12 -2
  44. package/dist/src/matchmaking/config.d.ts.map +1 -1
  45. package/dist/src/matchmaking/config.js +8 -2
  46. package/dist/src/matchmaking/config.js.map +1 -1
  47. package/dist/src/matchmaking/index.d.ts +3 -2
  48. package/dist/src/matchmaking/index.d.ts.map +1 -1
  49. package/dist/src/matchmaking/index.js +3 -2
  50. package/dist/src/matchmaking/index.js.map +1 -1
  51. package/dist/src/matchmaking/seeker.d.ts +5 -2
  52. package/dist/src/matchmaking/seeker.d.ts.map +1 -1
  53. package/dist/src/matchmaking/seeker.js +6 -1
  54. package/dist/src/matchmaking/seeker.js.map +1 -1
  55. package/dist/src/matchmaking/wire.d.ts +66 -3
  56. package/dist/src/matchmaking/wire.d.ts.map +1 -1
  57. package/dist/src/matchmaking/wire.js +79 -11
  58. package/dist/src/matchmaking/wire.js.map +1 -1
  59. package/dist/src/network/i-key-network.d.ts +8 -0
  60. package/dist/src/network/i-key-network.d.ts.map +1 -1
  61. package/dist/src/network/index.d.ts +1 -0
  62. package/dist/src/network/index.d.ts.map +1 -1
  63. package/dist/src/network/index.js +1 -0
  64. package/dist/src/network/index.js.map +1 -1
  65. package/dist/src/network/stale-failure.d.ts +12 -3
  66. package/dist/src/network/stale-failure.d.ts.map +1 -1
  67. package/dist/src/network/stale-failure.js +14 -1
  68. package/dist/src/network/stale-failure.js.map +1 -1
  69. package/dist/src/network/struct.d.ts +54 -4
  70. package/dist/src/network/struct.d.ts.map +1 -1
  71. package/dist/src/network/struct.js.map +1 -1
  72. package/dist/src/network/transaction-expired-error.d.ts +44 -0
  73. package/dist/src/network/transaction-expired-error.d.ts.map +1 -0
  74. package/dist/src/network/transaction-expired-error.js +77 -0
  75. package/dist/src/network/transaction-expired-error.js.map +1 -0
  76. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  77. package/dist/src/testing/test-transactor.js +28 -46
  78. package/dist/src/testing/test-transactor.js.map +1 -1
  79. package/dist/src/transaction/coordinator.d.ts +4 -1
  80. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  81. package/dist/src/transaction/coordinator.js +31 -5
  82. package/dist/src/transaction/coordinator.js.map +1 -1
  83. package/dist/src/transaction/index.d.ts +1 -1
  84. package/dist/src/transaction/index.d.ts.map +1 -1
  85. package/dist/src/transaction/index.js +1 -1
  86. package/dist/src/transaction/index.js.map +1 -1
  87. package/dist/src/transaction/transaction.d.ts +27 -0
  88. package/dist/src/transaction/transaction.d.ts.map +1 -1
  89. package/dist/src/transaction/transaction.js +27 -0
  90. package/dist/src/transaction/transaction.js.map +1 -1
  91. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  92. package/dist/src/transactor/network-transactor.js +32 -39
  93. package/dist/src/transactor/network-transactor.js.map +1 -1
  94. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  95. package/dist/src/transactor/transactor-source.js +6 -2
  96. package/dist/src/transactor/transactor-source.js.map +1 -1
  97. package/dist/src/utility/format-instant.d.ts +8 -0
  98. package/dist/src/utility/format-instant.d.ts.map +1 -0
  99. package/dist/src/utility/format-instant.js +11 -0
  100. package/dist/src/utility/format-instant.js.map +1 -0
  101. package/package.json +1 -1
  102. package/src/cluster/structs.ts +72 -14
  103. package/src/cohort-topic/coldstart.ts +8 -4
  104. package/src/cohort-topic/member-engine.ts +5 -1
  105. package/src/cohort-topic/registration/store.ts +68 -0
  106. package/src/cohort-topic/willingness.ts +4 -3
  107. package/src/cohort-topic/wire/primitives.ts +6 -0
  108. package/src/cohort-topic/wire/validate.ts +1 -3
  109. package/src/collection/action.ts +15 -1
  110. package/src/collection/collection.ts +63 -5
  111. package/src/collection/struct.ts +6 -2
  112. package/src/index.ts +1 -0
  113. package/src/matchmaking/arrival-push.ts +66 -0
  114. package/src/matchmaking/config.ts +17 -2
  115. package/src/matchmaking/index.ts +3 -2
  116. package/src/matchmaking/seeker.ts +11 -3
  117. package/src/matchmaking/wire.ts +134 -10
  118. package/src/network/i-key-network.ts +9 -0
  119. package/src/network/index.ts +1 -0
  120. package/src/network/stale-failure.ts +16 -3
  121. package/src/network/struct.ts +57 -4
  122. package/src/network/transaction-expired-error.ts +81 -0
  123. package/src/testing/test-transactor.ts +28 -40
  124. package/src/transaction/coordinator.ts +37 -7
  125. package/src/transaction/index.ts +2 -1
  126. package/src/transaction/transaction.ts +28 -0
  127. package/src/transactor/network-transactor.ts +36 -43
  128. package/src/transactor/transactor-source.ts +6 -2
  129. package/src/utility/format-instant.ts +10 -0
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Matchmaking — arrival-push fan-out selection (db-core, pure).
3
+ *
4
+ * Decides which push-opted seekers a newly arrived provider is pushed to (`docs/matchmaking.md`
5
+ * §Fairness — FCFS by `attachedAt`, fan-out bounded by `capacityBudget`). Every cohort member runs the
6
+ * same selection over the same gossip-replicated records and then delivers only to the selected seekers
7
+ * whose slot primary it is, so the cohort as a whole notifies about `capacityBudget` seekers rather than
8
+ * that many per member.
9
+ *
10
+ * Pure: no clock, no I/O. The db-p2p cohort driver decodes the records, keeps the targets it is primary
11
+ * for, coalesces, signs and delivers.
12
+ */
13
+ import type { LocalProviderRegistration, LocalSeekerRegistration } from "./query-eval.js";
14
+ /** A decoded seeker registration held at this cohort, considered as a push target. */
15
+ export type ArrivalPushCandidate = LocalSeekerRegistration;
16
+ /**
17
+ * Seekers to notify about `provider`, longest-waiting first: of the push-opted seekers whose filter the
18
+ * provider matches and that attached no later than it did, the first `capacityBudget` by `attachedAt`
19
+ * (ties broken by `participantId`, so every member computes the same order). Generic so the caller gets
20
+ * back its own richer candidate objects.
21
+ *
22
+ * The `attachedAt` rule exists for a member that receives the whole record set at once (catching up by
23
+ * gossip, or pulling records in a rotation handoff): without it, that member would push every existing
24
+ * provider to every seeker. A provider that attached before a seeker was answerable by that seeker's own
25
+ * first query, and its safety poll still finds it.
26
+ *
27
+ * NOTE: accepted tradeoff — the ranking reads only replicated state, so a seeker already satisfied,
28
+ * finished, or answering `unknown_seeker` to its own primary keeps holding a fan-out slot until its
29
+ * record leaves the cohort (withdraw on finish, or its `seeker_ttl` expiry), under-filling that arrival's fan-out;
30
+ * members whose gossip views differ can also over- or under-fill by a few. Excluding them would mean
31
+ * gossiping per-seeker push state; the seeker's safety poll covers what is missed. Revisit if push
32
+ * under-fill shows up as seekers routinely falling back to the safety poll on a busy topic.
33
+ */
34
+ export declare function selectArrivalPushTargets<S extends ArrivalPushCandidate>(provider: LocalProviderRegistration, seekers: readonly S[]): S[];
35
+ //# sourceMappingURL=arrival-push.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"arrival-push.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/arrival-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1F,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,oBAAoB,EACtE,QAAQ,EAAE,yBAAyB,EACnC,OAAO,EAAE,SAAS,CAAC,EAAE,GACnB,CAAC,EAAE,CASL"}
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Matchmaking — arrival-push fan-out selection (db-core, pure).
3
+ *
4
+ * Decides which push-opted seekers a newly arrived provider is pushed to (`docs/matchmaking.md`
5
+ * §Fairness — FCFS by `attachedAt`, fan-out bounded by `capacityBudget`). Every cohort member runs the
6
+ * same selection over the same gossip-replicated records and then delivers only to the selected seekers
7
+ * whose slot primary it is, so the cohort as a whole notifies about `capacityBudget` seekers rather than
8
+ * that many per member.
9
+ *
10
+ * Pure: no clock, no I/O. The db-p2p cohort driver decodes the records, keeps the targets it is primary
11
+ * for, coalesces, signs and delivers.
12
+ */
13
+ import { matchesFilter } from "./capability-filter.js";
14
+ /**
15
+ * Seekers to notify about `provider`, longest-waiting first: of the push-opted seekers whose filter the
16
+ * provider matches and that attached no later than it did, the first `capacityBudget` by `attachedAt`
17
+ * (ties broken by `participantId`, so every member computes the same order). Generic so the caller gets
18
+ * back its own richer candidate objects.
19
+ *
20
+ * The `attachedAt` rule exists for a member that receives the whole record set at once (catching up by
21
+ * gossip, or pulling records in a rotation handoff): without it, that member would push every existing
22
+ * provider to every seeker. A provider that attached before a seeker was answerable by that seeker's own
23
+ * first query, and its safety poll still finds it.
24
+ *
25
+ * NOTE: accepted tradeoff — the ranking reads only replicated state, so a seeker already satisfied,
26
+ * finished, or answering `unknown_seeker` to its own primary keeps holding a fan-out slot until its
27
+ * record leaves the cohort (withdraw on finish, or its `seeker_ttl` expiry), under-filling that arrival's fan-out;
28
+ * members whose gossip views differ can also over- or under-fill by a few. Excluding them would mean
29
+ * gossiping per-seeker push state; the seeker's safety poll covers what is missed. Revisit if push
30
+ * under-fill shows up as seekers routinely falling back to the safety poll on a busy topic.
31
+ */
32
+ export function selectArrivalPushTargets(provider, seekers) {
33
+ const budget = provider.payload.capacityBudget;
34
+ if (budget === 0) {
35
+ return [];
36
+ }
37
+ return seekers
38
+ .filter((s) => isPushTarget(provider, s))
39
+ .sort(byLongestWaiting)
40
+ .slice(0, budget);
41
+ }
42
+ /** True iff `seeker` holds a push binding, matches `provider`, and was waiting when it arrived. */
43
+ function isPushTarget(provider, seeker) {
44
+ return seeker.payload.pushOnArrival === true
45
+ && seeker.payload.correlationId !== undefined
46
+ && matchesFilter(provider.payload, seeker.payload.filter)
47
+ && provider.attachedAt >= seeker.attachedAt;
48
+ }
49
+ /** Ascending `attachedAt`, then code-unit order of `participantId` (locale-independent, so members agree). */
50
+ function byLongestWaiting(a, b) {
51
+ if (a.attachedAt !== b.attachedAt) {
52
+ return a.attachedAt - b.attachedAt;
53
+ }
54
+ return a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0;
55
+ }
56
+ //# sourceMappingURL=arrival-push.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"arrival-push.js","sourceRoot":"","sources":["../../../src/matchmaking/arrival-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAMvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAmC,EACnC,OAAqB;IAErB,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC;IAC/C,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACX,CAAC;IACD,OAAO,OAAO;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;SACxC,IAAI,CAAC,gBAAgB,CAAC;SACtB,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,mGAAmG;AACnG,SAAS,YAAY,CAAC,QAAmC,EAAE,MAA4B;IACtF,OAAO,MAAM,CAAC,OAAO,CAAC,aAAa,KAAK,IAAI;WACxC,MAAM,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS;WAC1C,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;WACtD,QAAQ,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC;AAC9C,CAAC;AAED,8GAA8G;AAC9G,SAAS,gBAAgB,CAAC,CAAuB,EAAE,CAAuB;IACzE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3F,CAAC"}
@@ -10,8 +10,9 @@
10
10
  * The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
11
11
  * rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
12
12
  * defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
13
- * §Configuration "Defaults validated by simulator"). The `push_*` rows belong to the arrival-push
14
- * path (a separate slice) and are intentionally not modeled here.
13
+ * §Configuration "Defaults validated by simulator"). Of the arrival-push rows, `push_safety_poll_ms` is
14
+ * seeker-side and lives on {@link HangOutConfig}; `push_coalesce_ms` is the one cohort-side knob and
15
+ * lives on {@link ArrivalPushConfig}.
15
16
  */
16
17
  import type { NodeProfile } from "../cohort-topic/tiers.js";
17
18
  /** Provider registration TTL on a Core node (ms). */
@@ -55,9 +56,18 @@ export interface HangOutConfig {
55
56
  readonly contentionFactorCap: number;
56
57
  /** Hang-out poll cadence on the non-push path. */
57
58
  readonly requeryIntervalMs: number;
59
+ /** Sparse safety-poll cadence beneath the pushes, for a seeker that set `pushOnArrival`. */
60
+ readonly pushSafetyPollMs: number;
58
61
  }
59
62
  /** The default hang-out decision config (simulator-validated). */
60
63
  export declare const DEFAULT_HANG_OUT_CONFIG: HangOutConfig;
64
+ /** Cohort-side arrival-push tuning (`docs/matchmaking.md` §Coalescing). */
65
+ export interface ArrivalPushConfig {
66
+ /** Window the pushing member batches fresh matchable arrivals per seeker before flushing one push. */
67
+ readonly coalesceMs: number;
68
+ }
69
+ /** The default arrival-push config. */
70
+ export declare const DEFAULT_ARRIVAL_PUSH_CONFIG: ArrivalPushConfig;
61
71
  /** The full matchmaking config, with the documented defaults. */
62
72
  export interface MatchmakingConfig {
63
73
  readonly providerTtlCoreMs: number;
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,wDAAwD;AACxD,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAI9C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,gHAAgH;AAChH,eAAO,MAAM,0BAA0B,IAAM,CAAC;AAC9C,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,IAAM,CAAC;AAC/C,6GAA6G;AAC7G,eAAO,MAAM,qBAAqB,IAAM,CAAC;AACzC,mHAAmH;AACnH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,qHAAqH;AACrH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,0GAA0G;IAC1G,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,aAGrC,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;CAC3C;AAED,4DAA4D;AAC5D,eAAO,MAAM,0BAA0B,EAAE,iBAOxC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,GAAE,iBAA8C,GAAG,MAAM,CAE1H"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,wDAAwD;AACxD,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAI9C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,gHAAgH;AAChH,eAAO,MAAM,0BAA0B,IAAM,CAAC;AAC9C,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,IAAM,CAAC;AAC/C,6GAA6G;AAC7G,eAAO,MAAM,qBAAqB,IAAM,CAAC;AACzC,mHAAmH;AACnH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,qHAAqH;AACrH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,0GAA0G;IAC1G,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAClC;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,aAIrC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IACjC,sGAAsG;IACtG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,uCAAuC;AACvC,eAAO,MAAM,2BAA2B,EAAE,iBAEzC,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;CAC3C;AAED,4DAA4D;AAC5D,eAAO,MAAM,0BAA0B,EAAE,iBAOxC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,GAAE,iBAA8C,GAAG,MAAM,CAE1H"}
@@ -10,8 +10,9 @@
10
10
  * The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
11
11
  * rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
12
12
  * defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
13
- * §Configuration "Defaults validated by simulator"). The `push_*` rows belong to the arrival-push
14
- * path (a separate slice) and are intentionally not modeled here.
13
+ * §Configuration "Defaults validated by simulator"). Of the arrival-push rows, `push_safety_poll_ms` is
14
+ * seeker-side and lives on {@link HangOutConfig}; `push_coalesce_ms` is the one cohort-side knob and
15
+ * lives on {@link ArrivalPushConfig}.
15
16
  */
16
17
  /** Provider registration TTL on a Core node (ms). */
17
18
  export const PROVIDER_TTL_CORE_MS = 90_000;
@@ -49,6 +50,11 @@ export const PUSH_SAFETY_POLL_MS = 5_000;
49
50
  export const DEFAULT_HANG_OUT_CONFIG = {
50
51
  contentionFactorCap: CONTENTION_FACTOR_CAP,
51
52
  requeryIntervalMs: REQUERY_INTERVAL_MS,
53
+ pushSafetyPollMs: PUSH_SAFETY_POLL_MS,
54
+ };
55
+ /** The default arrival-push config. */
56
+ export const DEFAULT_ARRIVAL_PUSH_CONFIG = {
57
+ coalesceMs: PUSH_COALESCE_MS,
52
58
  };
53
59
  /** The default matchmaking config (this ticket's slice). */
54
60
  export const DEFAULT_MATCHMAKING_CONFIG = {
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AACpC,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACxC,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAC3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,kGAAkG;AAElG,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,gHAAgH;AAChH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAC9C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,6GAA6G;AAC7G,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,mHAAmH;AACnH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,qHAAqH;AACrH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,qGAAqG;AACrG,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAczC,kEAAkE;AAClE,MAAM,CAAC,MAAM,uBAAuB,GAAkB;IACrD,mBAAmB,EAAE,qBAAqB;IAC1C,iBAAiB,EAAE,mBAAmB;CACtC,CAAC;AAYF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC5D,iBAAiB,EAAE,oBAAoB;IACvC,iBAAiB,EAAE,oBAAoB;IACvC,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,qBAAqB;IACzC,yBAAyB,EAAE,4BAA4B;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoB,EAAE,SAA4B,0BAA0B;IACjH,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;AACtF,CAAC"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AACpC,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACxC,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAC3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,kGAAkG;AAElG,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,gHAAgH;AAChH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAC9C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,6GAA6G;AAC7G,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,mHAAmH;AACnH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,qHAAqH;AACrH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,qGAAqG;AACrG,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAgBzC,kEAAkE;AAClE,MAAM,CAAC,MAAM,uBAAuB,GAAkB;IACrD,mBAAmB,EAAE,qBAAqB;IAC1C,iBAAiB,EAAE,mBAAmB;IACtC,gBAAgB,EAAE,mBAAmB;CACrC,CAAC;AAQF,uCAAuC;AACvC,MAAM,CAAC,MAAM,2BAA2B,GAAsB;IAC7D,UAAU,EAAE,gBAAgB;CAC5B,CAAC;AAYF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC5D,iBAAiB,EAAE,oBAAoB;IACvC,iBAAiB,EAAE,oBAAoB;IACvC,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,qBAAqB;IACzC,yBAAyB,EAAE,4BAA4B;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoB,EAAE,SAA4B,0BAA0B;IACjH,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;AACtF,CAAC"}
@@ -4,8 +4,8 @@
4
4
  * See `docs/matchmaking.md`. The db-core layer owns the transport-agnostic pieces: wire codecs +
5
5
  * seeker-side entry re-validation, the stable topic-anchor derivation, configuration, both
6
6
  * registration roles' decision/state (provider attach/renew/self-throttle; seeker short-TTL
7
- * registration), the cohort-side capability filter + pure query evaluation, and the seeker
8
- * hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
7
+ * registration), the cohort-side capability filter + pure query evaluation, the arrival-push fan-out
8
+ * selection, and the seeker hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
9
9
  * (managers, the cohort query handler, the seeker walk client).
10
10
  */
11
11
  export * from "./config.js";
@@ -15,6 +15,7 @@ export * from "./provider.js";
15
15
  export * from "./seeker.js";
16
16
  export * from "./capability-filter.js";
17
17
  export * from "./query-eval.js";
18
+ export * from "./arrival-push.js";
18
19
  export * from "./seeker-walk.js";
19
20
  export * from "./multi-cohort-seeker.js";
20
21
  export * from "./voting-quorum.js";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
@@ -4,8 +4,8 @@
4
4
  * See `docs/matchmaking.md`. The db-core layer owns the transport-agnostic pieces: wire codecs +
5
5
  * seeker-side entry re-validation, the stable topic-anchor derivation, configuration, both
6
6
  * registration roles' decision/state (provider attach/renew/self-throttle; seeker short-TTL
7
- * registration), the cohort-side capability filter + pure query evaluation, and the seeker
8
- * hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
7
+ * registration), the cohort-side capability filter + pure query evaluation, the arrival-push fan-out
8
+ * selection, and the seeker hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
9
9
  * (managers, the cohort query handler, the seeker walk client).
10
10
  */
11
11
  export * from "./config.js";
@@ -15,6 +15,7 @@ export * from "./provider.js";
15
15
  export * from "./seeker.js";
16
16
  export * from "./capability-filter.js";
17
17
  export * from "./query-eval.js";
18
+ export * from "./arrival-push.js";
18
19
  export * from "./seeker-walk.js";
19
20
  export * from "./multi-cohort-seeker.js";
20
21
  export * from "./voting-quorum.js";
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
@@ -24,11 +24,14 @@ export interface MatchmakingSeekerOptions {
24
24
  readonly contactHint: string;
25
25
  /** Optional capability filter (evaluated cohort-side in the next ticket; carried here). */
26
26
  readonly filter?: CapabilityFilter;
27
- /** Opt into arrival pushes; default false (poll path). Consumed by the next ticket. */
27
+ /** Opt into arrival pushes; default false (poll path). */
28
28
  readonly pushOnArrival?: boolean;
29
29
  /** Sign the canonical registration image; resolves the base64url signature. */
30
30
  readonly sign: (payload: Uint8Array) => Promise<string>;
31
- /** 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. */
31
+ /**
32
+ * 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. Sent in the
33
+ * payload when `pushOnArrival` is set, as the id arrival pushes are bound to.
34
+ */
32
35
  readonly correlationId?: Uint8Array;
33
36
  /** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
34
37
  readonly randomBytes?: (n: number) => Uint8Array;
@@ -1 +1 @@
1
- {"version":3,"file":"seeker.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAA0B,MAAM,WAAW,CAAC;AAEzH,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACxC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,6FAA6F;IAC7F,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;IACpC,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;CACjD;AAED,gGAAgG;AAChG,qBAAa,iBAAiB;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2C;gBAEpD,OAAO,EAAE,wBAAwB;IAc7C,kFAAkF;IAC5E,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAiBpD,gFAAgF;IAC1E,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;CAG5C"}
1
+ {"version":3,"file":"seeker.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAA0B,MAAM,WAAW,CAAC;AAEzH,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACxC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;IACpC,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;CACjD;AAED,gGAAgG;AAChG,qBAAa,iBAAiB;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2C;gBAEpD,OAAO,EAAE,wBAAwB;IAc7C,kFAAkF;IAC5E,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAoBpD,gFAAgF;IAC1E,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;CAG5C"}
@@ -14,6 +14,8 @@
14
14
  * Crypto-free: signing is an injected callback, matching {@link MatchmakingProvider}.
15
15
  */
16
16
  import { randomBytes } from "@noble/hashes/utils.js";
17
+ import { bytesToB64url } from "../cohort-topic/wire/codec.js";
18
+ import { CORRELATION_BYTES } from "../cohort-topic/wire/primitives.js";
17
19
  import { seekerSigningPayload, encodeSeekerAppPayload } from "./wire.js";
18
20
  /** Live seeker state + signed-payload builder for one matchmaking topic (registration only). */
19
21
  export class MatchmakingSeeker {
@@ -35,7 +37,7 @@ export class MatchmakingSeeker {
35
37
  this.pushOnArrival = options.pushOnArrival;
36
38
  this.sign = options.sign;
37
39
  const rand = options.randomBytes ?? randomBytes;
38
- this.correlationId = options.correlationId ?? rand(16);
40
+ this.correlationId = options.correlationId ?? rand(CORRELATION_BYTES);
39
41
  }
40
42
  /** Build the signed {@link SeekerAppPayloadV1} for this seeker's registration. */
41
43
  async buildAppPayload() {
@@ -52,6 +54,9 @@ export class MatchmakingSeeker {
52
54
  if (this.pushOnArrival !== undefined) {
53
55
  payload.pushOnArrival = this.pushOnArrival;
54
56
  }
57
+ if (this.pushOnArrival === true) {
58
+ payload.correlationId = bytesToB64url(this.correlationId);
59
+ }
55
60
  return payload;
56
61
  }
57
62
  /** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
@@ -1 +1 @@
1
- {"version":3,"file":"seeker.js","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAkD,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAsBzH,gGAAgG;AAChG,MAAM,OAAO,iBAAiB;IACpB,OAAO,CAAa;IACpB,aAAa,CAAa;IAClB,SAAS,CAAS;IAClB,WAAW,CAAS;IACpB,MAAM,CAAoB;IAC1B,aAAa,CAAW;IACxB,IAAI,CAA2C;IAEhE,YAAY,OAAiC;QAC5C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,UAAU,CAAC,8DAA8D,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,eAAe;QACpB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QACtF,MAAM,OAAO,GAAuB;YACnC,IAAI,EAAE,cAAc;YACpB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS;SACT,CAAC;QACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9B,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QAC5C,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,eAAe;QACpB,OAAO,sBAAsB,CAAC,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;IAC7D,CAAC;CACD"}
1
+ {"version":3,"file":"seeker.js","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAkD,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAyBzH,gGAAgG;AAChG,MAAM,OAAO,iBAAiB;IACpB,OAAO,CAAa;IACpB,aAAa,CAAa;IAClB,SAAS,CAAS;IAClB,WAAW,CAAS;IACpB,MAAM,CAAoB;IAC1B,aAAa,CAAW;IACxB,IAAI,CAA2C;IAEhE,YAAY,OAAiC;QAC5C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,UAAU,CAAC,8DAA8D,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACvE,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,eAAe;QACpB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QACtF,MAAM,OAAO,GAAuB;YACnC,IAAI,EAAE,cAAc;YACpB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS;SACT,CAAC;QACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9B,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QAC5C,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;YACjC,OAAO,CAAC,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,eAAe;QACpB,OAAO,sBAAsB,CAAC,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;IAC7D,CAAC;CACD"}
@@ -11,9 +11,10 @@
11
11
  * which base64url-encodes them on the wire. They are therefore **not** length-framed here — the
12
12
  * cohort-topic `RegisterV1` frame wraps them.
13
13
  *
14
- * 2. **Query-protocol messages** ({@link QueryV1} / {@link QueryReplyV1} / {@link AggregateCountV1})
15
- * sent as standalone RPCs over the matchmaking application protocol. These ride the same
16
- * length-prefixed UTF-8 JSON framing as cohort-topic messages ({@link encodeCohortMessage}).
14
+ * 2. **Standalone RPC messages** — the query protocol ({@link QueryV1} / {@link QueryReplyV1} /
15
+ * {@link AggregateCountV1}) and the arrival push ({@link ArrivalPushV1} / {@link ArrivalPushAckV1})
16
+ * — sent over the matchmaking application protocols. These ride the same length-prefixed UTF-8
17
+ * JSON framing as cohort-topic messages ({@link encodeCohortMessage}).
17
18
  *
18
19
  * Conventions (matching the cohort-topic wire conventions): all JSON, byte fields base64url (no
19
20
  * padding), unix-millisecond timestamps, per-message structural validation on decode. Byte fidelity
@@ -47,6 +48,15 @@ export interface SeekerAppPayloadV1 {
47
48
  contactHint: string;
48
49
  /** Opt into arrival pushes; default false (poll path). */
49
50
  pushOnArrival?: boolean;
51
+ /**
52
+ * The registration id an {@link ArrivalPushV1} is bound to, 16 bytes, base64url. Required when
53
+ * `pushOnArrival` is `true`; accepted and ignored otherwise. Riding in the payload puts it in the
54
+ * cohort's gossip-replicated record, so any member can derive the seeker's push binding after a
55
+ * failover. Deliberately outside {@link seekerSigningPayload} (a forwarded {@link SeekerEntryV1}
56
+ * does not carry it); it is still authenticated, because the cohort admits the payload only inside
57
+ * a peer-key-signed `RegisterV1`, whose signing image covers `appPayload`.
58
+ */
59
+ correlationId?: string;
50
60
  /** base64url. */
51
61
  signature: string;
52
62
  }
@@ -143,6 +153,39 @@ export interface AggregateBucketV1 {
143
153
  /** Log-bucketed. */
144
154
  count: number;
145
155
  }
156
+ /**
157
+ * A cohort member's notification to a push-opted seeker that fresh matchable providers arrived
158
+ * (`docs/matchmaking.md` §Arrival push on provider arrival). Advisory, with the same trust model as
159
+ * {@link QueryReplyV1}: `signature` is the pushing member's single peer-key signature over
160
+ * {@link arrivalPushSigningPayload}, and the seeker re-validates every entry's `registrationSig`
161
+ * ({@link verifyProviderEntry}) before dialing.
162
+ */
163
+ export interface ArrivalPushV1 {
164
+ v: 1;
165
+ /** Topic id, 32 bytes, base64url. */
166
+ topicId: string;
167
+ /** Cohort epoch the push was computed under, 32 bytes, base64url. */
168
+ cohortEpoch: string;
169
+ /** The seeker registration this push is bound to ({@link SeekerAppPayloadV1.correlationId}), 16 bytes, base64url. */
170
+ correlationId: string;
171
+ /** The fresh, filter-matched, coalesced batch: `1..QUERY_LIMIT_MAX` entries. */
172
+ providers: ProviderEntryV1[];
173
+ /** Current traffic snapshot, so the seeker can re-run its hang-out math without a poll. */
174
+ topicTraffic: TopicTrafficV1;
175
+ /** The pushing member's single peer-key signature (NOT threshold), base64url. */
176
+ signature: string;
177
+ }
178
+ /** The outcomes a seeker may report for an {@link ArrivalPushV1}. */
179
+ export declare const ARRIVAL_PUSH_RESULTS: readonly ["ok", "unknown_seeker"];
180
+ export type ArrivalPushResult = typeof ARRIVAL_PUSH_RESULTS[number];
181
+ /**
182
+ * A seeker's reply to an {@link ArrivalPushV1}. `unknown_seeker` says the push's `correlationId` is not
183
+ * the seeker's current registration (it re-registered, or finished), so the pusher drops the binding.
184
+ */
185
+ export interface ArrivalPushAckV1 {
186
+ v: 1;
187
+ result: ArrivalPushResult;
188
+ }
146
189
  /** Ceiling for an opaque app payload (provider/seeker), guarding decode allocation. */
147
190
  export declare const DEFAULT_MAX_APP_PAYLOAD_BYTES: number;
148
191
  /** Narrow an already-parsed value to {@link ProviderAppPayloadV1}, throwing on any defect. */
@@ -173,6 +216,10 @@ export declare function validateQueryV1(value: unknown): QueryV1;
173
216
  export declare function validateQueryReplyV1(value: unknown): QueryReplyV1;
174
217
  /** Narrow an already-parsed value to {@link AggregateCountV1}, throwing on any defect. */
175
218
  export declare function validateAggregateCountV1(value: unknown): AggregateCountV1;
219
+ /** Narrow an already-parsed value to {@link ArrivalPushV1}, throwing on any defect. */
220
+ export declare function validateArrivalPushV1(value: unknown): ArrivalPushV1;
221
+ /** Narrow an already-parsed value to {@link ArrivalPushAckV1}, throwing on any defect. */
222
+ export declare function validateArrivalPushAckV1(value: unknown): ArrivalPushAckV1;
176
223
  /** Encode a {@link QueryV1} as a length-prefixed UTF-8 JSON frame. */
177
224
  export declare function encodeQueryV1(msg: QueryV1, maxMessageBytes?: number): Uint8Array;
178
225
  /** Decode a length-prefixed {@link QueryV1} frame. */
@@ -185,6 +232,14 @@ export declare function decodeQueryReplyV1(bytes: Uint8Array, maxMessageBytes?:
185
232
  export declare function encodeAggregateCountV1(msg: AggregateCountV1, maxMessageBytes?: number): Uint8Array;
186
233
  /** Decode a length-prefixed {@link AggregateCountV1} frame. */
187
234
  export declare function decodeAggregateCountV1(bytes: Uint8Array, maxMessageBytes?: number): AggregateCountV1;
235
+ /** Encode an {@link ArrivalPushV1} as a length-prefixed UTF-8 JSON frame. */
236
+ export declare function encodeArrivalPushV1(msg: ArrivalPushV1, maxMessageBytes?: number): Uint8Array;
237
+ /** Decode a length-prefixed {@link ArrivalPushV1} frame. */
238
+ export declare function decodeArrivalPushV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushV1;
239
+ /** Encode an {@link ArrivalPushAckV1} as a length-prefixed UTF-8 JSON frame. */
240
+ export declare function encodeArrivalPushAckV1(msg: ArrivalPushAckV1, maxMessageBytes?: number): Uint8Array;
241
+ /** Decode a length-prefixed {@link ArrivalPushAckV1} frame. */
242
+ export declare function decodeArrivalPushAckV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushAckV1;
188
243
  /**
189
244
  * Canonical signed byte image of a provider registration — `(topicId, capabilities, capacityBudget)`
190
245
  * per `docs/matchmaking.md` §Wire formats.
@@ -237,6 +292,14 @@ export declare function verifySeekerEntry(topicId: Uint8Array, entry: SeekerEntr
237
292
  * advisory per-entry signatures.
238
293
  */
239
294
  export declare function queryReplySigningPayload(reply: Omit<QueryReplyV1, "signature">): Uint8Array;
295
+ /**
296
+ * Canonical signed byte image of an {@link ArrivalPushV1} — the pushing member's single-member
297
+ * signature, mirroring {@link queryReplySigningPayload}. It binds the topic, epoch, the seeker
298
+ * registration the push is addressed to, the traffic snapshot, and the providers' participant ids
299
+ * (order-sensitive); the per-entry signatures stay outside it, since the seeker re-validates each entry
300
+ * on its own ({@link verifyProviderEntry}).
301
+ */
302
+ export declare function arrivalPushSigningPayload(unsigned: Omit<ArrivalPushV1, "signature">): Uint8Array;
240
303
  /**
241
304
  * Log-bucket a raw provider count for an {@link AggregateCountV1} bucket: the largest power of two
242
305
  * `<= n` (and `0` for `n <= 0`). The root reports bucketed, not exact, per-shard populations
@@ -1 +1 @@
1
- {"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/wire.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/wire.ts"],"names":[],"mappings":"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"}
@@ -11,9 +11,10 @@
11
11
  * which base64url-encodes them on the wire. They are therefore **not** length-framed here — the
12
12
  * cohort-topic `RegisterV1` frame wraps them.
13
13
  *
14
- * 2. **Query-protocol messages** ({@link QueryV1} / {@link QueryReplyV1} / {@link AggregateCountV1})
15
- * sent as standalone RPCs over the matchmaking application protocol. These ride the same
16
- * length-prefixed UTF-8 JSON framing as cohort-topic messages ({@link encodeCohortMessage}).
14
+ * 2. **Standalone RPC messages** — the query protocol ({@link QueryV1} / {@link QueryReplyV1} /
15
+ * {@link AggregateCountV1}) and the arrival push ({@link ArrivalPushV1} / {@link ArrivalPushAckV1})
16
+ * — sent over the matchmaking application protocols. These ride the same length-prefixed UTF-8
17
+ * JSON framing as cohort-topic messages ({@link encodeCohortMessage}).
17
18
  *
18
19
  * Conventions (matching the cohort-topic wire conventions): all JSON, byte fields base64url (no
19
20
  * padding), unix-millisecond timestamps, per-message structural validation on decode. Byte fidelity
@@ -22,8 +23,10 @@
22
23
  * be unit-tested against fixtures.
23
24
  */
24
25
  import { bytesToB64url, b64urlToBytes, decodeCohortMessage, encodeCohortMessage, DEFAULT_MAX_MESSAGE_BYTES, } from "../cohort-topic/wire/codec.js";
25
- import { asObject, b64urlField, b64urlFixedLen, COORD_BYTES, failWire as fail, optBool, optFiniteNumber, reqBool, reqFiniteNumber, reqIntInRange, reqString, reqStringArray, requireV1, } from "../cohort-topic/wire/primitives.js";
26
+ import { asObject, b64urlField, b64urlFixedLen, COORD_BYTES, CORRELATION_BYTES, failWire as fail, optBool, optFiniteNumber, optString, reqBool, reqEnum, reqFiniteNumber, reqIntInRange, reqString, reqStringArray, requireV1, } from "../cohort-topic/wire/primitives.js";
26
27
  import { QUERY_LIMIT_MAX } from "./config.js";
28
+ /** The outcomes a seeker may report for an {@link ArrivalPushV1}. */
29
+ export const ARRIVAL_PUSH_RESULTS = ["ok", "unknown_seeker"];
27
30
  // --- matchmaking-local wire state (generic validation primitives live in cohort-topic/wire/primitives.js) ---
28
31
  const utf8Encoder = new TextEncoder();
29
32
  // Built on first use, not at module load: Hermes (React Native) has no native `TextDecoder`, so a
@@ -85,6 +88,13 @@ export function validateSeekerAppPayloadV1(value) {
85
88
  if (pushOnArrival !== undefined) {
86
89
  out.pushOnArrival = pushOnArrival;
87
90
  }
91
+ const correlationId = optString(obj, "correlationId", what);
92
+ if (correlationId !== undefined) {
93
+ out.correlationId = b64urlFixedLen(correlationId, "correlationId", CORRELATION_BYTES, what);
94
+ }
95
+ if (out.pushOnArrival === true && out.correlationId === undefined) {
96
+ fail(`${what}: field "correlationId" is required when "pushOnArrival" is true`);
97
+ }
88
98
  return out;
89
99
  }
90
100
  /** Serialize a {@link ProviderAppPayloadV1} to the opaque UTF-8 JSON bytes for `RegisterV1.appPayload`. */
@@ -254,6 +264,32 @@ export function validateAggregateCountV1(value) {
254
264
  cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
255
265
  };
256
266
  }
267
+ /** Narrow an already-parsed value to {@link ArrivalPushV1}, throwing on any defect. */
268
+ export function validateArrivalPushV1(value) {
269
+ const what = "ArrivalPushV1";
270
+ const obj = asObject(value, what);
271
+ requireV1(obj, what);
272
+ const providers = obj["providers"];
273
+ if (!Array.isArray(providers) || providers.length < 1 || providers.length > QUERY_LIMIT_MAX) {
274
+ fail(`${what}: field "providers" must be an array of 1..${QUERY_LIMIT_MAX} entries`);
275
+ }
276
+ return {
277
+ v: 1,
278
+ topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
279
+ cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
280
+ correlationId: b64urlFixedLen(reqString(obj, "correlationId", what), "correlationId", CORRELATION_BYTES, what),
281
+ providers: providers.map(validateProviderEntryV1),
282
+ topicTraffic: validateTopicTrafficV1(obj["topicTraffic"], `${what}.topicTraffic`),
283
+ signature: b64urlField(reqString(obj, "signature", what), "signature", what),
284
+ };
285
+ }
286
+ /** Narrow an already-parsed value to {@link ArrivalPushAckV1}, throwing on any defect. */
287
+ export function validateArrivalPushAckV1(value) {
288
+ const what = "ArrivalPushAckV1";
289
+ const obj = asObject(value, what);
290
+ requireV1(obj, what);
291
+ return { v: 1, result: reqEnum(obj, "result", ARRIVAL_PUSH_RESULTS, what) };
292
+ }
257
293
  /** Encode a {@link QueryV1} as a length-prefixed UTF-8 JSON frame. */
258
294
  export function encodeQueryV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
259
295
  return encodeCohortMessage(validateQueryV1(msg), maxMessageBytes);
@@ -278,6 +314,22 @@ export function encodeAggregateCountV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAG
278
314
  export function decodeAggregateCountV1(bytes, maxMessageBytes) {
279
315
  return validateAggregateCountV1(decodeCohortMessage(bytes, maxMessageBytes));
280
316
  }
317
+ /** Encode an {@link ArrivalPushV1} as a length-prefixed UTF-8 JSON frame. */
318
+ export function encodeArrivalPushV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
319
+ return encodeCohortMessage(validateArrivalPushV1(msg), maxMessageBytes);
320
+ }
321
+ /** Decode a length-prefixed {@link ArrivalPushV1} frame. */
322
+ export function decodeArrivalPushV1(bytes, maxMessageBytes) {
323
+ return validateArrivalPushV1(decodeCohortMessage(bytes, maxMessageBytes));
324
+ }
325
+ /** Encode an {@link ArrivalPushAckV1} as a length-prefixed UTF-8 JSON frame. */
326
+ export function encodeArrivalPushAckV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
327
+ return encodeCohortMessage(validateArrivalPushAckV1(msg), maxMessageBytes);
328
+ }
329
+ /** Decode a length-prefixed {@link ArrivalPushAckV1} frame. */
330
+ export function decodeArrivalPushAckV1(bytes, maxMessageBytes) {
331
+ return validateArrivalPushAckV1(decodeCohortMessage(bytes, maxMessageBytes));
332
+ }
281
333
  // --- canonical participant-signature payloads (provider/seeker registration sigs) ---
282
334
  /**
283
335
  * Canonical signed byte image of a provider registration — `(topicId, capabilities, capacityBudget)`
@@ -360,17 +412,33 @@ export function queryReplySigningPayload(reply) {
360
412
  reply.v,
361
413
  reply.cohortEpoch,
362
414
  reply.truncated,
363
- [
364
- reply.topicTraffic.windowSeconds,
365
- reply.topicTraffic.arrivalsPerMin,
366
- reply.topicTraffic.queriesPerMin,
367
- reply.topicTraffic.directParticipants,
368
- reply.topicTraffic.childCohortCount,
369
- ],
415
+ topicTrafficImage(reply.topicTraffic),
370
416
  (reply.providers ?? []).map((p) => p.participantId),
371
417
  (reply.seekers ?? []).map((s) => s.participantId),
372
418
  ]));
373
419
  }
420
+ /**
421
+ * Canonical signed byte image of an {@link ArrivalPushV1} — the pushing member's single-member
422
+ * signature, mirroring {@link queryReplySigningPayload}. It binds the topic, epoch, the seeker
423
+ * registration the push is addressed to, the traffic snapshot, and the providers' participant ids
424
+ * (order-sensitive); the per-entry signatures stay outside it, since the seeker re-validates each entry
425
+ * on its own ({@link verifyProviderEntry}).
426
+ */
427
+ export function arrivalPushSigningPayload(unsigned) {
428
+ return utf8Encoder.encode(JSON.stringify([
429
+ "ArrivalPushV1",
430
+ unsigned.v,
431
+ unsigned.topicId,
432
+ unsigned.cohortEpoch,
433
+ unsigned.correlationId,
434
+ topicTrafficImage(unsigned.topicTraffic),
435
+ unsigned.providers.map((p) => p.participantId),
436
+ ]));
437
+ }
438
+ /** The traffic snapshot as an explicitly ordered array, shared by the single-member signing images. */
439
+ function topicTrafficImage(t) {
440
+ return [t.windowSeconds, t.arrivalsPerMin, t.queriesPerMin, t.directParticipants, t.childCohortCount];
441
+ }
374
442
  // --- aggregate-count log-bucketing + canonical threshold-signing image (multi-cohort sweep) ---
375
443
  /**
376
444
  * Log-bucket a raw provider count for an {@link AggregateCountV1} bucket: the largest power of two