@optimystic/db-core 1.11.0 → 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 (73) hide show
  1. package/dist/src/cluster/structs.d.ts +13 -0
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cohort-topic/registration/store.d.ts +8 -1
  4. package/dist/src/cohort-topic/registration/store.d.ts.map +1 -1
  5. package/dist/src/cohort-topic/registration/store.js +57 -0
  6. package/dist/src/cohort-topic/registration/store.js.map +1 -1
  7. package/dist/src/cohort-topic/wire/primitives.d.ts +5 -0
  8. package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
  9. package/dist/src/cohort-topic/wire/primitives.js +5 -0
  10. package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
  11. package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
  12. package/dist/src/cohort-topic/wire/validate.js +1 -3
  13. package/dist/src/cohort-topic/wire/validate.js.map +1 -1
  14. package/dist/src/collection/action.d.ts +15 -1
  15. package/dist/src/collection/action.d.ts.map +1 -1
  16. package/dist/src/collection/action.js.map +1 -1
  17. package/dist/src/collection/collection.d.ts.map +1 -1
  18. package/dist/src/collection/collection.js +40 -4
  19. package/dist/src/collection/collection.js.map +1 -1
  20. package/dist/src/collection/struct.d.ts +6 -2
  21. package/dist/src/collection/struct.d.ts.map +1 -1
  22. package/dist/src/collection/struct.js.map +1 -1
  23. package/dist/src/matchmaking/arrival-push.d.ts +35 -0
  24. package/dist/src/matchmaking/arrival-push.d.ts.map +1 -0
  25. package/dist/src/matchmaking/arrival-push.js +56 -0
  26. package/dist/src/matchmaking/arrival-push.js.map +1 -0
  27. package/dist/src/matchmaking/config.d.ts +12 -2
  28. package/dist/src/matchmaking/config.d.ts.map +1 -1
  29. package/dist/src/matchmaking/config.js +8 -2
  30. package/dist/src/matchmaking/config.js.map +1 -1
  31. package/dist/src/matchmaking/index.d.ts +3 -2
  32. package/dist/src/matchmaking/index.d.ts.map +1 -1
  33. package/dist/src/matchmaking/index.js +3 -2
  34. package/dist/src/matchmaking/index.js.map +1 -1
  35. package/dist/src/matchmaking/seeker.d.ts +5 -2
  36. package/dist/src/matchmaking/seeker.d.ts.map +1 -1
  37. package/dist/src/matchmaking/seeker.js +6 -1
  38. package/dist/src/matchmaking/seeker.js.map +1 -1
  39. package/dist/src/matchmaking/wire.d.ts +66 -3
  40. package/dist/src/matchmaking/wire.d.ts.map +1 -1
  41. package/dist/src/matchmaking/wire.js +79 -11
  42. package/dist/src/matchmaking/wire.js.map +1 -1
  43. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  44. package/dist/src/testing/test-transactor.js +28 -46
  45. package/dist/src/testing/test-transactor.js.map +1 -1
  46. package/dist/src/transaction/index.d.ts +1 -1
  47. package/dist/src/transaction/index.d.ts.map +1 -1
  48. package/dist/src/transaction/index.js +1 -1
  49. package/dist/src/transaction/index.js.map +1 -1
  50. package/dist/src/transaction/transaction.d.ts +27 -0
  51. package/dist/src/transaction/transaction.d.ts.map +1 -1
  52. package/dist/src/transaction/transaction.js +27 -0
  53. package/dist/src/transaction/transaction.js.map +1 -1
  54. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  55. package/dist/src/transactor/transactor-source.js +6 -2
  56. package/dist/src/transactor/transactor-source.js.map +1 -1
  57. package/package.json +1 -1
  58. package/src/cluster/structs.ts +13 -0
  59. package/src/cohort-topic/registration/store.ts +68 -0
  60. package/src/cohort-topic/wire/primitives.ts +6 -0
  61. package/src/cohort-topic/wire/validate.ts +1 -3
  62. package/src/collection/action.ts +15 -1
  63. package/src/collection/collection.ts +43 -4
  64. package/src/collection/struct.ts +6 -2
  65. package/src/matchmaking/arrival-push.ts +66 -0
  66. package/src/matchmaking/config.ts +17 -2
  67. package/src/matchmaking/index.ts +3 -2
  68. package/src/matchmaking/seeker.ts +11 -3
  69. package/src/matchmaking/wire.ts +134 -10
  70. package/src/testing/test-transactor.ts +28 -40
  71. package/src/transaction/index.ts +2 -1
  72. package/src/transaction/transaction.ts +28 -0
  73. package/src/transactor/transactor-source.ts +6 -2
