@optimystic/db-core 1.19.0 → 1.20.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 (171) hide show
  1. package/dist/src/cluster/structs.d.ts +41 -8
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.js +18 -7
  4. package/dist/src/cluster/structs.js.map +1 -1
  5. package/dist/src/collection/action.d.ts +29 -0
  6. package/dist/src/collection/action.d.ts.map +1 -1
  7. package/dist/src/collection/action.js +6 -0
  8. package/dist/src/collection/action.js.map +1 -1
  9. package/dist/src/collection/collection.d.ts +533 -120
  10. package/dist/src/collection/collection.d.ts.map +1 -1
  11. package/dist/src/collection/collection.js +974 -500
  12. package/dist/src/collection/collection.js.map +1 -1
  13. package/dist/src/collection/head-commit.d.ts +110 -0
  14. package/dist/src/collection/head-commit.d.ts.map +1 -0
  15. package/dist/src/collection/head-commit.js +65 -0
  16. package/dist/src/collection/head-commit.js.map +1 -0
  17. package/dist/src/collection/index.d.ts +2 -0
  18. package/dist/src/collection/index.d.ts.map +1 -1
  19. package/dist/src/collection/index.js +2 -0
  20. package/dist/src/collection/index.js.map +1 -1
  21. package/dist/src/collection/segments.d.ts +77 -0
  22. package/dist/src/collection/segments.d.ts.map +1 -0
  23. package/dist/src/collection/segments.js +110 -0
  24. package/dist/src/collection/segments.js.map +1 -0
  25. package/dist/src/collection/struct.d.ts +156 -1
  26. package/dist/src/collection/struct.d.ts.map +1 -1
  27. package/dist/src/collection/struct.js +70 -0
  28. package/dist/src/collection/struct.js.map +1 -1
  29. package/dist/src/collection/write-attempts.d.ts +245 -0
  30. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  31. package/dist/src/collection/write-attempts.js +439 -0
  32. package/dist/src/collection/write-attempts.js.map +1 -0
  33. package/dist/src/collections/tree/struct.d.ts +100 -17
  34. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  35. package/dist/src/collections/tree/struct.js +38 -7
  36. package/dist/src/collections/tree/struct.js.map +1 -1
  37. package/dist/src/collections/tree/tree.d.ts +17 -5
  38. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  39. package/dist/src/collections/tree/tree.js +112 -26
  40. package/dist/src/collections/tree/tree.js.map +1 -1
  41. package/dist/src/index.d.ts +2 -0
  42. package/dist/src/index.d.ts.map +1 -1
  43. package/dist/src/index.js +2 -0
  44. package/dist/src/index.js.map +1 -1
  45. package/dist/src/network/i-repo.d.ts +3 -0
  46. package/dist/src/network/i-repo.d.ts.map +1 -1
  47. package/dist/src/network/index.d.ts +3 -0
  48. package/dist/src/network/index.d.ts.map +1 -1
  49. package/dist/src/network/index.js +3 -0
  50. package/dist/src/network/index.js.map +1 -1
  51. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  52. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  53. package/dist/src/network/promise-shortfall-error.js +67 -0
  54. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  55. package/dist/src/network/refuse-solo.d.ts +8 -0
  56. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  57. package/dist/src/network/refuse-solo.js +8 -0
  58. package/dist/src/network/refuse-solo.js.map +1 -0
  59. package/dist/src/network/stale-failure.d.ts +20 -3
  60. package/dist/src/network/stale-failure.d.ts.map +1 -1
  61. package/dist/src/network/stale-failure.js +24 -3
  62. package/dist/src/network/stale-failure.js.map +1 -1
  63. package/dist/src/network/struct.d.ts +148 -2
  64. package/dist/src/network/struct.d.ts.map +1 -1
  65. package/dist/src/network/struct.js.map +1 -1
  66. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  67. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  68. package/dist/src/network/validity-rejected-error.js +51 -0
  69. package/dist/src/network/validity-rejected-error.js.map +1 -0
  70. package/dist/src/offline/entry.d.ts +72 -0
  71. package/dist/src/offline/entry.d.ts.map +1 -0
  72. package/dist/src/offline/entry.js +73 -0
  73. package/dist/src/offline/entry.js.map +1 -0
  74. package/dist/src/offline/index.d.ts +5 -0
  75. package/dist/src/offline/index.d.ts.map +1 -0
  76. package/dist/src/offline/index.js +5 -0
  77. package/dist/src/offline/index.js.map +1 -0
  78. package/dist/src/offline/journal.d.ts +61 -0
  79. package/dist/src/offline/journal.d.ts.map +1 -0
  80. package/dist/src/offline/journal.js +2 -0
  81. package/dist/src/offline/journal.js.map +1 -0
  82. package/dist/src/offline/queue.d.ts +484 -0
  83. package/dist/src/offline/queue.d.ts.map +1 -0
  84. package/dist/src/offline/queue.js +1236 -0
  85. package/dist/src/offline/queue.js.map +1 -0
  86. package/dist/src/offline/reachability.d.ts +25 -0
  87. package/dist/src/offline/reachability.d.ts.map +1 -0
  88. package/dist/src/offline/reachability.js +13 -0
  89. package/dist/src/offline/reachability.js.map +1 -0
  90. package/dist/src/offline/status.d.ts +148 -0
  91. package/dist/src/offline/status.d.ts.map +1 -0
  92. package/dist/src/offline/status.js +63 -0
  93. package/dist/src/offline/status.js.map +1 -0
  94. package/dist/src/offline/wake.d.ts +30 -0
  95. package/dist/src/offline/wake.d.ts.map +1 -0
  96. package/dist/src/offline/wake.js +68 -0
  97. package/dist/src/offline/wake.js.map +1 -0
  98. package/dist/src/testing/test-transactor.d.ts +29 -0
  99. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  100. package/dist/src/testing/test-transactor.js +50 -0
  101. package/dist/src/testing/test-transactor.js.map +1 -1
  102. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  103. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  104. package/dist/src/transaction/commit-failure-class.js +96 -0
  105. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  106. package/dist/src/transaction/coordinator.d.ts +165 -41
  107. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  108. package/dist/src/transaction/coordinator.js +605 -300
  109. package/dist/src/transaction/coordinator.js.map +1 -1
  110. package/dist/src/transaction/entry-commit.d.ts +139 -0
  111. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  112. package/dist/src/transaction/entry-commit.js +199 -0
  113. package/dist/src/transaction/entry-commit.js.map +1 -0
  114. package/dist/src/transaction/index.d.ts +4 -1
  115. package/dist/src/transaction/index.d.ts.map +1 -1
  116. package/dist/src/transaction/index.js +1 -0
  117. package/dist/src/transaction/index.js.map +1 -1
  118. package/dist/src/transaction/transaction.d.ts +20 -0
  119. package/dist/src/transaction/transaction.d.ts.map +1 -1
  120. package/dist/src/transaction/validator.d.ts +7 -0
  121. package/dist/src/transaction/validator.d.ts.map +1 -1
  122. package/dist/src/transaction/validator.js +21 -12
  123. package/dist/src/transaction/validator.js.map +1 -1
  124. package/dist/src/transactor/network-transactor.d.ts +1 -0
  125. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  126. package/dist/src/transactor/network-transactor.js +61 -28
  127. package/dist/src/transactor/network-transactor.js.map +1 -1
  128. package/dist/src/transactor/transactor-source.d.ts +22 -11
  129. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  130. package/dist/src/transactor/transactor-source.js +9 -13
  131. package/dist/src/transactor/transactor-source.js.map +1 -1
  132. package/dist/src/utility/visit-every.d.ts +14 -0
  133. package/dist/src/utility/visit-every.d.ts.map +1 -0
  134. package/dist/src/utility/visit-every.js +27 -0
  135. package/dist/src/utility/visit-every.js.map +1 -0
  136. package/package.json +1 -1
  137. package/src/cluster/structs.ts +42 -7
  138. package/src/collection/action.ts +34 -0
  139. package/src/collection/collection.ts +1048 -543
  140. package/src/collection/head-commit.ts +148 -0
  141. package/src/collection/index.ts +2 -0
  142. package/src/collection/segments.ts +149 -0
  143. package/src/collection/struct.ts +183 -1
  144. package/src/collection/write-attempts.ts +506 -0
  145. package/src/collections/tree/struct.ts +97 -17
  146. package/src/collections/tree/tree.ts +125 -29
  147. package/src/index.ts +2 -0
  148. package/src/network/i-repo.ts +3 -0
  149. package/src/network/index.ts +3 -0
  150. package/src/network/promise-shortfall-error.ts +69 -0
  151. package/src/network/refuse-solo.ts +7 -0
  152. package/src/network/stale-failure.ts +27 -4
  153. package/src/network/struct.ts +154 -2
  154. package/src/network/validity-rejected-error.ts +55 -0
  155. package/src/offline/entry.ts +127 -0
  156. package/src/offline/index.ts +4 -0
  157. package/src/offline/journal.ts +60 -0
  158. package/src/offline/queue.ts +1342 -0
  159. package/src/offline/reachability.ts +32 -0
  160. package/src/offline/status.ts +183 -0
  161. package/src/offline/wake.ts +67 -0
  162. package/src/testing/test-transactor.ts +53 -0
  163. package/src/transaction/commit-failure-class.ts +133 -0
  164. package/src/transaction/coordinator.ts +696 -349
  165. package/src/transaction/entry-commit.ts +285 -0
  166. package/src/transaction/index.ts +4 -0
  167. package/src/transaction/transaction.ts +21 -0
  168. package/src/transaction/validator.ts +22 -12
  169. package/src/transactor/network-transactor.ts +62 -28
  170. package/src/transactor/transactor-source.ts +29 -13
  171. package/src/utility/visit-every.ts +25 -0
