@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
@@ -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
  /**
@@ -62,4 +62,13 @@ export type IKeyNetwork = {
62
62
  * @param ttlMs Optional time-to-live for the cached hint, in ms
63
63
  */
64
64
  recordCoordinator?(key: RoutingKey, peerId: PeerId, ttlMs?: number): void;
65
+
66
+ /**
67
+ * Optionally report that this node was configured with peers to join through and has not yet
68
+ * heard from all of them. While true, a `findCluster` answer naming nobody but this node is
69
+ * what the node would see whether or not those peers hold a block, so a repo must not treat
70
+ * its own lack of the block as proof the block was never created. Implementations with no
71
+ * such configuration omit this, which reads as "not awaiting".
72
+ */
73
+ awaitingBootstrapContact?(): Promise<boolean>;
65
74
  }
@@ -7,4 +7,5 @@ export * from "./repo-protocol.js";
7
7
  export * from "./routing-key.js";
8
8
  export * from "./stale-failure.js";
9
9
  export * from "./struct.js";
10
+ export * from "./transaction-expired-error.js";
10
11
  export * from "./types.js";
@@ -1,5 +1,5 @@
1
1
  import type { ActionId, ActionRev } from "../collection/action.js";
2
- import type { StaleFailure } from "./struct.js";
2
+ import type { ExpiredFailure, StaleFailure, WriteFailure } from "./struct.js";
3
3
 
4
4
  /**
5
5
  * The single rule for "is this non-success retryable after a re-read?" Both write paths and the
@@ -7,12 +7,25 @@ import type { StaleFailure } from "./struct.js";
7
7
  *
8
8
  * {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
9
9
  * covers producers that have not been taught the field, including a remote peer on an older build
10
- * (the repo protocol is plain JSON, so an unset field simply arrives absent).
10
+ * (the repo protocol is plain JSON, so an unset field simply arrives absent). An expiry is never a
11
+ * conflict ({@link isExpiryFailure}), whatever else arrived beside it.
11
12
  */
12
- export function isConflictFailure(failure: StaleFailure): boolean {
13
+ export function isConflictFailure(failure: WriteFailure): boolean {
14
+ if (isExpiryFailure(failure)) return false;
13
15
  return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
14
16
  }
15
17
 
18
+ /**
19
+ * The single rule for "did the cohort refuse this write because the transaction had already expired
20
+ * by the members' clocks?" ({@link ExpiredFailure}). Every write path stops on it rather than
21
+ * retrying, since a retry's expiration comes from the same clock. Decided by the structured field,
22
+ * never the reason text; a peer on a build that predates the field never sends it, and its refusal
23
+ * reads as the shape it always had.
24
+ */
25
+ export function isExpiryFailure(failure: WriteFailure): failure is ExpiredFailure {
26
+ return failure.expired !== undefined;
27
+ }
28
+
16
29
  /**
17
30
  * The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
18
31
  *
@@ -184,9 +184,50 @@ export type StaleFailure = {
184
184
  * the presence of this field.
185
185
  */
186
186
  staleAt?: { blockId: BlockId; rev: number };
187
+ /** Never set on a lost race — an expiry is its own failure shape, {@link ExpiredFailure}. */
188
+ expired?: never;
187
189
  };
188
190
 
189
- export type PendResult = PendSuccess | StaleFailure;
191
+ /**
192
+ * Why a cohort refused a write as expired: by each refusing member's own clock, the transaction's
193
+ * `expiration` had already passed when the record reached it. Plain data, so it crosses the JSON repo
194
+ * protocol intact. `TransactionExpiredError` is built from it, wherever it is raised.
195
+ */
196
+ export type TransactionExpiry = {
197
+ /** The transaction's expiration (unix ms), as the writer's transactor set it from its own clock. */
198
+ expiration: number;
199
+ /** Per refusing cohort member (peer-id string), the clock reading (unix ms) it signed when it
200
+ * judged the record expired (`Signature.expiredAt`). Never empty. */
201
+ memberClocks: Record<string, number>;
202
+ /** The coordinating node's clock (unix ms) when it concluded the refusal. */
203
+ coordinatorClock: number;
204
+ };
205
+
206
+ /**
207
+ * The cohort refused the write because the transaction had already EXPIRED by the members' clocks —
208
+ * a clock disagreement between the writer and the cohort, not a lost race and not a judgement of the
209
+ * write. Never retryable: every retry carries an expiration set by the same clock, and is refused the
210
+ * same way until a clock is corrected. A sibling of {@link StaleFailure} rather than a field on it,
211
+ * because "lost to a newer revision" is exactly what this is not; the fields it can never carry are
212
+ * typed `never`, so a consumer reads `reason`, `missing` or `staleAt` off either shape unnarrowed.
213
+ * Tell the two apart with `isExpiryFailure`, never by reading `reason`.
214
+ */
215
+ export type ExpiredFailure = {
216
+ success: false;
217
+ /** The coordinator's description of the refusal, for a log line. Never branch on it. */
218
+ reason?: string;
219
+ /** Always false: an expiry is never a conflict a re-read can win. */
220
+ conflict: false;
221
+ expired: TransactionExpiry;
222
+ missing?: never;
223
+ pending?: never;
224
+ staleAt?: never;
225
+ };
226
+
227
+ /** Every way a pend or a commit can be refused with an answer rather than a throw. */
228
+ export type WriteFailure = StaleFailure | ExpiredFailure;
229
+
230
+ export type PendResult = PendSuccess | WriteFailure;
190
231
 