@@ -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
@@ -34,10 +35,13 @@ import {
34
35
  b64urlField,
35
36
  b64urlFixedLen,
36
37
  COORD_BYTES,
38
+ CORRELATION_BYTES,
37
39
  failWire as fail,
38
40
  optBool,
39
41
  optFiniteNumber,
42
+ optString,
40
43
  reqBool,
44
+ reqEnum,
41
45
  reqFiniteNumber,
42
46
  reqIntInRange,
43
47
  reqString,
@@ -75,6 +79,15 @@ export interface SeekerAppPayloadV1 {
75
79
  contactHint: string;
76
80
  /** Opt into arrival pushes; default false (poll path). */
77
81
  pushOnArrival?: boolean;
82
+ /**
83
+ * The registration id an {@link ArrivalPushV1} is bound to, 16 bytes, base64url. Required when
84
+ * `pushOnArrival` is `true`; accepted and ignored otherwise. Riding in the payload puts it in the
85
+ * cohort's gossip-replicated record, so any member can derive the seeker's push binding after a
86
+ * failover. Deliberately outside {@link seekerSigningPayload} (a forwarded {@link SeekerEntryV1}
87
+ * does not carry it); it is still authenticated, because the cohort admits the payload only inside
88
+ * a peer-key-signed `RegisterV1`, whose signing image covers `appPayload`.
89
+ */
90
+ correlationId?: string;
78
91
  /** base64url. */
79
92
  signature: string;
80
93
  }
@@ -181,6 +194,44 @@ export interface AggregateBucketV1 {
181
194
  count: number;
182
195
  }
183
196
 
197
+ // --- Arrival push (cohort member → push-opted seeker) ---
198
+
199
+ /**
200
+ * A cohort member's notification to a push-opted seeker that fresh matchable providers arrived
201
+ * (`docs/matchmaking.md` §Arrival push on provider arrival). Advisory, with the same trust model as
202
+ * {@link QueryReplyV1}: `signature` is the pushing member's single peer-key signature over
203
+ * {@link arrivalPushSigningPayload}, and the seeker re-validates every entry's `registrationSig`
204
+ * ({@link verifyProviderEntry}) before dialing.
205
+ */
206
+ export interface ArrivalPushV1 {
207
+ v: 1;
208
+ /** Topic id, 32 bytes, base64url. */
209
+ topicId: string;
210
+ /** Cohort epoch the push was computed under, 32 bytes, base64url. */
211
+ cohortEpoch: string;
212
+ /** The seeker registration this push is bound to ({@link SeekerAppPayloadV1.correlationId}), 16 bytes, base64url. */
213
+ correlationId: string;
214
+ /** The fresh, filter-matched, coalesced batch: `1..QUERY_LIMIT_MAX` entries. */
215
+ providers: ProviderEntryV1[];
216
+ /** Current traffic snapshot, so the seeker can re-run its hang-out math without a poll. */
217
+ topicTraffic: TopicTrafficV1;
218
+ /** The pushing member's single peer-key signature (NOT threshold), base64url. */
219
+ signature: string;
220
+ }
221
+
222
+ /** The outcomes a seeker may report for an {@link ArrivalPushV1}. */
223
+ export const ARRIVAL_PUSH_RESULTS = ["ok", "unknown_seeker"] as const;
224
+ export type ArrivalPushResult = typeof ARRIVAL_PUSH_RESULTS[number];
225
+
226
+ /**
227
+ * A seeker's reply to an {@link ArrivalPushV1}. `unknown_seeker` says the push's `correlationId` is not
228
+ * the seeker's current registration (it re-registered, or finished), so the pusher drops the binding.
229
+ */
230
+ export interface ArrivalPushAckV1 {
231
+ v: 1;
232
+ result: ArrivalPushResult;
233
+ }
234
+
184
235
  // --- matchmaking-local wire state (generic validation primitives live in cohort-topic/wire/primitives.js) ---
185
236
 
186
237
  const utf8Encoder = new TextEncoder();
@@ -248,6 +299,13 @@ export function validateSeekerAppPayloadV1(value: unknown): SeekerAppPayloadV1 {
248
299
  if (pushOnArrival !== undefined) {
249
300
  out.pushOnArrival = pushOnArrival;
250
301
  }
302
+ const correlationId = optString(obj, "correlationId", what);
303
+ if (correlationId !== undefined) {
304
+ out.correlationId = b64urlFixedLen(correlationId, "correlationId", CORRELATION_BYTES, what);
305
+ }
306
+ if (out.pushOnArrival === true && out.correlationId === undefined) {
307
+ fail(`${what}: field "correlationId" is required when "pushOnArrival" is true`);
308
+ }
251
309
  return out;
252
310
  }
253
311
 
@@ -433,6 +491,34 @@ export function validateAggregateCountV1(value: unknown): AggregateCountV1 {
433
491
  };
434
492
  }