@@ -1,6 +1,6 @@
1
1
  import type { CollectionId, BlockId, IBlock, ActionId, Transform, Transforms } from "../index.js";
2
2
  import type { ActionContext, ActionRev } from "../collection/action.js";
3
- import type { Transaction } from "../transaction/transaction.js";
3
+ import type { Transaction, ValidityRejection } from "../transaction/transaction.js";
4
4
  import type { DisputeResolutionProof } from "../log/struct.js";
5
5
  import type { PeerId } from "./types.js";
6
6
 
@@ -104,6 +104,25 @@ export type PendRequest = ActionTransforms & {
104
104
  * an older build ignores it, and then delivers at once as it always did.
105
105
  */
106
106
  soleReservation?: true;
107
+ /**
108
+ * The writer's word that this write must not be committed by a lone node that knows it is not
109
+ * alone (`SyncOptions.refuseSoloCommit`). A coordinator whose cohort for the write is only itself
110
+ * refuses the pend — before reserving anything — when it knows of cohort members it could not
111
+ * place in the cohort, is still waiting to hear from a configured bootstrap peer, or could not
112
+ * route the write to itself, answering with a {@link ShortfallFailure} whose
113
+ * {@link PromiseShortfall.soloRefused} names which (`CoordinatorRepo.pendSolo` in db-p2p). A
114
+ * coordinator that is genuinely alone ignores it and pends as it always did, and so does every
115
+ * coordinator whose cohort has more than one member.
116
+ *
117
+ * Carried by every send of the write's attempt cycle, the re-send a refresh makes to finish a torn
118
+ * attempt included (`Collection.completeOwnEntry`). Every per-coordinator rebuild of the request
119
+ * keeps it (`pendRequestForBatch` in `NetworkTransactor`), since a batch that dropped it would
120
+ * lose the protection for that coordinator's share. Omitted rather than `false`, for the same
121
+ * preimage reason as {@link baseRevs}: a write that does not set it serializes exactly as before.
122
+ * A coordinator on an older build ignores it and commits alone at `local`; in a group of mixed
123
+ * versions the offline queue's reachability gate is then the only protection.
124
+ */
125
+ refuseSolo?: true;
107
126
  };
