@optimystic/db-core 1.5.0 → 1.5.1

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 (152) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. package/src/utility/pending.ts +43 -43
@@ -1,123 +1,123 @@
1
- /**
2
- * Matchmaking — provider decision/state (db-core, transport-agnostic).
3
- *
4
- * A {@link MatchmakingProvider} owns the live provider state for one topic: its capability tags, its
5
- * current `capacityBudget`, and a correlation id (registration identity; not bound into the
6
- * matchmaking signature — see {@link providerSigningPayload} option (b)). It builds the
7
- * signed {@link ProviderAppPayloadV1} (and the opaque bytes for the cohort-topic
8
- * `RegisterV1.appPayload` slot) that the db-p2p `provider-manager` registers at cohort-topic tier
9
- * **T2** (`docs/matchmaking.md` §Provider registration).
10
- *
11
- * It is crypto-free: signing is an injected callback (db-p2p supplies the libp2p peer key), matching
12
- * the cohort-topic {@link import("../cohort-topic/service.js").ParticipantSigner} pattern.
13
- *
14
- * Self-throttling (`docs/matchmaking.md` §Provider self-throttling) is expressed here as state:
15
- * - **Signal full** — {@link MatchmakingProvider.signalFull} sets `capacityBudget = 0`; the provider
16
- * stays listed as "available but at capacity". The manager re-registers to push the new payload
17
- * (the cohort-topic `RenewV1` carries no `appPayload`, so a capacity change is a re-register, not a
18
- * ping — see the implement handoff).
19
- * - **Withdraw** — {@link MatchmakingProvider.markWithdrawn} records intent; the manager stops
20
- * renewing so the record ages out by TTL. Withdrawal is an **optimization, not a correctness
21
- * requirement** (§Provider self-throttling, GROUNDING resolution): a non-withdrawn registration is
22
- * bounded by TTL eviction.
23
- */
24
-
25
- import { randomBytes } from "@noble/hashes/utils.js";
26
- import { providerSigningPayload, type ProviderAppPayloadV1, encodeProviderAppPayload } from "./wire.js";
27
-
28
- /** Construction inputs for a {@link MatchmakingProvider}. */
29
- export interface MatchmakingProviderOptions {
30
- /** The matchmaking topic this provider serves (from {@link import("./topic-anchor.js").MatchTopicAnchor}). */
31
- readonly topicId: Uint8Array;
32
- /** Application-defined capability tags. */
33
- readonly capabilities: readonly string[];
34
- /** Initial concurrent-task budget (integer `>= 0`). */
35
- readonly capacityBudget: number;
36
- /** Multiaddr or PeerId-based callback. */
37
- readonly contactHint: string;
38
- /** Optional soft expiry hint (unix ms). */
39
- readonly serviceUntil?: number;
40
- /** Sign the canonical registration image; resolves the base64url signature. */
41
- readonly sign: (payload: Uint8Array) => Promise<string>;
42
- /** 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. */
43
- readonly correlationId?: Uint8Array;
44
- /** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
45
- readonly randomBytes?: (n: number) => Uint8Array;
46
- }
47
-
48
- /** Live provider state + signed-payload builder for one matchmaking topic. */
49
- export class MatchmakingProvider {
50
- readonly topicId: Uint8Array;
51
- readonly correlationId: Uint8Array;
52
- private readonly capabilities: readonly string[];
53
- private readonly contactHint: string;
54
- private readonly serviceUntil?: number;
55
- private readonly sign: (payload: Uint8Array) => Promise<string>;
56
- private capacity: number;
57
- private withdrawnFlag = false;
58
-
59
- constructor(options: MatchmakingProviderOptions) {
60
- this.topicId = options.topicId;
61
- this.capabilities = [...options.capabilities];
62
- this.contactHint = options.contactHint;
63
- this.serviceUntil = options.serviceUntil;
64
- this.sign = options.sign;
65
- this.capacity = requireBudget(options.capacityBudget);
66
- const rand = options.randomBytes ?? randomBytes;
67
- this.correlationId = options.correlationId ?? rand(16);
68
- }
69
-
70
- /** Current concurrent-task budget; `0` means "listed but full". */
71
- get capacityBudget(): number {
72
- return this.capacity;
73
- }
74
-
75
- /** True once {@link markWithdrawn} has been called (the manager should stop renewing). */
76
- get withdrawn(): boolean {
77
- return this.withdrawnFlag;
78
- }
79
-
80
- /** Set the live budget (integer `>= 0`). The next built payload reflects it. */
81
- setCapacity(budget: number): void {
82
- this.capacity = requireBudget(budget);
83
- }
84
-
85
- /** Signal "available but at capacity" by setting `capacityBudget = 0` (§Provider self-throttling). */
86
- signalFull(): void {
87
- this.capacity = 0;
88
- }
89
-
90
- /** Record withdrawal intent; the manager stops renewing so the record TTL-expires (optimization). */
91
- markWithdrawn(): void {
92
- this.withdrawnFlag = true;
93
- }
94
-
95
- /** Build the signed {@link ProviderAppPayloadV1} reflecting the current capacity. */
96
- async buildAppPayload(): Promise<ProviderAppPayloadV1> {
97
- const signature = await this.sign(providerSigningPayload(this.topicId, this.capabilities, this.capacity));
98
- const payload: ProviderAppPayloadV1 = {
99
- kind: "match-provider",
100
- capabilities: [...this.capabilities],
101
- capacityBudget: this.capacity,
102
- contactHint: this.contactHint,
103
- signature,
104
- };
105
- if (this.serviceUntil !== undefined) {
106
- payload.serviceUntil = this.serviceUntil;
107
- }
108
- return payload;
109
- }
110
-
111
- /** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
112
- async appPayloadBytes(): Promise<Uint8Array> {
113
- return encodeProviderAppPayload(await this.buildAppPayload());
114
- }
115
- }
116
-
117
- /** Validate a capacity budget is an integer `>= 0`. */
118
- function requireBudget(budget: number): number {
119
- if (!Number.isInteger(budget) || budget < 0) {
120
- throw new RangeError(`matchmaking provider: capacityBudget must be an integer >= 0, got ${budget}`);
121
- }
122
- return budget;
123
- }
1
+ /**
2
+ * Matchmaking — provider decision/state (db-core, transport-agnostic).
3
+ *
4
+ * A {@link MatchmakingProvider} owns the live provider state for one topic: its capability tags, its
5
+ * current `capacityBudget`, and a correlation id (registration identity; not bound into the
6
+ * matchmaking signature — see {@link providerSigningPayload} option (b)). It builds the
7
+ * signed {@link ProviderAppPayloadV1} (and the opaque bytes for the cohort-topic
8
+ * `RegisterV1.appPayload` slot) that the db-p2p `provider-manager` registers at cohort-topic tier
9
+ * **T2** (`docs/matchmaking.md` §Provider registration).
10
+ *
11
+ * It is crypto-free: signing is an injected callback (db-p2p supplies the libp2p peer key), matching
12
+ * the cohort-topic {@link import("../cohort-topic/service.js").ParticipantSigner} pattern.
13
+ *
14
+ * Self-throttling (`docs/matchmaking.md` §Provider self-throttling) is expressed here as state:
15
+ * - **Signal full** — {@link MatchmakingProvider.signalFull} sets `capacityBudget = 0`; the provider
16
+ * stays listed as "available but at capacity". The manager re-registers to push the new payload
17
+ * (the cohort-topic `RenewV1` carries no `appPayload`, so a capacity change is a re-register, not a
18
+ * ping — see the implement handoff).
19
+ * - **Withdraw** — {@link MatchmakingProvider.markWithdrawn} records intent; the manager stops
20
+ * renewing so the record ages out by TTL. Withdrawal is an **optimization, not a correctness
21
+ * requirement** (§Provider self-throttling, GROUNDING resolution): a non-withdrawn registration is
22
+ * bounded by TTL eviction.
23
+ */
24
+
25
+ import { randomBytes } from "@noble/hashes/utils.js";
26
+ import { providerSigningPayload, type ProviderAppPayloadV1, encodeProviderAppPayload } from "./wire.js";
27
+
28
+ /** Construction inputs for a {@link MatchmakingProvider}. */
29
+ export interface MatchmakingProviderOptions {
30
+ /** The matchmaking topic this provider serves (from {@link import("./topic-anchor.js").MatchTopicAnchor}). */
31
+ readonly topicId: Uint8Array;
32
+ /** Application-defined capability tags. */
33
+ readonly capabilities: readonly string[];
34
+ /** Initial concurrent-task budget (integer `>= 0`). */
35
+ readonly capacityBudget: number;
36
+ /** Multiaddr or PeerId-based callback. */
37
+ readonly contactHint: string;
38
+ /** Optional soft expiry hint (unix ms). */
39
+ readonly serviceUntil?: number;
40
+ /** Sign the canonical registration image; resolves the base64url signature. */
41
+ readonly sign: (payload: Uint8Array) => Promise<string>;
42
+ /** 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. */
43
+ readonly correlationId?: Uint8Array;
44
+ /** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
45
+ readonly randomBytes?: (n: number) => Uint8Array;
46
+ }
47
+
48
+ /** Live provider state + signed-payload builder for one matchmaking topic. */
49
+ export class MatchmakingProvider {
50
+ readonly topicId: Uint8Array;
51
+ readonly correlationId: Uint8Array;
52
+ private readonly capabilities: readonly string[];
53
+ private readonly contactHint: string;
54
+ private readonly serviceUntil?: number;
55
+ private readonly sign: (payload: Uint8Array) => Promise<string>;
56
+ private capacity: number;
57
+ private withdrawnFlag = false;
58
+
59
+ constructor(options: MatchmakingProviderOptions) {
60
+ this.topicId = options.topicId;
61
+ this.capabilities = [...options.capabilities];
62
+ this.contactHint = options.contactHint;
63
+ this.serviceUntil = options.serviceUntil;
64
+ this.sign = options.sign;
65
+ this.capacity = requireBudget(options.capacityBudget);
66
+ const rand = options.randomBytes ?? randomBytes;
67
+ this.correlationId = options.correlationId ?? rand(16);
68
+ }
69
+
70
+ /** Current concurrent-task budget; `0` means "listed but full". */
71
+ get capacityBudget(): number {
72
+ return this.capacity;
73
+ }
74
+
75
+ /** True once {@link markWithdrawn} has been called (the manager should stop renewing). */
76
+ get withdrawn(): boolean {
77
+ return this.withdrawnFlag;
78
+ }
79
+
80
+ /** Set the live budget (integer `>= 0`). The next built payload reflects it. */
81
+ setCapacity(budget: number): void {
82
+ this.capacity = requireBudget(budget);
83
+ }
84
+
85
+ /** Signal "available but at capacity" by setting `capacityBudget = 0` (§Provider self-throttling). */
86
+ signalFull(): void {
87
+ this.capacity = 0;
88
+ }
89
+
90
+ /** Record withdrawal intent; the manager stops renewing so the record TTL-expires (optimization). */
91
+ markWithdrawn(): void {
92
+ this.withdrawnFlag = true;
93
+ }
94
+
95
+ /** Build the signed {@link ProviderAppPayloadV1} reflecting the current capacity. */
96
+ async buildAppPayload(): Promise<ProviderAppPayloadV1> {
97
+ const signature = await this.sign(providerSigningPayload(this.topicId, this.capabilities, this.capacity));
98
+ const payload: ProviderAppPayloadV1 = {
99
+ kind: "match-provider",
100
+ capabilities: [...this.capabilities],
101
+ capacityBudget: this.capacity,
102
+ contactHint: this.contactHint,
103
+ signature,
104
+ };
105
+ if (this.serviceUntil !== undefined) {
106
+ payload.serviceUntil = this.serviceUntil;
107
+ }
108
+ return payload;
109
+ }
110
+
111
+ /** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
112
+ async appPayloadBytes(): Promise<Uint8Array> {
113
+ return encodeProviderAppPayload(await this.buildAppPayload());
114
+ }
115
+ }
116
+
117
+ /** Validate a capacity budget is an integer `>= 0`. */
118
+ function requireBudget(budget: number): number {
119
+ if (!Number.isInteger(budget) || budget < 0) {
120
+ throw new RangeError(`matchmaking provider: capacityBudget must be an integer >= 0, got ${budget}`);
121
+ }
122
+ return budget;
123
+ }
@@ -1,105 +1,105 @@
1
- /**
2
- * Matchmaking — pure `QueryV1` evaluation (db-core, transport-agnostic).
3
- *
4
- * The cohort-side query handler (`db-p2p/src/matchmaking/query-handler.ts`) decodes its local
5
- * registration records into the {@link LocalProviderRegistration} / {@link LocalSeekerRegistration}
6
- * shapes below and hands them here; this module performs the *advisory* selection that
7
- * `docs/matchmaking.md` §Seeker query / §Capability filter specify:
8
- *
9
- * - Providers are filtered through {@link matchesFilter} (when `includeProviders`).
10
- * - Each included set is truncated to `query.limit` (`<= query_limit_max`, enforced on decode in
11
- * `wire.ts`); {@link QueryEvalResult.truncated} is set when *any* included set had more matches than
12
- * `limit` allowed, so the seeker knows to re-query a sibling cohort.
13
- * - The forwarded entries carry the provider/seeker's own `registrationSig` verbatim, so the seeker
14
- * re-validates each one (`verifyProviderEntry`) — the cohort vouches only for the *set it held*.
15
- *
16
- * Pure: no I/O, no clock, no crypto. The db-p2p handler attaches `topicTraffic` / `cohortEpoch` and
17
- * the primary's reply signature.
18
- */
19
-
20
- import { matchesFilter } from "./capability-filter.js";
21
- import type { ProviderAppPayloadV1, SeekerAppPayloadV1, ProviderEntryV1, SeekerEntryV1, QueryV1 } from "./wire.js";
22
-
23
- /** A decoded local provider registration held by the cohort, ready for {@link evaluateQuery}. */
24
- export interface LocalProviderRegistration {
25
- /** The provider's peer-id string — the entry's `participantId` AND the `registrationSig` signer. */
26
- readonly participantId: string;
27
- /** Unix ms the registration first attached (forwarded verbatim for seeker FCFS ordering). */
28
- readonly attachedAt: number;
29
- /** The decoded, validated provider app payload (capabilities, budget, contact, signature). */
30
- readonly payload: ProviderAppPayloadV1;
31
- }
32
-
33
- /** A decoded local seeker registration held by the cohort (collective-assembly discovery). */
34
- export interface LocalSeekerRegistration {
35
- readonly participantId: string;
36
- readonly attachedAt: number;
37
- readonly payload: SeekerAppPayloadV1;
38
- }
39
-
40
- /** The selected entries for a {@link QueryReplyV1} body (the db-p2p handler signs + frames it). */
41
- export interface QueryEvalResult {
42
- readonly providers?: ProviderEntryV1[];
43
- readonly seekers?: SeekerEntryV1[];
44
- /** `true` when an included set had more matches than `query.limit` allowed (re-query hint). */
45
- readonly truncated: boolean;
46
- }
47
-
48
- /** Build a forwarded {@link ProviderEntryV1} from a local registration (signature forwarded verbatim). */
49
- export function providerEntryOf(reg: LocalProviderRegistration): ProviderEntryV1 {
50
- return {
51
- participantId: reg.participantId,
52
- capabilities: [...reg.payload.capabilities],
53
- capacityBudget: reg.payload.capacityBudget,
54
- contactHint: reg.payload.contactHint,
55
- attachedAt: reg.attachedAt,
56
- registrationSig: reg.payload.signature,
57
- };
58
- }
59
-
60
- /** Build a forwarded {@link SeekerEntryV1} from a local registration (signature forwarded verbatim). */
61
- export function seekerEntryOf(reg: LocalSeekerRegistration): SeekerEntryV1 {
62
- return {
63
- participantId: reg.participantId,
64
- wantCount: reg.payload.wantCount,
65
- contactHint: reg.payload.contactHint,
66
- attachedAt: reg.attachedAt,
67
- registrationSig: reg.payload.signature,
68
- };
69
- }
70
-
71
- /**
72
- * Evaluate `query` against the cohort's locally-held registrations: filter providers, optionally include
73
- * seekers, truncate each included set to `query.limit`. Inputs are returned in `attachedAt` order
74
- * (oldest first) so truncation keeps the longest-waiting registrations — the FCFS bias the arrival-push
75
- * fairness rule also uses (`docs/matchmaking.md` §Fairness).
76
- */
77
- export function evaluateQuery(
78
- query: QueryV1,
79
- providers: readonly LocalProviderRegistration[],
80
- seekers: readonly LocalSeekerRegistration[],
81
- ): QueryEvalResult {
82
- let truncated = false;
83
- const result: { providers?: ProviderEntryV1[]; seekers?: SeekerEntryV1[]; truncated: boolean } = { truncated: false };
84
-
85
- if (query.includeProviders) {
86
- const matched = providers
87
- .filter((reg) => matchesFilter(reg.payload, query.filter))
88
- .sort((a, b) => a.attachedAt - b.attachedAt);
89
- if (matched.length > query.limit) {
90
- truncated = true;
91
- }
92
- result.providers = matched.slice(0, query.limit).map(providerEntryOf);
93
- }
94
-
95
- if (query.includeSeekers) {
96
- const ordered = [...seekers].sort((a, b) => a.attachedAt - b.attachedAt);
97
- if (ordered.length > query.limit) {
98
- truncated = true;
99
- }
100
- result.seekers = ordered.slice(0, query.limit).map(seekerEntryOf);
101
- }
102
-
103
- result.truncated = truncated;
104
- return result;
105
- }
1
+ /**
2
+ * Matchmaking — pure `QueryV1` evaluation (db-core, transport-agnostic).
3
+ *
4
+ * The cohort-side query handler (`db-p2p/src/matchmaking/query-handler.ts`) decodes its local
5
+ * registration records into the {@link LocalProviderRegistration} / {@link LocalSeekerRegistration}
6
+ * shapes below and hands them here; this module performs the *advisory* selection that
7
+ * `docs/matchmaking.md` §Seeker query / §Capability filter specify:
8
+ *
9
+ * - Providers are filtered through {@link matchesFilter} (when `includeProviders`).
10
+ * - Each included set is truncated to `query.limit` (`<= query_limit_max`, enforced on decode in
11
+ * `wire.ts`); {@link QueryEvalResult.truncated} is set when *any* included set had more matches than
12
+ * `limit` allowed, so the seeker knows to re-query a sibling cohort.
13
+ * - The forwarded entries carry the provider/seeker's own `registrationSig` verbatim, so the seeker
14
+ * re-validates each one (`verifyProviderEntry`) — the cohort vouches only for the *set it held*.
15
+ *
16
+ * Pure: no I/O, no clock, no crypto. The db-p2p handler attaches `topicTraffic` / `cohortEpoch` and
17
+ * the primary's reply signature.
18
+ */
19
+
20
+ import { matchesFilter } from "./capability-filter.js";
21
+ import type { ProviderAppPayloadV1, SeekerAppPayloadV1, ProviderEntryV1, SeekerEntryV1, QueryV1 } from "./wire.js";
22
+
23
+ /** A decoded local provider registration held by the cohort, ready for {@link evaluateQuery}. */
24
+ export interface LocalProviderRegistration {
25
+ /** The provider's peer-id string — the entry's `participantId` AND the `registrationSig` signer. */
26
+ readonly participantId: string;
27
+ /** Unix ms the registration first attached (forwarded verbatim for seeker FCFS ordering). */
28
+ readonly attachedAt: number;
29
+ /** The decoded, validated provider app payload (capabilities, budget, contact, signature). */
30
+ readonly payload: ProviderAppPayloadV1;
31
+ }
32
+
33
+ /** A decoded local seeker registration held by the cohort (collective-assembly discovery). */
34
+ export interface LocalSeekerRegistration {
35
+ readonly participantId: string;
36
+ readonly attachedAt: number;
37
+ readonly payload: SeekerAppPayloadV1;
38
+ }
39
+
40
+ /** The selected entries for a {@link QueryReplyV1} body (the db-p2p handler signs + frames it). */
41
+ export interface QueryEvalResult {
42
+ readonly providers?: ProviderEntryV1[];
43
+ readonly seekers?: SeekerEntryV1[];
44
+ /** `true` when an included set had more matches than `query.limit` allowed (re-query hint). */
45
+ readonly truncated: boolean;
46
+ }
47
+
48
+ /** Build a forwarded {@link ProviderEntryV1} from a local registration (signature forwarded verbatim). */
49
+ export function providerEntryOf(reg: LocalProviderRegistration): ProviderEntryV1 {
50
+ return {
51
+ participantId: reg.participantId,
52
+ capabilities: [...reg.payload.capabilities],
53
+ capacityBudget: reg.payload.capacityBudget,
54
+ contactHint: reg.payload.contactHint,
55
+ attachedAt: reg.attachedAt,
56
+ registrationSig: reg.payload.signature,
57
+ };
58
+ }
59
+
60
+ /** Build a forwarded {@link SeekerEntryV1} from a local registration (signature forwarded verbatim). */
61
+ export function seekerEntryOf(reg: LocalSeekerRegistration): SeekerEntryV1 {
62
+ return {
63
+ participantId: reg.participantId,
64
+ wantCount: reg.payload.wantCount,
65
+ contactHint: reg.payload.contactHint,
66
+ attachedAt: reg.attachedAt,
67
+ registrationSig: reg.payload.signature,
68
+ };
69
+ }
70
+
71
+ /**
72
+ * Evaluate `query` against the cohort's locally-held registrations: filter providers, optionally include
73
+ * seekers, truncate each included set to `query.limit`. Inputs are returned in `attachedAt` order
74
+ * (oldest first) so truncation keeps the longest-waiting registrations — the FCFS bias the arrival-push
75
+ * fairness rule also uses (`docs/matchmaking.md` §Fairness).
76
+ */
77
+ export function evaluateQuery(
78
+ query: QueryV1,
79
+ providers: readonly LocalProviderRegistration[],
80
+ seekers: readonly LocalSeekerRegistration[],
81
+ ): QueryEvalResult {
82
+ let truncated = false;
83
+ const result: { providers?: ProviderEntryV1[]; seekers?: SeekerEntryV1[]; truncated: boolean } = { truncated: false };
84
+
85
+ if (query.includeProviders) {
86
+ const matched = providers
87
+ .filter((reg) => matchesFilter(reg.payload, query.filter))
88
+ .sort((a, b) => a.attachedAt - b.attachedAt);
89
+ if (matched.length > query.limit) {
90
+ truncated = true;
91
+ }
92
+ result.providers = matched.slice(0, query.limit).map(providerEntryOf);
93
+ }
94
+
95
+ if (query.includeSeekers) {
96
+ const ordered = [...seekers].sort((a, b) => a.attachedAt - b.attachedAt);
97
+ if (ordered.length > query.limit) {
98
+ truncated = true;
99
+ }
100
+ result.seekers = ordered.slice(0, query.limit).map(seekerEntryOf);
101
+ }
102
+
103
+ result.truncated = truncated;
104
+ return result;
105
+ }