435
493
 
494
+ /** Narrow an already-parsed value to {@link ArrivalPushV1}, throwing on any defect. */
495
+ export function validateArrivalPushV1(value: unknown): ArrivalPushV1 {
496
+ const what = "ArrivalPushV1";
497
+ const obj = asObject(value, what);
498
+ requireV1(obj, what);
499
+ const providers = obj["providers"];
500
+ if (!Array.isArray(providers) || providers.length < 1 || providers.length > QUERY_LIMIT_MAX) {
501
+ fail(`${what}: field "providers" must be an array of 1..${QUERY_LIMIT_MAX} entries`);
502
+ }
503
+ return {
504
+ v: 1,
505
+ topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
506
+ cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
507
+ correlationId: b64urlFixedLen(reqString(obj, "correlationId", what), "correlationId", CORRELATION_BYTES, what),
508
+ providers: providers.map(validateProviderEntryV1),
509
+ topicTraffic: validateTopicTrafficV1(obj["topicTraffic"], `${what}.topicTraffic`),
510
+ signature: b64urlField(reqString(obj, "signature", what), "signature", what),
511
+ };
512
+ }
513
+
514
+ /** Narrow an already-parsed value to {@link ArrivalPushAckV1}, throwing on any defect. */
515
+ export function validateArrivalPushAckV1(value: unknown): ArrivalPushAckV1 {
516
+ const what = "ArrivalPushAckV1";
517
+ const obj = asObject(value, what);
518
+ requireV1(obj, what);
519
+ return { v: 1, result: reqEnum(obj, "result", ARRIVAL_PUSH_RESULTS, what) };
520
+ }
521
+
436
522
  /** Encode a {@link QueryV1} as a length-prefixed UTF-8 JSON frame. */