191
232
  /** What one block will materialize to at the committing revision, declared by the client that
192
233
  * authored the transforms. */
@@ -265,7 +306,7 @@ export type InvalidateRequest = {
265
306
  resolution: DisputeResolutionProof;
266
307
  };
267
308
 
268
- export type CommitResult = CommitSuccess | StaleFailure;
309
+ export type CommitResult = CommitSuccess | WriteFailure;
269
310
 
270
311
  export type CommitSuccess = {
271
312
  success: true;
@@ -387,13 +428,25 @@ export type BlockUnavailableReason =
387
428
  /** Nothing is held locally and NO cohort member outside the answering node could be
388
429
  * asked at all. Distinct from `peers-unreachable` in exactly the way that matters to
389
430
  * a caller: there is no better-connected coordinator to re-ask, so the answer will
390
- * not improve until that node's connectivity does. Its local view is all there is. */
431
+ * not improve until that node's connectivity does. Its local view is all there is.
432
+ * Also the answer of a node whose cohort view holds only itself while a peer it was
433
+ * configured to join through has never been heard from
434
+ * (`IKeyNetwork.awaitingBootstrapContact`): it knows of a machine outside itself and
435
+ * has not reached it. */
391
436
  | 'cohort-unreachable'
392
437
  /** Nothing is held locally, but a cohort peer positively CLAIMED a revision of this
393
438
  * block, and the answering node could neither corroborate that claim to a quorum nor
394
439
  * acquire the content. The block is known to exist somewhere; reporting it absent
395
440
  * would be a lie regardless of whether anyone was silent. */
396
- | 'claimed-elsewhere';
441
+ | 'claimed-elsewhere'
442
+ /** Nothing is held locally and the answering node had nobody to ask (its cohort view
443
+ * was empty, or only itself), but the read carried a floor for the block
444
+ * ({@link BlockGets.floors}): the asker walked a log entry committing a revision of it.
445
+ * The block is known to exist, from the asker's own evidence, so "never created" would
446
+ * contradict what the asker already knows. Unlike `cohort-unreachable` this is never
447
+ * "the local view is all there is": another machine may hold the block, and asking one
448
+ * is the remedy. */
449
+ | 'named-by-log';
397
450
 
398
451
  export type GetBlockResult = {
399
452
  /** The retrieved block - undefined if the block was deleted */
@@ -0,0 +1,81 @@
1
+ import type { ExpiredFailure, TransactionExpiry } from "./struct.js";
2
+ import { formatInstant } from "../utility/format-instant.js";
3
+
4
+ /**
5
+ * A write the cohort refused because, by the refusing members' own clocks, the transaction had
6
+ * already expired when it reached them. Nobody judged the write and nobody was unreachable: the clock
7
+ * that set the expiration (the writer's) and the members' clocks disagree by more than the
8
+ * transaction timeout (30 s by default). Not retryable — a retry's expiration comes from the same
9
+ * clock, so it is refused the same way until one of the clocks is corrected. Nothing was saved.
10
+ *
11
+ * ONE class for every place it is raised, so the coordinator's report and the writer's cannot drift.
12
+ * The cluster coordinator (db-p2p `ClusterCoordinator`) raises it when every reject vote that sank a
13
+ * transaction was an expiry vote; the coordinating repo returns its facts as an
14
+ * {@link ExpiredFailure} ({@link toFailure}), which is what lets a remote writer receive them at all;
15
+ * and each write path (`Collection.sync`, `TransactionCoordinator.commit`) raises it again from that
16
+ * refusal, with its own clock as {@link localClock}. Deliberately not a db-p2p
17
+ * `ValidatorRejectionError`, which means "the cohort judged the write": the coordinating repo turns
18
+ * this one into its refusal before its validator-rejection classifiers run.
19
+ */
20
+ export class TransactionExpiredError extends Error {
21
+ /** The transaction's expiration (unix ms), as the writer's transactor set it. */
22
+ readonly expiration: number;
23
+ /** Per refusing cohort member (peer-id string), the clock reading (unix ms) it signed. */
24
+ readonly memberClocks: Readonly<Record<string, number>>;
25
+ /** The coordinating node's clock (unix ms) when it concluded the refusal. */
26
+ readonly coordinatorClock: number;
27
+ /**
28
+ * How far ahead of {@link localClock} the most-skewed refusing member's clock appeared: the largest
29
+ * `memberClocks[peer] − localClock`. An estimate, low by the time the answer took to travel back
30
+ * (a member read its clock before then). Raised by a write path, this is how far the cohort's
31
+ * clocks appear to be from the writer's own — the number to act on whichever side is wrong. Zero or
32
+ * less means this node's clock has the expiration past as well.
33
+ */
34
+ readonly apparentSkewMs: number;
35
+
36
+ constructor(
37
+ expiry: TransactionExpiry,
38
+ /** This node's clock (unix ms) when it raised the error: the coordinator's where the cluster
39
+ * raised it, the writer's where a write path raised it from a returned refusal. */
40
+ readonly localClock: number = Date.now(),
41
+ ) {
42
+ // NOTE: `expiry` off the wire is trusted as shaped (`isExpiryFailure` checks only presence), so a
43
+ // malformed coordinator answer gives NaN here, or a TypeError when `memberClocks` is missing,
44
+ // instead of this error. Either still ends the write; if hostile coordinators become a concern,
45
+ // validate the shape where the refusal is received.
46
+ const apparentSkewMs = Math.max(...Object.values(expiry.memberClocks)) - localClock;
47
+ super(transactionExpiredMessage(expiry, localClock, apparentSkewMs));
48
+ this.name = 'TransactionExpiredError';
49
+ this.expiration = expiry.expiration;
50
+ this.memberClocks = { ...expiry.memberClocks };
51
+ this.coordinatorClock = expiry.coordinatorClock;
52
+ this.apparentSkewMs = apparentSkewMs;
53
+ }
54
+
55
+ /** The refusal a coordinating repo returns for this error, so it crosses the repo protocol as an
56
+ * answer rather than as a reset stream. */
57
+ toFailure(): ExpiredFailure {
58
+ return {
59
+ success: false,
60
+ conflict: false,
61
+ reason: this.message,
62
+ expired: { expiration: this.expiration, memberClocks: { ...this.memberClocks }, coordinatorClock: this.coordinatorClock },
63
+ };
64
+ }
65
+ }
66
+
67
+ /**
68
+ * Written to be shown to a person. Deliberately free of the shortfall error's text ("Failed to get
69
+ * super-majority"), which a downstream repository matches to retry a silent cohort: a clock
70
+ * disagreement is neither silence nor transient.
71
+ */
72
+ function transactionExpiredMessage(expiry: TransactionExpiry, localClock: number, apparentSkewMs: number): string {
73
+ const seconds = (ms: number) => (ms / 1000).toFixed(1);
74
+ const refusing = Object.keys(expiry.memberClocks).length;
75
+ const gap = apparentSkewMs > 0
76
+ ? `Their clocks appear to be about ${seconds(apparentSkewMs)} s ahead of this device's.`
77
+ : `This device's clock has it ${seconds(localClock - expiry.expiration)} s past as well, so the clock that set the expiration may be behind, or the transaction outlived its deadline.`;
78
+ return `The transaction expired before the cohort could accept it: by their own clocks, ${refusing} cohort member(s) found its expiration (${formatInstant(expiry.expiration)}) already past. `
79
+ + `${gap} This is a clock disagreement, not a conflict or an unreachable cohort, and retrying fails the same way until it is resolved: `
80
+ + `correct the clock of whichever device is wrong — this one, or the refusing members.`;
81
+ }
@@ -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 {