@optimystic/db-core 1.12.0 → 1.13.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 (63) hide show
  1. package/dist/src/cluster/i-cluster.d.ts +16 -1
  2. package/dist/src/cluster/i-cluster.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.d.ts +48 -6
  4. package/dist/src/cluster/structs.d.ts.map +1 -1
  5. package/dist/src/cluster/structs.js +5 -0
  6. package/dist/src/cluster/structs.js.map +1 -1
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +5 -3
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/network/durability.d.ts +17 -4
  11. package/dist/src/network/durability.d.ts.map +1 -1
  12. package/dist/src/network/durability.js +60 -15
  13. package/dist/src/network/durability.js.map +1 -1
  14. package/dist/src/network/i-key-network.d.ts +9 -0
  15. package/dist/src/network/i-key-network.d.ts.map +1 -1
  16. package/dist/src/network/struct.d.ts +25 -5
  17. package/dist/src/network/struct.d.ts.map +1 -1
  18. package/dist/src/network/struct.js.map +1 -1
  19. package/dist/src/transaction/coordinator.d.ts +23 -14
  20. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  21. package/dist/src/transaction/coordinator.js +73 -45
  22. package/dist/src/transaction/coordinator.js.map +1 -1
  23. package/dist/src/transaction/durability.d.ts +31 -0
  24. package/dist/src/transaction/durability.d.ts.map +1 -0
  25. package/dist/src/transaction/durability.js +36 -0
  26. package/dist/src/transaction/durability.js.map +1 -0
  27. package/dist/src/transaction/errors.d.ts +14 -6
  28. package/dist/src/transaction/errors.d.ts.map +1 -1
  29. package/dist/src/transaction/errors.js +16 -5
  30. package/dist/src/transaction/errors.js.map +1 -1
  31. package/dist/src/transaction/index.d.ts +2 -0
  32. package/dist/src/transaction/index.d.ts.map +1 -1
  33. package/dist/src/transaction/index.js +1 -0
  34. package/dist/src/transaction/index.js.map +1 -1
  35. package/dist/src/transaction/session.d.ts +2 -0
  36. package/dist/src/transaction/session.d.ts.map +1 -1
  37. package/dist/src/transaction/session.js +4 -2
  38. package/dist/src/transaction/session.js.map +1 -1
  39. package/dist/src/transaction/transaction.d.ts +9 -0
  40. package/dist/src/transaction/transaction.d.ts.map +1 -1
  41. package/dist/src/transaction/transaction.js.map +1 -1
  42. package/dist/src/transactor/change-notifier.d.ts +20 -8
  43. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  44. package/dist/src/transactor/change-notifier.js.map +1 -1
  45. package/dist/src/transactor/transactor-source.d.ts +5 -4
  46. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  47. package/dist/src/transactor/transactor-source.js +8 -5
  48. package/dist/src/transactor/transactor-source.js.map +1 -1
  49. package/package.json +1 -1
  50. package/src/cluster/i-cluster.ts +13 -2
  51. package/src/cluster/structs.ts +50 -6
  52. package/src/collection/collection.ts +5 -3
  53. package/src/network/durability.ts +63 -15
  54. package/src/network/i-key-network.ts +10 -0
  55. package/src/network/struct.ts +25 -5
  56. package/src/transaction/coordinator.ts +119 -76
  57. package/src/transaction/durability.ts +60 -0
  58. package/src/transaction/errors.ts +18 -3
  59. package/src/transaction/index.ts +2 -0
  60. package/src/transaction/session.ts +4 -2
  61. package/src/transaction/transaction.ts +9 -0
  62. package/src/transactor/change-notifier.ts +20 -8
  63. package/src/transactor/transactor-source.ts +8 -5
@@ -85,25 +85,37 @@ export function isBlockChangeNotifier(x: unknown): x is IBlockChangeNotifier {
85
85
  * acknowledged below `full` (`WriteDurability.quorum`) is pending until these events cover its
86
86
  * blocks, at which point a host can move it from "pending" to "saved".
87
87
  *
88
+ * **Fired only on the node whose ledger recorded the shortfall** — the one a below-`full` answer
89
+ * names as `WriteDurability.recordedBy`. An answer without `recordedBy` is a write no node is
90
+ * tracking, and no event should be expected for it. That node fires the event when its record of a
91
+ * block's shortfall is removed, which happens two ways, each firing exactly once per record: the
92
+ * node's push of the missing copies empties it (the event carries the record's own `rev` and
93
+ * `actionId`), or a later commit of the block that every member confirmed settles it (the event
94
+ * carries that later commit's `rev` and `actionId`).
95
+ *
88
96
  * **Keyed by block, deliberately, never by action.** The node's record of what is still owed (the
89
97
  * under-replication ledger) keeps ONE entry per block, at the block's highest under-replicated