108
127
 
109
128
  export type BlockActionStatus = ActionBlocks & {
@@ -228,6 +247,12 @@ export type StaleFailure = {
228
247
  staleAt?: { blockId: BlockId; rev: number };
229
248
  /** Never set on a lost race — an expiry is its own failure shape, {@link ExpiredFailure}. */
230
249
  expired?: never;
250
+ /** Never set on a lost race — a cohort too few of whose members answered is its own failure
251
+ * shape, {@link ShortfallFailure}. */
252
+ shortfall?: never;
253
+ /** Never set on a lost race — a write judged invalid is its own failure shape,
254
+ * {@link RejectedFailure}. */
255
+ rejected?: never;
231
256
  };
232
257
 
233
258
  /**
@@ -264,10 +289,124 @@ export type ExpiredFailure = {
264
289
  missing?: never;
265
290
  pending?: never;
266
291
  staleAt?: never;
292
+ shortfall?: never;
293
+ rejected?: never;
294
+ };
295
+
296
+ /**
297
+ * Why a cohort's promise round fell short with no member refusing it as a lost race or a held block,
298
+ * and too few rejecting it for a rejection: too few members answered. Plain data, so it crosses the
299
+ * JSON repo protocol intact. `PromiseShortfallError` is built from it, wherever it is raised.
300
+ */
301
+ export type PromiseShortfall = {
302
+ /** Approve votes the round received. */
303
+ approvals: number;
304
+ /** Reject votes the round received — fewer than would make the round a rejection. */
305
+ rejections: number;
306
+ /** How many members the cohort the round ran on has. */
307
+ peerCount: number;
308
+ /** The approvals the round needed: `ceil(peerCount × superMajorityThreshold)`. */
309
+ needed: number;
310
+ /** Peer-id strings of the cohort members that cast no promise vote at all. */
311
+ silentPeers: string[];
312
+ /**
313
+ * Set only when no consensus round ran: a coordinator whose cohort for the write was only itself
314
+ * refused to write alone, because the write asked it to (`PendRequest.refuseSolo`). The other
315
+ * fields then describe the cohort the coordinator expected rather than one it asked: one approval
316
+ * (its own), no rejections, the members it knows of and could not reach as `silentPeers`, and the
317
+ * bar a cohort of that size would set. Absent on a shortfall a consensus round produced, so a log
318
+ * or an application can tell "refused to write alone" from "a round heard too few".
319
+ */
320
+ soloRefused?: SoloRefusalReason;
321
+ };
322
+
323
+ /**
324
+ * Why a lone coordinator refused a write that asked not to be committed alone
325
+ * (`PendRequest.refuseSolo`, `CommitRequest.refuseSolo`):
326
+ * - `absent-members`: its cohort for the write was only itself, and it knows of cohort members it
327
+ * could not place in that cohort (`IKeyNetwork.absentCohortMembers`);
328
+ * - `awaiting-bootstrap`: its cohort was only itself and it is still waiting to hear from a peer it
329
+ * was configured to join through (`IKeyNetwork.awaitingBootstrapContact`);
330
+ * - `unrouted`: the cohort lookup failed, named nobody, or named one peer that is not this node.
331
+ */
332
+ export type SoloRefusalReason = 'absent-members' | 'awaiting-bootstrap' | 'unrouted';
333
+
334
+ /**
335
+ * The cohort refused the pend because too few of its members ANSWERED the promise round for it to
336
+ * reach its bar — silence, not a judgement of the write and not a lost race. Not retryable by a write
337
+ * path: every coordinator of that cohort meets the same silent members, so a re-read and re-pend fails
338
+ * the same way until they come back. A sibling of {@link StaleFailure} and {@link ExpiredFailure},
339
+ * with the fields it can never carry typed `never`, so a consumer reads `reason`, `missing` or
340
+ * `staleAt` off any of them unnarrowed. Tell it apart with `isShortfallFailure`, never by reading
341
+ * `reason`. A pend answer only: a commit that falls short is still thrown (see
342
+ * `CoordinatorRepo.commit`).
343
+ */
344
+ export type ShortfallFailure = {
345
+ success: false;
346
+ /** The coordinator's description of the refusal, for a log line. Never branch on it. */
347
+ reason?: string;
348
+ /** Always false: silence is not a conflict a re-read can win. */
349
+ conflict: false;
350
+ shortfall: PromiseShortfall;
351
+ missing?: never;
352
+ pending?: never;
353
+ staleAt?: never;
354
+ expired?: never;
355
+ rejected?: never;
356
+ };
357
+
358
+ /**
359
+ * One refusal behind a {@link TransactionInvalidity}: a cohort member's validity-marked reject vote
360
+ * (`Signature`'s `validity`), or the validity verdict of the coordinating node's own storage-tier check
361
+ * (`StorageRepo.pend`, for a cohort of one, where no vote is cast).
362
+ */
363
+ export type ValidityRefusal = ValidityRejection & {
364
+ /** The refusing member's peer-id string. Absent for a refusal a node's storage made without a vote. */
365
+ peerId?: string;
366
+ /** The refuser's description, free-form, for a log line. Never branch on it. */
367
+ reason?: string;
368
+ };
369
+
370
+ /**
371
+ * Why a write was refused as INVALID: the members that sank it judged the transaction itself wrong
372
+ * (see {@link ValidityRejection} for which refusals qualify), and no refusal of any other kind sank it
373
+ * beside them, bar expiry votes. Plain data, so it crosses the JSON repo protocol intact.
374
+ * `ValidityRejectedError` is built from it, wherever it is raised.
375
+ */
376
+ export type TransactionInvalidity = {
377
+ /** Every validity refusal that sank the write. Never empty. */
378
+ refusals: ValidityRefusal[];
379
+ };
380
+
381
+ /**
382
+ * The cohort refused the write because the members that sank it judged it INVALID — the transaction
383
+ * failed its re-execution, its operations hash, its stamp or its client signature. Never retryable:
384
+ * re-sending the same content to the same checks is refused the same way. A sibling of
385
+ * {@link StaleFailure}, {@link ExpiredFailure} and {@link ShortfallFailure}, with the fields it can
386
+ * never carry typed `never`, so a consumer reads `reason`, `missing` or `staleAt` off any of them
387
+ * unnarrowed. Tell it apart with `isRejectedFailure`, never by reading `reason`.
388
+ *
389
+ * A pend answer only, and only when nothing else could explain the rejection: a reject vote with no
390
+ * validity marker beside the marked ones (a stale revision, a member on an older build) leaves the
391
+ * rejection unclassified, and a revision loss the coordinator's own storage confirms is returned as
392
+ * the {@link StaleFailure} it is, since the writer's rebase sends different content.
393
+ */
394
+ export type RejectedFailure = {
395
+ success: false;
396
+ /** The coordinator's description of the refusal, for a log line. Never branch on it. */
397
+ reason?: string;
398
+ /** Always false: a verdict on the content is not a conflict a re-read can win. */
399
+ conflict: false;
400
+ rejected: TransactionInvalidity;
401
+ missing?: never;
402
+ pending?: never;
403
+ staleAt?: never;
404
+ expired?: never;
405
+ shortfall?: never;
267
406
  };
268
407
 
269
408
  /** Every way a pend or a commit can be refused with an answer rather than a throw. */
270
- export type WriteFailure = StaleFailure | ExpiredFailure;
409
+ export type WriteFailure = StaleFailure | ExpiredFailure | ShortfallFailure | RejectedFailure;
271
410
 
272
411
  export type PendResult = PendSuccess | WriteFailure;
273
412
 
@@ -324,6 +463,17 @@ export type CommitRequest = ActionBlocks & {
324
463
  // by literally writing `undefined`. Revisit if undeclared commits ever become common enough to show
325
464
  // up as replication-factor decay.
326
465
  blockDigests?: BlockContentDigests;
466
+ /**
467
+ * {@link PendRequest.refuseSolo}, on the commit. A coordinator whose cohort for the commit is only
468
+ * itself refuses it on the same rule, before minting a proof or applying anything, with a
469
+ * conflict-shaped refusal (`SOLO_COMMIT_REFUSED_REASON` in db-p2p), since a commit cannot answer
470
+ * with a shortfall. That is reached when the pend ran on a real cohort and the partner dropped
471
+ * before the commit: the writer cancels and retries, and the retry's pend meets the pend-side
472
+ * refusal. Carried through every per-coordinator rebuild of the commit (`repoCommitRequest` in
473
+ * `NetworkTransactor`); omitted rather than `false` for the preimage reason
474
+ * {@link blockDigests} is.
475
+ */
476
+ refuseSolo?: true;
327
477
  };
328
478
 
329
479
  /**
@@ -573,6 +723,8 @@ export type PendValidationResult = {
573
723
  valid: boolean;
574
724
  /** Reason for validation failure (if valid=false) */
575
725
  reason?: string;
726
+ /** Set only on a failure that judges the transaction itself wrong; see {@link ValidityRejection}. */
727
+ validity?: ValidityRejection;
576
728
  };