437
523
  export function encodeQueryV1(msg: QueryV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
438
524
  return encodeCohortMessage(validateQueryV1(msg), maxMessageBytes);
@@ -463,6 +549,26 @@ export function decodeAggregateCountV1(bytes: Uint8Array, maxMessageBytes?: numb
463
549
  return validateAggregateCountV1(decodeCohortMessage(bytes, maxMessageBytes));
464
550
  }
465
551
 
552
+ /** Encode an {@link ArrivalPushV1} as a length-prefixed UTF-8 JSON frame. */
553
+ export function encodeArrivalPushV1(msg: ArrivalPushV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
554
+ return encodeCohortMessage(validateArrivalPushV1(msg), maxMessageBytes);
555
+ }
556
+
557
+ /** Decode a length-prefixed {@link ArrivalPushV1} frame. */
558
+ export function decodeArrivalPushV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushV1 {
559
+ return validateArrivalPushV1(decodeCohortMessage(bytes, maxMessageBytes));
560
+ }
561
+
562
+ /** Encode an {@link ArrivalPushAckV1} as a length-prefixed UTF-8 JSON frame. */
563
+ export function encodeArrivalPushAckV1(msg: ArrivalPushAckV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
564
+ return encodeCohortMessage(validateArrivalPushAckV1(msg), maxMessageBytes);
565
+ }
566
+
567
+ /** Decode a length-prefixed {@link ArrivalPushAckV1} frame. */
568
+ export function decodeArrivalPushAckV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushAckV1 {
569
+ return validateArrivalPushAckV1(decodeCohortMessage(bytes, maxMessageBytes));
570
+ }
571
+
466
572
  // --- canonical participant-signature payloads (provider/seeker registration sigs) ---
467
573
 
468
574
  /**
@@ -558,18 +664,36 @@ export function queryReplySigningPayload(reply: Omit<QueryReplyV1, "signature">)
558
664
  reply.v,
559
665
  reply.cohortEpoch,
560
666
  reply.truncated,
561
- [
562
- reply.topicTraffic.windowSeconds,
563
- reply.topicTraffic.arrivalsPerMin,
564
- reply.topicTraffic.queriesPerMin,
565
- reply.topicTraffic.directParticipants,
566
- reply.topicTraffic.childCohortCount,
567
- ],
667
+ topicTrafficImage(reply.topicTraffic),
568
668
  (reply.providers ?? []).map((p) => p.participantId),
569
669
  (reply.seekers ?? []).map((s) => s.participantId),
570
670
  ]));
571
671
  }
572
672
 
673
+ /**
674
+ * Canonical signed byte image of an {@link ArrivalPushV1} — the pushing member's single-member
675
+ * signature, mirroring {@link queryReplySigningPayload}. It binds the topic, epoch, the seeker
676
+ * registration the push is addressed to, the traffic snapshot, and the providers' participant ids
677
+ * (order-sensitive); the per-entry signatures stay outside it, since the seeker re-validates each entry
678
+ * on its own ({@link verifyProviderEntry}).
679
+ */
680
+ export function arrivalPushSigningPayload(unsigned: Omit<ArrivalPushV1, "signature">): Uint8Array {
681
+ return utf8Encoder.encode(JSON.stringify([
682
+ "ArrivalPushV1",
683
+ unsigned.v,
684
+ unsigned.topicId,
685
+ unsigned.cohortEpoch,
686
+ unsigned.correlationId,
687
+ topicTrafficImage(unsigned.topicTraffic),
688
+ unsigned.providers.map((p) => p.participantId),
689
+ ]));
690
+ }
691
+
692
+ /** The traffic snapshot as an explicitly ordered array, shared by the single-member signing images. */
693
+ function topicTrafficImage(t: TopicTrafficV1): number[] {
694
+ return [t.windowSeconds, t.arrivalsPerMin, t.queriesPerMin, t.directParticipants, t.childCohortCount];
695
+ }
696
+
573
697
  // --- aggregate-count log-bucketing + canonical threshold-signing image (multi-cohort sweep) ---
574
698
 
575
699
  /**
@@ -73,27 +73,22 @@ export class TestTransactor implements ITransactor {
73
73
  // revision-pinned read of a block committed further since the pin makes them differ,
74
74
  // and there the pinned value is what the reader observed (see the field's doc).
75
75
  let materializedRev: number | undefined;
76
- if (blockGets.context?.actionId !== undefined) {
77
- // If requesting a specific action, apply pending transform if it exists
78
- const pendingTransform = blockState.pendingActions.get(blockGets.context.actionId);
79
- if (pendingTransform) {
80
- // Read latest committed block as base for pending transform
81
- const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
82
- block = applyTransformSafe(baseBlock, pendingTransform);
83
- // A pending carries no revision of its own — report the committed base it was
84
- // applied over. Absent when there was no base (a pending-only insert).
85
- if (baseBlock) materializedRev = blockState.latestRev;
86
- } else {
87
- // Action not pending, maybe committed? Or maybe invalid actionId for context.
88
- // For simplicity, return undefined block if specific pending action not found.
89
- // A more complex impl might check committedActions history.
90
- block = undefined;
91
- }
92
- } else if (blockGets.context?.committed) {
93
- // Check context.committed for matching pending actions — mirrors coordinator
94
- // behavior: context.committed proves the action succeeded, so pending blocks
95
- // for that action should be served.
96
- for (const { actionId: cId } of blockGets.context.committed) {
76
+ // A named pending is overlaid only where this block holds it; every other block gets the
77
+ // plain answer for the same context (mirrors StorageRepo.get).
78
+ const pin = blockGets.context?.rev;
79
+ const namedPending = blockGets.context?.actionId !== undefined
80
+ ? blockState.pendingActions.get(blockGets.context.actionId) : undefined;
81
+ if (namedPending) {
82
+ // Overlay over the committed base at the context's pin, as StorageRepo does.
83
+ const base = committedAt(blockState, pin);
84
+ block = applyTransformSafe(base?.block, namedPending);
85
+ // A pending carries no revision of its own — report the committed base it was
86
+ // applied over. Absent when there was no base (a pending-only insert).
87
+ materializedRev = base?.rev;
88
+ } else {
89
+ // context.committed proves its actions succeeded, so a block still holding one of them
90
+ // pending is served with it applied — mirrors the coordinator's read-driven promotion.
91
+ for (const { actionId: cId } of blockGets.context?.committed ?? []) {
97
92
  const pendingTransform = blockState.pendingActions.get(cId);
98
93
  if (pendingTransform) {
99
94
  const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
@@ -102,29 +97,14 @@ export class TestTransactor implements ITransactor {
102
97
  break;
103
98
  }
104
99
  }
105
- // Fall through to standard resolution if no pending match
100
+ // Otherwise the committed content at the highest revision ≤ the pin, or the latest.
106
101
  if (block === undefined) {
107
- if (blockGets.context.rev !== undefined) {
108
- const found = latestMaterializedAt(blockState, blockGets.context.rev);
109
- block = structuredClone(found?.block);
110
- materializedRev = found?.rev;
111
- } else {
112
- block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
113
- if (block) materializedRev = blockState.latestRev;
114
- }
102
+ const found = committedAt(blockState, pin);
103
+ block = structuredClone(found?.block);
104
+ materializedRev = found?.rev;
115
105
  }
116
- } else if (blockGets.context?.rev !== undefined) {
117
- // Return the materialized block at the highest revision ≤ requested
118
- const found = latestMaterializedAt(blockState, blockGets.context.rev);
119
- block = structuredClone(found?.block);
120
- materializedRev = found?.rev;
121
- } else {
122
- // Otherwise return latest materialized block
123
- block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
124
- if (block) materializedRev = blockState.latestRev;
125
106
  }
126
107
 
127
-
128
108
  const actionId = blockState.revisionActions.get(blockState.latestRev);
129
109
  // The materialized revision travels WITH its action id (one field, so the pair can
130
110
  // never disagree) — the same `(rev, actionId)` the commit recorded for it.
@@ -963,6 +943,14 @@ function latestActionRev(blockState: BlockState): ActionRev | undefined {
963
943
  return actionId === undefined ? undefined : { actionId, rev: blockState.latestRev };
964
944
  }
965
945
 
946
+ /** The committed content a read at `pin` sees — the highest materialized revision at or below
947
+ * it — or the latest revision's content when the read is unpinned. */
948
+ function committedAt(blockState: BlockState, pin: number | undefined): { block: IBlock, rev: number } | undefined {
949
+ if (pin !== undefined) return latestMaterializedAt(blockState, pin);
950
+ const block = blockState.materializedBlocks.get(blockState.latestRev);
951
+ return block ? { block, rev: blockState.latestRev } : undefined;
952
+ }
953
+
966
954
  /** Returns the materialized block at the highest revision ≤ the given revision, together with
967
955
  * that revision — the caller reports it as {@link GetBlockResult.materialized}. */
968
956
  function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
@@ -24,7 +24,8 @@ export {
24
24
  clientSignaturePayload,
25
25
  CLIENT_SIG_VERSION,
26
26
  MaxPriority,
27
- clampPriority
27
+ clampPriority,
28
+ SlotHoldAfterLosses
28
29
  } from './transaction.js';
29
30
 
30
31
  export {
@@ -152,6 +152,34 @@ export function clampPriority(priority: number | undefined): number {
152
152
  return Math.floor(priority);
153
153
  }
154
154
 
155
+ /**
156
+ * How many times a storage member must ITSELF have refused one action's pend as stale — a rival's
157
+ * revision already committed under the requested one — before it holds the next slot of that pend's
158
+ * blocks for the action. Counted per action id, which is one sync cycle (`Collection.syncInternal`
159
+ * mints the id once and every attempt of that cycle reuses it), so the count is "losses in a row of
160
+ * one write" and never needs resetting.
161
+ *
162
+ * What the member holds, and how it answers a rival while it holds, is in db-p2p's
163
+ * `ClusterMember.validatePendOperations` (`cluster/cluster-repo.ts`): the hold answers the next
164
+ * other-action pend of each block with the same `held` vote a storage reservation produces, once,
165
+ * for a bounded window, and is consumed by the aged action's own next pend. It closes the
166
+ * sequential starvation the aged {@link Transaction.priority} cannot reach — a stream of quick
167
+ * writers that each commit and leave before the slow one's attempt arrives never co-pend with it,
168
+ * so `resolveRace` never meets them (docs/correctness.md Theorem 9, "Bound").
169
+ *
170
+ * The count is the member's own and never the self-asserted priority: a member grants only on
171
+ * refusals it issued, so no claimant can talk it into a hold with a number. The writer side counts the
172
+ * refusals that confirmed a committed revision against the same constant to stop backing off on the
173
+ * loss after which a member holds for it (`retryBackoffMs` in `collection/collection.ts`), so the two
174
+ * sides agree with nothing on the wire — wherever the refused pends reached the member.
175
+ *
176
+ * Three: the plan-stage measurement (ticket `slot-hold-for-an-aged-writer`) showed an honest slow
177
+ * writer behind a quick stream losing nine of ten attempts, so two losses are an ordinary lost race
178
+ * and three are the stream. Lower, and a single lost race would hold a block against every other
179
+ * writer; higher, and the slow writer pays more refused round trips before it is helped.
180
+ */
181
+ export const SlotHoldAfterLosses = 3;
182
+
155
183
  /** Check whether a transaction stamp has expired. */
156
184
  export function isTransactionExpired(stamp: TransactionStamp): boolean {
157
185
  return Date.now() > stamp.expiration;
@@ -134,8 +134,12 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
134
134
  this.readRevisions.set(id, rev);
135
135
  this.served.set(block, { rev, mayRetain: this.mayRetain(id, rev) });
136
136
  }
137
- // TODO: if the state reports that there is a pending action, record this so that we are sure to update before syncing
138
- //state.pendings
137
+ // NOTE: rival pendings in `state.pendings` are deliberately not remembered for a refresh
138
+ // before the next pend. It would save one doomed pend round only when the rival commits in
139
+ // between; the hint goes stale on a cache hit (which never re-reads), stuck records would
140
+ // trigger refreshes for nothing (backlog `debt-unpromotable-pending-records-need-a-sweep`),
141
+ // and while the rival is still pending a refresh changes nothing and the pend is refused
142
+ // `held` anyway. Revisit if lost pend rounds after a rival commit show up in measurements.
139
143
  return block as TBlock;
140
144
  }
141
145
  }