90
98
  * revision: a block written again by a LATER action replaces the earlier entry, so the earlier
91
99
  * action's shortfall is cleared by the later action's copies and reported under the later
92
100
  * action's `actionId` — the earlier action never fires an event of its own. A host that keys its
93
- * pending state by action alone therefore waits forever for a superseded write. Hold the block ids
94
- * the write's result names (`PendSuccess.blockIds`) and clear each as an event covers it; `rev`
95
- * and `actionId` say which write's copies did the covering.
101
+ * pending state by action alone therefore waits forever for a superseded write. Hold the blocks the
102
+ * write's durability names (`WriteDurability.blockRevs`, each with the revision it committed at) and
103
+ * clear a block when an event names it at that revision or a later one; `rev` and `actionId` say
104
+ * which write's copies did the covering. An event can arrive before the write's answer has reached
105
+ * the host, so a host that registers on the answer must also remember events it has already seen.
96
106
  */
97
107
  export type BlockDurabilityReachedEvent = {
98
- /** Blocks that reached full replication in this round. Today's producer reports one block per
99
- * event; the list shape lets a producer report several blocks of one action together. */
108
+ /** Blocks that reached full replication in this round. Both of today's producers report one block
109
+ * per event; the list shape lets a producer report several blocks of one action together. */
100
110
  readonly blockIds: readonly BlockId[];
101
111
  /** The revision every cohort member now holds — the block's highest under-replicated revision,
102
- * which supersedes every lower one. */
112
+ * or the fully replicated commit that settled it, either of which supersedes every lower one. */
103
113
  readonly rev: number;
104
- /** The action whose recorded shortfall cleared. See the note above on superseded writes. */
114
+ /** The action whose copies covered the block: the one whose recorded shortfall cleared, or the
115
+ * fully replicated commit that settled it. See the note above on superseded writes. */
105
116
  readonly actionId: ActionId;
106
- /** Best-effort; absent when the collection could not be resolved from the block's header. */
117
+ /** Best-effort; absent when the collection could not be resolved from the block's header, and
118
+ * always when a settling commit fired the event (the coordinator does not read the block). */
107
119
  readonly collectionId?: CollectionId;
108
120
  };
109
121
 
@@ -2,6 +2,7 @@ import { randomBytes } from '@noble/hashes/utils.js'
2
2
  import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
3
3
  import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, CommitResult, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms, BlockContentDigests, BlockBaseRevs, GetBlockResult } from "../index.js";
4
4
  import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
5
+ import { withBlockRevs } from "../network/durability.js";
5
6
  import type { ReadDependency } from "../transaction/transaction.js";
6
7
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
7
8
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
@@ -228,10 +229,11 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
228
229
  * committed revision each update-only block's operations were computed against, from the same tracker
229
230
  * (`Tracker.stagedBaseRevs`). Omitted from the pend request when empty, for the same preimage reason.
230
231
  * @returns The transactor's own verdict, unflattened: a {@link CommitSuccess} carrying the
231
- * {@link WriteDurability} of the committed revision, or a {@link StaleFailure} if the pend or the commit
232
- * was refused. Success is deliberately NOT collapsed to `undefined` — the durability is the only thing
233
- * that tells a write every machine holds from one only this machine holds, and a caller that wants the
234
- * old boolean reads `result.success`. Test "is this completely saved" through `isFullyDurable`, never
232
+ * {@link WriteDurability} of the committed revision — naming every block it committed at `rev`
233
+ * (`blockRevs`) — or a {@link StaleFailure} if the pend or the commit was refused. Success is
234
+ * deliberately NOT collapsed to `undefined` — the durability is the only thing that tells a write every
235
+ * machine holds from one only this machine holds, and a caller that wants the old boolean reads
236
+ * `result.success`. Test "is this completely saved" through `isFullyDurable`, never
235
237
  * by comparing `quorum` (see {@link WriteDurability}).
236
238
  */
237
239
  async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0, blockDigests?: BlockContentDigests, baseRevs?: BlockBaseRevs): Promise<CommitResult> {
@@ -259,8 +261,9 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
259
261
  // rebase — letting the cancel's own failure throw over it would turn a routine,
260
262
  // recoverable race into a hard failure. So the cancel fault is logged, not raised.
261
263
  await this.dischargePend(actionId, pendResult.blockIds);
264
+ return commitResult;
262
265
  }
263
- return commitResult;
266
+ return { ...commitResult, durability: withBlockRevs(commitResult.durability, pendResult.blockIds, rev) };
264
267
  } catch (e) {
265
268
  // `e` is the real cause — a transport fault, the thing the caller needs to see. A cancel
266
269
  // that also fails must not silently take its place, but it must not be lost either: the