577
729
 
578
730
  /**
@@ -0,0 +1,55 @@
1
+ import type { RejectedFailure, TransactionInvalidity, ValidityRefusal } from "./struct.js";
2
+
3
+ /**
4
+ * A write the cohort refused because the members that sank it judged the transaction INVALID: it failed
5
+ * its re-execution, its operations hash, its stamp or its client signature (`ValidityRejection` in
6
+ * `transaction/transaction.ts` says which refusals qualify). Not retryable — re-sending the same
7
+ * content to the same checks is refused the same way. Nothing was saved: the members that approved
8
+ * release their reservation when the writer cancels.
9
+ *
10
+ * ONE class for every place it is raised, as `TransactionExpiredError` is. The coordinating repo (db-p2p
11
+ * `CoordinatorRepo`) returns its facts as a {@link RejectedFailure} ({@link toFailure}) when every reject
12
+ * that sank a pend was validity-marked or an expiry vote and its own storage confirms no revision loss,
13
+ * and a cohort of one's storage tier returns the same for its own check; each write path
14
+ * (`Collection.sync`, `TransactionCoordinator.commit`) raises it again from that refusal.
15
+ *
16
+ * Not the dispute answer. With disputes enabled, a marked rejection beside approvals is held for a ruling
17
+ * before it ends the pend, and that writer is answered with the dispute's own refusal (backlog
18
+ * `dispute-commit-path-block`, `dispute-writer-sees-disputed-pend`); this error stays the answer for a
19
+ * rejection no approval contests.
20
+ */
21
+ export class ValidityRejectedError extends Error {
22
+ /** Every validity refusal that sank the write. Never empty. */
23
+ readonly refusals: readonly ValidityRefusal[];
24
+
25
+ constructor(invalidity: TransactionInvalidity) {
26
+ // NOTE: `invalidity` off the wire is trusted as shaped (`isRejectedFailure` checks only presence),
27
+ // so a malformed coordinator answer throws a TypeError here (no `refusals` array) instead of this
28
+ // error. Either still ends the write; if hostile coordinators become a concern, validate the shape
29
+ // where the refusal is received, as for `TransactionExpiredError`.
30
+ super(validityRejectedMessage(invalidity.refusals));
31
+ this.name = 'ValidityRejectedError';
32
+ this.refusals = invalidity.refusals.map(refusal => ({ ...refusal }));
33
+ }
34
+
35
+ /** The refusal a coordinating repo returns for this error, so it crosses the repo protocol as an
36
+ * answer rather than as a reset stream. */
37
+ toFailure(): RejectedFailure {
38
+ return {
39
+ success: false,
40
+ conflict: false,
41
+ reason: this.message,
42
+ rejected: { refusals: this.refusals.map(refusal => ({ ...refusal })) },
43
+ };
44
+ }
45
+ }
46
+
47
+ /** Written to be shown to a person. Names each refuser — the member's peer id, or the coordinating
48
+ * node's own check where no vote was cast — with the reason it gave. */
49
+ function validityRejectedMessage(refusals: readonly ValidityRefusal[]): string {
50
+ const details = refusals
51
+ .map(refusal => `${refusal.peerId ?? 'coordinating node'}: ${refusal.reason ?? 'no reason given'}`)
52
+ .join('; ');
53
+ return `The transaction was rejected as invalid by ${refusals.length} validator(s) (${details}). `
54
+ + `This is a verdict on the transaction itself, not a conflict or an unreachable cohort, and sending it again is refused the same way.`;
55
+ }
@@ -0,0 +1,127 @@
1
+ import type { ActionId, AlreadyAppliedTally } from '../collection/action.js';
2
+ import { addTallies, ZeroTally } from '../collection/action.js';
3
+ import type { Collection } from '../collection/collection.js';
4
+ import type { EntryId } from '../collection/segments.js';
5
+ import type { CollectionId, InFlightAttempt } from '../collection/struct.js';
6
+ import type { WriteDurability } from '../network/struct.js';
7
+ import type { CommittedEffect, EntryStatus, EntryWaitingFor, QueuedEntry } from './status.js';
8
+ import type { JournalDriveState } from './journal.js';
9
+
10
+ /** One queued entry, as `OfflineQueue` holds it, and the projections of it the queue reports. */
11
+ export type Entry = {
12
+ readonly id: EntryId;
13
+ readonly seq: number;
14
+ readonly queuedAt: number;
15
+ readonly expiresAt: number | undefined;
16
+ /** The collections the entry sealed a segment in — the ones `sealPending` answered `true` for. */
17
+ readonly collections: readonly Collection<any>[];
18
+ /** One action id for the entry's whole life, with one exception: a `torn-not-saved` outcome mints
19
+ * a fresh one (the queue's `applyFailure` says why). */
20
+ actionId: ActionId;
21
+ attempts: number;
22
+ /** Whether an attempt may have landed; sticky — see the NOTE at the queue's `recordAttempts`. */
23
+ inDoubt: boolean;
24
+ /** The attempts recorded under `actionId` and not yet resolved, per collection, handed back as
25
+ * `resume` when the entry is re-driven. Cleared with the action id. */
26
+ readonly retained: Map<CollectionId, InFlightAttempt>;
27
+ /** The collections a partial commit has already committed, with who holds each, accumulated
28
+ * across submissions (`recordCollectionDurability`); empty until one does. The committed half's
29
+ * segments are consumed, so the next submission drives only the rest, and the terminal status
30
+ * reports these beside it. */
31
+ readonly committed: Map<CollectionId, WriteDurability | undefined>;
32
+ /** What each collection's head segment accepted as already applied when it was committed, as the
33
+ * `onCommittedHead` hooks reported it — across submissions, so a partial commit's committed half is
34
+ * recorded before the error reaches the queue and a later submission's tallies accumulate beside
35
+ * it. A collection a restore found already committed records nothing. Folded into the `committed`
36
+ * status's `effect` ({@link effectOf}, which answers `applied` while any collection the entry wrote
37
+ * has no tally here). In memory only: a restart between a partial commit and the remainder's commit
38
+ * loses the committed half's tally, and the entry then reports `applied`, the conservative answer,
39
+ * whatever the remainder reports. */
40
+ readonly applied: Map<CollectionId, AlreadyAppliedTally>;
41
+ phase: 'queued' | 'submitting';
42
+ waitingFor: EntryWaitingFor | undefined;
43
+ lastError: unknown;
44
+ /** The last `queued` status emitted, so a re-check that changes nothing emits nothing. */
45
+ lastQueued: QueuedStatus | undefined;
46
+ /** The `offline:expiry-deferred` line is logged once per entry, not once per re-check. */
47
+ expiryDeferredLogged: boolean;
48
+ };
49
+
50
+ export type QueuedStatus = Extract<EntryStatus, { kind: 'queued' }>;
51
+
52
+ export function queuedStatus(entry: Entry): QueuedStatus {
53
+ return {
54
+ kind: 'queued',
55
+ entryId: entry.id,
56
+ seq: entry.seq,
57
+ collections: entry.collections.map(collection => collection.id),
58
+ queuedAt: entry.queuedAt,
59
+ attempts: entry.attempts,
60
+ inDoubt: entry.inDoubt,
61
+ waitingFor: entry.waitingFor,
62
+ ...(entry.lastError === undefined ? {} : { lastError: entry.lastError }),
63
+ ...committedField(entry),
64
+ };
65
+ }
66
+
67
+ /** `{ committedCollections }` once part of the entry has committed, `{}` before — the field the
68
+ * `queued` and `failed` statuses and {@link snapshot} carry only when it says something. */
69
+ export function committedField(entry: Entry): { committedCollections?: readonly CollectionId[] } {
70
+ return entry.committed.size === 0 ? {} : { committedCollections: [...entry.committed.keys()] };
71
+ }
72
+
73
+ export function currentStatus(entry: Entry): EntryStatus {
74
+ return entry.phase === 'submitting'
75
+ ? { kind: 'submitting', entryId: entry.id, attempt: entry.attempts }
76
+ : queuedStatus(entry);
77
+ }
78
+
79
+ /** The entry as `OfflineQueue.entries` lists it. */
80
+ export function snapshot(entry: Entry): QueuedEntry {
81
+ return {
82
+ id: entry.id,
83
+ seq: entry.seq,
84
+ queuedAt: entry.queuedAt,
85
+ collections: entry.collections.map(collection => collection.id),
86
+ ...committedField(entry),
87
+ status: currentStatus(entry),
88
+ };
89
+ }
90
+
91
+ /** Whether two `queued` statuses differ in anything an application can see. */
92
+ export function queuedStatusChanged(previous: QueuedStatus | undefined, status: QueuedStatus): boolean {
93
+ return previous === undefined
94
+ || previous.waitingFor !== status.waitingFor
95
+ || previous.attempts !== status.attempts
96
+ || previous.inDoubt !== status.inDoubt
97
+ || previous.lastError !== status.lastError
98
+ // The committed set only grows, so its size says whether it changed.
99
+ || previous.committedCollections?.length !== status.committedCollections?.length;
100
+ }
101
+
102
+ /** The `effect` of a committed entry ({@link CommittedEffect}): `already-applied` exactly when EVERY
103
+ * collection the entry wrote reported a tally and the tallies sum to `alreadyApplied > 0` and
104
+ * `applied === 0`. A collection whose tally was never heard — one committed before a restart, or one
105
+ * a restore found already committed — may have changed rows, so its absence answers `applied`: a
106
+ * remainder that was wholly already applied must not speak for a half that was not. */
107
+ export function effectOf(entry: Entry): CommittedEffect {
108
+ let total = ZeroTally;
109
+ for (const collection of entry.collections) {
110
+ const tally = entry.applied.get(collection.id);
111
+ if (tally === undefined) return 'applied';
112
+ total = addTallies(total, tally);
113
+ }
114
+ return total.alreadyApplied > 0 && total.applied === 0 ? 'already-applied' : 'applied';
115
+ }
116
+
117
+ /** The entry's drive state as the journal records it (`IOfflineJournal.driving`): its action id,
118
+ * the attempts retained under it — with `attempts`, the ones about to be sent, laid over them when
119
+ * given — and the collections already committed. Copies, so the journal serialises a state the
120
+ * drain cannot change under it. */
121
+ export function driveState(entry: Entry, attempts?: ReadonlyMap<CollectionId, InFlightAttempt>): JournalDriveState {
122
+ return {
123
+ actionId: entry.actionId,
124
+ attempts: new Map([...entry.retained, ...(attempts ?? [])]),
125
+ committed: new Map(entry.committed),
126
+ };
127
+ }
@@ -0,0 +1,4 @@
1
+ export * from './reachability.js';
2
+ export * from './status.js';
3
+ export * from './journal.js';
4
+ export * from './queue.js';
@@ -0,0 +1,60 @@
1
+ import type { Action, ActionId } from '../collection/action.js';
2
+ import type { EntryId } from '../collection/segments.js';
3
+ import type { CollectionId, InFlightAttempt } from '../collection/struct.js';
4
+ import type { WriteDurability } from '../network/struct.js';
5
+ import type { EntryStatus } from './status.js';
6
+
7
+ /**
8
+ * The port a durable journal fills (docs/offline-sync.md §Persistence): the queue calls it at every
9
+ * moment the design's write ordering names — after sealing and before `queued` is emitted, before
10
+ * each send, after a partial commit, after an identity renewal, and before each terminal status —
11
+ * so a journal can save queued entries to disk without the drain knowing where. It speaks the
12
+ * queue's vocabulary only (entry ids, collection ids, actions, `InFlightAttempt`s): a journal over a
13
+ * key-value store, which also has to name tables, lives with the Quereus plugin, and a `Tree` or
14
+ * `Diary` application with no SQL can journal through this port too. A queue built without a
15
+ * journal behaves exactly as before.
16
+ */
17
+
18
+ /** One entry as the journal records it at enqueue, written once (docs/offline-sync.md §What is
19
+ * journaled). */
20
+ export type JournalEntryRecord = {
21
+ readonly id: EntryId;
22
+ readonly seq: number;
23
+ readonly queuedAt: number;
24
+ readonly expiresAt?: number;
25
+ /** One per collection the entry sealed a segment in, in sealing order: the segment's actions,
26
+ * verbatim — the array the segment holds, which the journal serialises and never mutates. */
27
+ readonly segments: readonly { readonly collectionId: CollectionId; readonly actions: readonly Action<unknown>[] }[];
28
+ };
29
+
30
+ /** The drive state of an entry: everything that changes between sends and must be on disk before
31
+ * the next one (docs/offline-sync.md §Identity across attempts). */
32
+ export type JournalDriveState = {
33
+ /** The action id the next submission runs under (renewed after `torn-not-saved`). */
34
+ readonly actionId: ActionId;
35
+ /** The attempts recorded under `actionId` and not yet resolved, per collection — the ones a later
36
+ * cycle resumes from. Empty right after a renewal. */
37
+ readonly attempts: ReadonlyMap<CollectionId, InFlightAttempt>;
38
+ /** The collections a partial commit has already committed, with who holds each. */
39
+ readonly committed: ReadonlyMap<CollectionId, WriteDurability | undefined>;
40
+ };
41
+
42
+ /** The two terminal statuses, as the journal is told them before they are emitted. */
43
+ export type JournalSettledStatus = Extract<EntryStatus, { kind: 'committed' | 'failed' }>;
44
+
45
+ export interface IOfflineJournal {
46
+ /** Before the entry's `queued` status is emitted and before `enqueue` resolves. A throw or
47
+ * rejection fails the enqueue: the segments are unsealed and nothing is queued. The journal must
48
+ * flush before resolving. */
49
+ queued(record: JournalEntryRecord): Promise<void>;
50
+ /** Before each send, with the attempts about to go; again after a partial commit and after an
51
+ * identity renewal. Before a send, a throw aborts the cycle with nothing sent (the entry stays
52
+ * queued, not in doubt, re-driven after the backoff). After a partial commit or a renewal a throw
53
+ * is logged (`offline:journal-write-failed`) and the drain goes on; the next send's write repeats
54
+ * the state. The journal must flush before resolving. */
55
+ driving(entryId: EntryId, state: JournalDriveState): Promise<void>;
56
+ /** The entry's terminal status, before it is emitted. A throw is logged, never thrown into the
57
+ * drain: the outcome stands, and a restart resolves the stale record
58
+ * (docs/offline-sync.md §Restore after a restart). */
59
+ settled(status: JournalSettledStatus): Promise<void>;
60
+ }