@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
@@ -1,7 +1,8 @@
1
1
  import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, CommitRequest, ActionId } from "../index.js";
2
2
  import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
3
3
  import type { PeerId } from "../network/types.js";
4
- import { isConflictFailure } from "../network/stale-failure.js";
4
+ import { isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
5
+ import { TransactionExpiredError } from "../network/transaction-expired-error.js";
5
6
  import type { Collection, CollectionSnapshot, RefreshReport } from "../collection/collection.js";
6
7
  import type { SyncOptions } from "../collection/index.js";
7
8
  import { TornActionError } from "../collection/struct.js";
@@ -304,7 +305,10 @@ export class TransactionCoordinator {
304
305
  * still never re-drive a partial landing itself. A partial landing on a HARD failure (the
305
306
  * transport budget spent, a structural rejection) escapes at once as
306
307
  * {@link CoordinatorPartialCommitError}, and any other failure (expired transaction,
307
- * unavailable transactor, unreachable cluster) also propagates without retry.
308
+ * unavailable transactor, unreachable cluster) also propagates without retry — including a pend
309
+ * or commit the cohort refused because the transaction had expired by its members' clocks, which
310
+ * surfaces as {@link TransactionExpiredError} (inside a partial commit's `reason` once a sibling
311
+ * has landed).
308
312
  *
309
313
  * A participant can also be SAVED between attempts: an attempt that reported a loss may still
310
314
  * have stored that participant's log tail, and the refresh before the next attempt then finishes
@@ -719,6 +723,7 @@ export class TransactionCoordinator {
719
723
  committedCollections?: Set<CollectionId>;
720
724
  failedCollections?: Set<CollectionId>;
721
725
  staleLoss?: boolean;
726
+ expired?: TransactionExpiredError;
722
727
  };
723
728
  try {
724
729
  for (const { collectionId, collection } of collectionData) {
@@ -835,7 +840,7 @@ export class TransactionCoordinator {
835
840
  // stamp tracking (the success path does the same at the end) and surface the
836
841
  // structured signal for reconciliation at once.
837
842
  this.stampData.delete(transaction.stamp.id);
838
- throw new CoordinatorPartialCommitError([...committed], failed, coordResult.error);
843
+ throw new CoordinatorPartialCommitError([...committed], failed, coordResult.expired ?? coordResult.error);
839
844
  }
840
845
 
841
846
  // EMPTY committed set: PEND failed, or the whole commit failed cleanly with
@@ -851,6 +856,11 @@ export class TransactionCoordinator {
851
856
  if (coordResult.staleLoss) {
852
857
  throw new CoordinatorStaleLossError([...(coordResult.failedCollections ?? new Set(allCollectionIds))], coordResult.error);
853
858
  }
859
+ // An expiry is surfaced by name and never re-driven: the retry's pend would carry an
860
+ // expiration from the same clock.
861
+ if (coordResult.expired !== undefined) {
862
+ throw coordResult.expired;
863
+ }
854
864
  throw new Error(`Transaction commit failed: ${coordResult.error}`);
855
865
  }
856
866
 
@@ -1416,6 +1426,9 @@ export class TransactionCoordinator {
1416
1426
  /** True when the failure was a clean optimistic-concurrency conflict (stale loss / pending
1417
1427
  * contention) with nothing durable — i.e. safe to re-drive after a re-read. */
1418
1428
  staleLoss?: boolean;
1429
+ /** Present when a pend or a commit was refused because the transaction had expired by the
1430
+ * cohort's clocks: the error the commit surfaces, never a stale loss. */
1431
+ expired?: TransactionExpiredError;
1419
1432
  }> {
1420
1433
  const trxId = transaction.id;
1421
1434
  const t0 = Date.now();
@@ -1467,6 +1480,7 @@ export class TransactionCoordinator {
1467
1480
  committedCollections: commitResult.committedCollections,
1468
1481
  failedCollections: commitResult.failedCollections,
1469
1482
  staleLoss: commitResult.staleLoss,
1483
+ ...(commitResult.expired === undefined ? {} : { expired: commitResult.expired }),
1470
1484
  };
1471
1485
  }
1472
1486
 
@@ -1539,7 +1553,7 @@ export class TransactionCoordinator {
1539
1553
  collectionTransforms: ReadonlyMap<CollectionId, Transforms>,
1540
1554
  pendedRevs: ReadonlyMap<CollectionId, number>,
1541
1555
  superclusterNominees: ReadonlySet<PeerId> | null
1542
- ): Promise<{ success: boolean; error?: string; pendedBlockIds?: Map<CollectionId, BlockId[]>; staleLoss?: boolean }> {
1556
+ ): Promise<{ success: boolean; error?: string; pendedBlockIds?: Map<CollectionId, BlockId[]>; staleLoss?: boolean; expired?: TransactionExpiredError }> {
1543
1557
  if (collectionTransforms.size === 0) {
1544
1558
  return { success: false, error: 'No transforms to pend' };
1545
1559
  }
@@ -1569,6 +1583,8 @@ export class TransactionCoordinator {
1569
1583
  // re-driving it would just burn the retry budget — fail fast instead.
1570
1584
  let anyConflict = false;
1571
1585
  let anyHard = false;
1586
+ // An expiry is a hard failure too, and is carried whole: it is the error the commit surfaces.
1587
+ let expired: TransactionExpiredError | undefined;
1572
1588
  for (const outcome of outcomes) {
1573
1589
  if (outcome.status === 'fulfilled') {
1574
1590
  pendedBlockIds.set(outcome.value.collectionId, outcome.value.blockIds);
@@ -1578,6 +1594,7 @@ export class TransactionCoordinator {
1578
1594
  }
1579
1595
  if (outcome.reason instanceof PendRejectedError && outcome.reason.conflict) anyConflict = true;
1580
1596
  else anyHard = true;
1597
+ if (outcome.reason instanceof TransactionExpiredError) expired ??= outcome.reason;
1581
1598
  }
1582
1599
  }
1583
1600
 
@@ -1587,7 +1604,7 @@ export class TransactionCoordinator {
1587
1604
  // only those started before the failure. Cancels are best-effort (cancelPhase
1588
1605
  // swallows their errors) so they cannot mask the original pend failure.
1589
1606
  await this.cancelPhase(actionId, pendedBlockIds);
1590
- return { success: false, error: failure, staleLoss: anyConflict && !anyHard };
1607
+ return { success: false, error: failure, staleLoss: anyConflict && !anyHard, ...(expired === undefined ? {} : { expired }) };
1591
1608
  }
1592
1609
 
1593
1610
  return { success: true, pendedBlockIds };
@@ -1643,6 +1660,9 @@ export class TransactionCoordinator {
1643
1660
 
1644
1661
  const pendResult = await this.transactor.pend(pendRequest);
1645
1662
  if (!pendResult.success) {
1663
+ if (isExpiryFailure(pendResult)) {
1664
+ throw new TransactionExpiredError(pendResult.expired);
1665
+ }
1646
1666
  // Retryability comes from the response itself: a producer that classified the failure sets
1647
1667
  // `conflict`, and only where no producer set it do we fall back to inferring from
1648
1668
  // `missing`/`pending`. Either way a conflict is an optimistic-concurrency loss, clearable
@@ -1671,6 +1691,7 @@ export class TransactionCoordinator {
1671
1691
  committedCollections: Set<CollectionId>;
1672
1692
  failedCollections: Set<CollectionId>;
1673
1693
  staleLoss?: boolean;
1694
+ expired?: TransactionExpiredError;
1674
1695
  }> {
1675
1696
  // Fan out the independent per-collection commit-with-retry concurrently, then
1676
1697
  // aggregate the committed/failed partition from the settled results.
@@ -1689,6 +1710,7 @@ export class TransactionCoordinator {
1689
1710
  // re-driving.
1690
1711
  let anyStale = false;
1691
1712
  let anyHard = false;
1713
+ let expired: TransactionExpiredError | undefined;
1692
1714
  for (const outcome of outcomes) {
1693
1715
  if (outcome.status === 'fulfilled') {
1694
1716
  const { collectionId, committed, error, stale } = outcome.value;
@@ -1698,6 +1720,7 @@ export class TransactionCoordinator {
1698
1720
  failedCollections.add(collectionId);
1699
1721
  if (error) errors.push(error);
1700
1722
  if (stale) anyStale = true; else anyHard = true;
1723
+ expired ??= outcome.value.expired;
1701
1724
  }
1702
1725
  } else {
1703
1726
  // commitCollection resolves rather than rejects, but treat any unexpected
@@ -1714,6 +1737,7 @@ export class TransactionCoordinator {
1714
1737
  committedCollections,
1715
1738
  failedCollections,
1716
1739
  staleLoss: anyStale && !anyHard,
1740
+ ...(expired === undefined ? {} : { expired }),
1717
1741
  };
1718
1742
  }
1719
1743
 
@@ -1734,7 +1758,7 @@ export class TransactionCoordinator {
1734
1758
  * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
1735
1759
  * trips, could stamp the CommitRequest with a different number than the pend named. */
1736
1760
  rev: number
1737
- ): Promise<{ collectionId: CollectionId; committed: boolean; error?: string; stale?: boolean }> {
1761
+ ): Promise<{ collectionId: CollectionId; committed: boolean; error?: string; stale?: boolean; expired?: TransactionExpiredError }> {
1738
1762
  const collection = this.collections.get(collectionId);
1739
1763
  if (!collection) {
1740
1764
  return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
@@ -1778,6 +1802,11 @@ export class TransactionCoordinator {
1778
1802
  if (commitResult.success) {
1779
1803
  return { collectionId, committed: true };
1780
1804
  }
1805
+ if (isExpiryFailure(commitResult)) {
1806
+ // Not a stale loss: a re-drive's expiration comes from the same clock.
1807
+ const expired = new TransactionExpiredError(commitResult.expired);
1808
+ return { collectionId, committed: false, error: expired.message, expired };
1809
+ }
1781
1810
  // Permanent stale failure: do not retry here. It IS a clean stale loss, though, so
1782
1811
  // mark it retryable at the coordinator level (after a re-read advances the rev).
1783
1812
  // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict`
@@ -1791,7 +1820,8 @@ export class TransactionCoordinator {
1791
1820
  // stale-commit rejections as `{ success:false, conflict:true }` (returning, not
1792
1821
  // throwing, is what keeps them out of the verbatim retry above) — but every returned
1793
1822
  // failure still maps to `stale: true` here, and `isConflictFailure` covers that new
1794
- // shape, so no behavior change is needed. If a commit producer ever starts returning
1823
+ // shape, so no behavior change is needed. The one returned refusal that is NOT a stale
1824
+ // loss, an expiry, is split off above. If a commit producer ever starts returning other
1795
1825
  // hard commit rejections (validator policy, storage fault) as results too, gate
1796
1826
  // `stale` on isConflictFailure here.
1797
1827
  return {
@@ -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;
@@ -1,10 +1,10 @@
1
1
  import { peerIdFromString } from "../network/types.js";
2
2
  import type { PeerId } from "../network/types.js";
3
- import { highestStaleAt, isConflictFailure } from "../network/stale-failure.js";
3
+ import { highestStaleAt, isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
4
4
  import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
5
5
  import { mergeDurability, withTornBlocks } from "../network/durability.js";
6
6
  import { judgeCohortLineage, type CohortLineage, type MemberLineage } from "../network/lineage.js";
7
- import type { ActionTransforms, ActionBlocks, ActionLineage, BlockActionStatus, ITransactor, PendSuccess, CommitSuccess, StaleFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, GetBlockResult, CoordinatorIntent, BlockUnavailableReason, BlockContentDigests, BlockBaseRevs, WriteDurability } from "../index.js";
7
+ import type { ActionTransforms, ActionBlocks, ActionLineage, BlockActionStatus, ITransactor, PendSuccess, CommitSuccess, StaleFailure, WriteFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, GetBlockResult, CoordinatorIntent, BlockUnavailableReason, BlockContentDigests, BlockBaseRevs, WriteDurability } from "../index.js";
8
8
  import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
9
9
  import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
10
10
  import { Tracker } from "../transform/tracker.js";
@@ -310,9 +310,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
310
310
  // it: 'cohort-unreachable' is the one reason a caller may treat permissively (the
311
311
  // answering node reached nobody, so its own view is all it has), and a partitioned
312
312
  // coordinator answering first must not mask a well-connected one that positively
313
- // established the block EXISTS ('claimed-elsewhere', or 'unmaterializable' — records
314
- // held here). 'peers-unreachable' sits between: it establishes that some of the cohort
315
- // was reachable, without settling existence.
313
+ // established the block EXISTS ('claimed-elsewhere', 'named-by-log' — the caller's own
314
+ // floor names it — or 'unmaterializable' — records held here). 'peers-unreachable' sits
315
+ // between: it establishes that some of the cohort was reachable, without settling existence.
316
316
  const unavailableRank = (reason: BlockUnavailableReason): number =>
317
317
  reason === 'cohort-unreachable' ? 0 : reason === 'peers-unreachable' ? 1 : 2;
318
318
  const rankOf = (r: unknown): number => {
@@ -727,35 +727,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
727
727
  const stale = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
728
728
  if (stale.length > 0) { // Any active stale failures should preempt reporting connection or other potential transient errors (we have information)
729
729
  log('pend:stale actionId=%s staleCount=%d', blockAction.actionId, stale.length);
730
- // Carry the first available reject reason through: `SyncRetryExhaustedError.lastReason`
731
- // and the multi-collection writer's failure message both read it, and it is the only
732
- // diagnostic that survives an exhausted retry budget.
733
- const reason = stale.map(b => (b.request!.response! as StaleFailure).reason).find(r => r !== undefined);
734
- // This response is REBUILT from the per-batch ones rather than forwarded, so
735
- // retryability has to be carried explicitly or it is lost: a batch whose failure was
736
- // a confirmed lost race can arrive with neither `missing` nor `pending` (see
737
- // CoordinatorRepo.classifyStaleRejection), and the aggregate would then look like a
738
- // hard rejection to `isConflictFailure`. Any conflicting batch makes the aggregate a
739
- // conflict — the pend failed as a whole, and a re-read/rebase can clear it.
740
- // NOTE: `some`, not `every`, so a pend whose batches mix a lost race with a genuine hard
741
- // rejection is reported retryable and burns its (bounded, backed-off) retry budget before
742
- // failing. Deliberate: an unclassified reason-only response from an older peer is
743
- // indistinguishable from a hard rejection here, and `every` would refuse to retry a real
744
- // race whenever one batch came from such a peer. Revisit if every producer sets `conflict`
745
- // (then `every` is both safe and tighter), or if mixed-outcome pends show up as wasted
746
- // retry latency in practice.
747
- const conflict = stale.some(b => isConflictFailure(b.request!.response! as StaleFailure));
748
- // Deliberately NOT first-wins like `reason` above — `highestStaleAt` takes the largest
749
- // confirmed revision, which is the binding constraint on the client's next request.
750
- // Its doc comment carries the rule and the one-pend-one-collection assumption it rests on.
751
- const staleAt = highestStaleAt(stale.map(b => (b.request!.response! as StaleFailure).staleAt));
752
- return {
753
- success: false,
754
- conflict,
755
- ...(reason === undefined ? {} : { reason }),
756
- ...(staleAt === undefined ? {} : { staleAt }),
757
- missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)),
758
- };
730
+ // This response is REBUILT from the per-batch ones rather than forwarded, by the same
731
+ // rule the commit side uses — see `refusalFrom` for what is carried and why.
732
+ return refusalFrom(stale.map(b => b.request!.response! as WriteFailure));
759
733
  }
760
734
  throw error; // No stale failures, report the original error
761
735
  }
@@ -1101,9 +1075,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
1101
1075
  * sweep — both must distinguish a confirmed conflict (return it; the caller cancels and
1102
1076
  * re-drives) from a transient fault (throw / tolerate).
1103
1077
  */
1104
- private staleFromBatches(batches: CoordinatorBatch<BlockId[], CommitResult>[]): StaleFailure | undefined {
1078
+ private staleFromBatches(batches: CoordinatorBatch<BlockId[], CommitResult>[]): WriteFailure | undefined {
1105
1079
  const stale = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
1106
- return stale.length === 0 ? undefined : refusalFrom(stale.map(b => b.request!.response! as StaleFailure));
1080
+ return stale.length === 0 ? undefined : refusalFrom(stale.map(b => b.request!.response! as WriteFailure));
1107
1081
  }
1108
1082
 
1109
1083
  /**
@@ -1440,14 +1414,33 @@ function confirmedDurabilities(batches: CoordinatorBatch<BlockId[], CommitResult
1440
1414
  }
1441
1415
 
1442
1416
  /**
1443
- * One {@link StaleFailure} standing for every refused commit response in `responses`, rebuilt the
1444
- * same way {@link NetworkTransactor.pend}'s aggregate is: `reason` is the first one any response gave
1445
- * (the only diagnostic that survives into the coordinator's error text — a refusal whose reason is
1446
- * `commit-not-durable` must not read as "stale commit", a rival's win), `conflict` holds when any
1447
- * response was a classified conflict, and `staleAt` is the highest confirmed revision. A reason-only
1448
- * refusal (no `missing`) comes out with `missing: []` and its reason intact.
1417
+ * One refusal standing for every refused response in `responses` — the single rebuild both
1418
+ * {@link NetworkTransactor.pend} and the commit paths use, since the action-level answer is rebuilt
1419
+ * from per-batch ones rather than forwarded, and anything not carried here is lost.
1420
+ *
1421
+ * - An **expiry** anywhere ({@link isExpiryFailure}) is the answer, verbatim — the first one. No
1422
+ * retry can succeed while that cohort's clocks disagree with the writer's, so a conflict beside it
1423
+ * must not make the write look retryable, and its numbers must reach the writer whole.
1424
+ * - Otherwise a {@link StaleFailure}: `reason` is the first one any response gave (the only diagnostic
1425
+ * that survives an exhausted retry budget and the coordinator's error text — a refusal whose reason
1426
+ * is `commit-not-durable` must not read as "stale commit", a rival's win); `staleAt` is the highest
1427
+ * confirmed revision (`highestStaleAt`, the binding constraint on the next request); and `conflict`
1428
+ * holds when ANY response was a conflict, because a batch whose failure was a confirmed lost race
1429
+ * can arrive with neither `missing` nor `pending` (`CoordinatorRepo.classifyStaleRejection`), so
1430
+ * retryability has to be carried explicitly. A reason-only refusal comes out with `missing: []`.
1431
+ *
1432
+ * NOTE: `some`, not `every`, for `conflict`, so a write whose batches mix a lost race with a genuine
1433
+ * hard rejection is reported retryable and burns its (bounded, backed-off) retry budget before
1434
+ * failing. Deliberate: an unclassified reason-only response from an older peer is indistinguishable
1435
+ * from a hard rejection here, and `every` would refuse to retry a real race whenever one batch came
1436
+ * from such a peer. Revisit if every producer sets `conflict` (then `every` is both safe and tighter),
1437
+ * or if mixed-outcome writes show up as wasted retry latency in practice.
1449
1438
  */
1450
- function refusalFrom(responses: StaleFailure[]): StaleFailure {
1439
+ function refusalFrom(responses: WriteFailure[]): WriteFailure {
1440
+ const expired = responses.find(isExpiryFailure);
1441
+ if (expired !== undefined) {
1442
+ return expired;
1443
+ }
1451
1444
  const staleAt = highestStaleAt(responses.map(r => r.staleAt));
1452
1445
  const reason = responses.map(r => r.reason).find(r => r !== undefined);
1453
1446
  return {
@@ -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
  }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * ISO-8601 for a representable instant (unix ms), the bare number otherwise. For log and error prose
3
+ * about instants that arrived off the wire: `Date.prototype.toISOString` throws on an invalid date
4
+ * (beyond ±8.64e15 ms, or not a number at all), and a throw while describing a refusal would replace
5
+ * the refusal.
6
+ */
7
+ export function formatInstant(ms: number): string {
8
+ const date = new Date(ms);
9
+ return Number.isNaN(date.getTime()) ? String(ms) : date.toISOString();
10
+ }