@optimystic/db-core 1.12.1 → 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
@@ -1,7 +1,8 @@
1
- import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, CommitRequest, ActionId } from "../index.js";
1
+ import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, CommitRequest, ActionId, WriteDurability } 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
4
  import { isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
5
+ import { withBlockRevs } from "../network/durability.js";
5
6
  import { TransactionExpiredError } from "../network/transaction-expired-error.js";
6
7
  import type { Collection, CollectionSnapshot, RefreshReport } from "../collection/collection.js";
7
8
  import type { SyncOptions } from "../collection/index.js";
@@ -12,6 +13,7 @@ import { blockIdsForTransforms, copyTransforms } from "../transform/helpers.js";
12
13
  import { computeBlockContentDigests, blockDigestsField, baseRevsField } from "../transform/digest.js";
13
14
  import { collectOperations, hashOperations } from "./operations-hash.js";
14
15
  import { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
16
+ import { recordCollectionDurability, transactionDurability, type TransactionDurability } from "./durability.js";
15
17
  import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
16
18
  import { createLogger } from "../logger.js";
17
19
 
@@ -71,11 +73,43 @@ type CommitCycle = {
71
73
  * still be finished (the partial-retry branch of {@link commitOnceLatched}). Once non-empty,
72
74
  * the commit can no longer fail cleanly: every later failure is reported through
73
75
  * {@link reportSaved} as a partial landing naming these as committed. A successful attempt
74
- * ends the commit and records nothing here; a partial landing on a hard failure reports its
75
- * own committed set at once. */
76
- saved: Set<CollectionId>;
76
+ * ends the commit and records nothing here (it returns what it committed instead); a partial
77
+ * landing on a hard failure reports its own committed set at once. Each saved participant
78
+ * carries who holds it, `undefined` where the refresh that saved it could not say (see
79
+ * {@link TransactionDurability}). */
80
+ saved: Map<CollectionId, WriteDurability | undefined>;
77
81
  };
78
82
 
83
+ /** How one collection's commit ended ({@link TransactionCoordinator.commitCollection}). */
84
+ type CollectionCommitOutcome =
85
+ | { collectionId: CollectionId; committed: true; durability: WriteDurability }
86
+ | { collectionId: CollectionId; committed: false; error: string; stale?: boolean; expired?: TransactionExpiredError };
87
+
88
+ /** How one attempt's distributed phases ended ({@link TransactionCoordinator.coordinateTransaction}).
89
+ * `committedCollections` carries who holds each collection that durably committed — every
90
+ * participant on success, a subset (possibly empty) on failure. */
91
+ type CoordinationResult =
92
+ | { success: true; committedCollections: ReadonlyMap<CollectionId, WriteDurability> }
93
+ | {
94
+ success: false;
95
+ error?: string;
96
+ committedCollections?: ReadonlyMap<CollectionId, WriteDurability>;
97
+ failedCollections?: ReadonlySet<CollectionId>;
98
+ /** True when the failure was a clean optimistic-concurrency conflict (stale loss / pending
99
+ * contention) with nothing durable — i.e. safe to re-drive after a re-read. */
100
+ staleLoss?: boolean;
101
+ /** Present when a pend or a commit was refused because the transaction had expired by the
102
+ * cohort's clocks: the error the commit surfaces, never a stale loss. */
103
+ expired?: TransactionExpiredError;
104
+ };
105
+
106
+ /** What a successful commit wrote: `written` folded into one report, or `undefined` when it holds
107
+ * nothing (nothing was staged, so there was no pend and no commit — the same hole
108
+ * `Collection.sync` has). */
109
+ function writtenDurability(written: ReadonlyMap<CollectionId, WriteDurability | undefined>): TransactionDurability | undefined {
110
+ return written.size === 0 ? undefined : transactionDurability(written);
111
+ }
112
+
79
113
  /**
80
114
  * What a pend this coordinator sends carries for the receiving cluster members to re-check.
81
115
  *
@@ -321,18 +355,17 @@ export class TransactionCoordinator {
321
355
  *
322
356
  * Defaults are safe out of the box: a caller that passes no options gets bounded, jittered retry.
323
357
  *
324
- * NOTE: this returns nothing, so a multi-collection commit reports NO durability — unlike
325
- * `Collection.sync`, which now answers with the {@link WriteDurability} of what it committed. The
326
- * gap is deliberate and tracked in `tickets/backlog/feat-multi-collection-commit-reports-durability.md`:
327
- * folding a class across collections that may individually have committed or been dropped (see
328
- * {@link CoordinatorPartialCommitError}) is its own design problem, not a pass-through. Until that
329
- * lands, a caller that needs to know whether a write is fully held has to use the single-collection
330
- * path; do not infer one here from a plain successful return.
331
- *
332
358
  * @param transaction - The transaction to commit
333
359
  * @param options - Retry knobs; shares the {@link SyncOptions} vocabulary with `Collection.sync`.
360
+ * @returns who holds what the commit wrote — per collection, across every attempt (a participant
361
+ * the refresh between attempts saved included), with `overall` the weakest of them. Test it
362
+ * through `isFullyDurable(overall)`; an absent `overall` means some collection is saved but who
363
+ * holds it is unknown. `undefined` means NOTHING was written — nothing was staged, or a retry's
364
+ * replay dropped every staged action — exactly as `Collection.sync` reports an empty sync. Every
365
+ * other successful return carries a report; a failure after something was written carries the
366
+ * committed half's on {@link CoordinatorPartialCommitError.durability}.
334
367
  */
335
- async commit(transaction: Transaction, options?: SyncOptions): Promise<void> {
368
+ async commit(transaction: Transaction, options?: SyncOptions): Promise<TransactionDurability | undefined> {
336
369
  // At most one open stamp (see the invariant on stampData). Checked once, BEFORE the retry
337
370
  // loop — this is a hard failure, never retryable: the open stamp must be committed or
338
371
  // rolled back first. This guard is what catches a caller that staged directly (Tree.stage /
@@ -346,10 +379,10 @@ export class TransactionCoordinator {
346
379
  const cycle: CommitCycle = {
347
380
  inFlightDisposers: [],
348
381
  participants: new Set(),
349
- saved: new Set(),
382
+ saved: new Map(),
350
383
  };
351
384
  try {
352
- await this.commitAttempts(transaction, cycle, options);
385
+ return await this.commitAttempts(transaction, cycle, options);
353
386
  } catch (err) {
354
387
  // The ONE place a failure leaves this commit, so no exit — present or future — can skip
355
388
  // reporting a participant that is already saved.
@@ -365,8 +398,10 @@ export class TransactionCoordinator {
365
398
  }
366
399
 
367
400
  /** The retry loop behind {@link commit}: every attempt, and the refresh between them. Records
368
- * what it learns in `cycle`; {@link commit} owns turning a failure into the right report. */
369
- private async commitAttempts(transaction: Transaction, cycle: CommitCycle, options?: SyncOptions): Promise<void> {
401
+ * what it learns in `cycle`; {@link commit} owns turning a failure into the right report. On
402
+ * success, reports every participant the cycle saved together with what the final attempt
403
+ * committed (see {@link commit}'s return). */
404
+ private async commitAttempts(transaction: Transaction, cycle: CommitCycle, options?: SyncOptions): Promise<TransactionDurability | undefined> {
370
405
  const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
371
406
  const baseBackoffMs = options?.baseBackoffMs ?? DefaultBaseBackoffMs;
372
407
  const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
@@ -400,8 +435,14 @@ export class TransactionCoordinator {
400
435
  }
401
436
 
402
437
  try {
403
- await this.commitOnce(transaction, cycle);
404
- return;
438
+ const committed = await this.commitOnce(transaction, cycle);
439
+ // Merged, not overwritten, should one participant be both saved and committed (see the
440
+ // NOTE in reportSaved).
441
+ const written = new Map(cycle.saved);
442
+ for (const [collectionId, durability] of committed) {
443
+ recordCollectionDurability(written, collectionId, durability);
444
+ }
445
+ return writtenDurability(written);
405
446
  } catch (err) {
406
447
  // Only a CLEAN stale loss is retryable. A partial landing, an expired transaction, an
407
448
  // unavailable transactor, etc. all propagate unchanged.
@@ -455,7 +496,7 @@ export class TransactionCoordinator {
455
496
  // can be saved and still hold actions staged after the attempt began, and those
456
497
  // the next attempt must commit.
457
498
  this.stampData.delete(transaction.stamp.id);
458
- return;
499
+ return transactionDurability(cycle.saved);
459
500
  }
460
501
  }
461
502
  }
@@ -463,7 +504,8 @@ export class TransactionCoordinator {
463
504
 
464
505
  /**
465
506
  * Refresh every registered collection between attempts, recording in `cycle.saved` each one
466
- * whose refresh finished this transaction's own log entry (see {@link Collection.refreshInFlight}).
507
+ * whose refresh finished this transaction's own log entry (see {@link Collection.refreshInFlight}),
508
+ * with who holds it — `undefined` when the refresh could not say, which still records it as saved.
467
509
  *
468
510
  * Visits EVERY collection even after one throws. Stopping at the first throw would leave a
469
511
  * participant later in the map unfinished whenever an earlier one is torn — its log tail stored
@@ -502,7 +544,7 @@ export class TransactionCoordinator {
502
544
  // Read after the try, not only on success: a refresh can throw AFTER it finished the
503
545
  // entry, and that participant is saved either way.
504
546
  if (report.ownEntryFinished !== undefined) {
505
- cycle.saved.add(collectionId);
547
+ recordCollectionDurability(cycle.saved, collectionId, report.ownEntryFinished.durability);
506
548
  }
507
549
  }
508
550
  if (terminal !== undefined) {
@@ -540,6 +582,7 @@ export class TransactionCoordinator {
540
582
  *
541
583
  * - `committedCollections`: every refresh-saved participant, plus the committed set of `err`
542
584
  * when it is itself a partial landing (merged, never wrapped twice — its `reason` is kept);
585
+ * `durability` carries who holds each of them, merged the same way;
543
586
  * - `failedCollections`: every other participant of any attempt. Empty when a failure came after
544
587
  * every participant was saved (a refresh that finished its entry and then threw, say);
545
588
  * - `reason`: the original error.
@@ -553,10 +596,12 @@ export class TransactionCoordinator {
553
596
  if (cycle.saved.size === 0) {
554
597
  return err;
555
598
  }
556
- const committed = new Set(cycle.saved);
599
+ const committed = new Map(cycle.saved);
557
600
  let reason = err;
558
601
  if (err instanceof CoordinatorPartialCommitError) {
559
- for (const id of err.committedCollections) committed.add(id);
602
+ for (const [id, durability] of err.durability.collections) {
603
+ recordCollectionDurability(committed, id, durability);
604
+ }
560
605
  reason = err.reason;
561
606
  }
562
607
  // NOTE: a participant is in exactly one list, so one saved by a refresh that ALSO held actions
@@ -565,9 +610,9 @@ export class TransactionCoordinator {
565
610
  // races a commit, report such a participant in both lists.
566
611
  const failed = [...cycle.participants].filter(id => !committed.has(id));
567
612
  log('commit:partial-after-refresh tx=%s committed=%o failed=%o reason=%s', transaction.id,
568
- [...committed], failed, reason instanceof Error ? reason.name : String(reason));
613
+ [...committed.keys()], failed, reason instanceof Error ? reason.name : String(reason));
569
614
  this.stampData.delete(transaction.stamp.id);
570
- return new CoordinatorPartialCommitError([...committed], failed, reason);
615
+ return new CoordinatorPartialCommitError(committed, failed, reason);
571
616
  }
572
617
 
573
618
  /**
@@ -594,8 +639,10 @@ export class TransactionCoordinator {
594
639
  * `cycle.inFlightDisposers`. REQUIRED, so a future caller cannot silently reintroduce the
595
640
  * unmarked refresh the disposers exist to prevent, nor lose track of who took part. The caller
596
641
  * owns clearing the marks, because they have to survive past this attempt.
642
+ * @returns every collection this attempt committed, with who holds it — empty when nothing was
643
+ * staged, so the attempt wrote nothing.
597
644
  */
598
- private async commitOnce(transaction: Transaction, cycle: CommitCycle): Promise<void> {
645
+ private async commitOnce(transaction: Transaction, cycle: CommitCycle): Promise<ReadonlyMap<CollectionId, WriteDurability>> {
599
646
  if (isTransactionExpired(transaction.stamp)) {
600
647
  throw new Error(`Transaction expired at ${transaction.stamp.expiration}`);
601
648
  }
@@ -608,7 +655,7 @@ export class TransactionCoordinator {
608
655
  // or a read-only transaction that opened one (the empty pre-stage barrier) wedges every
609
656
  // later stamp on this coordinator.
610
657
  this.stampData.delete(transaction.stamp.id);
611
- return;
658
+ return new Map();
612
659
  }
613
660
  for (const { collectionId } of collectionData) {
614
661
  cycle.participants.add(collectionId);
@@ -651,7 +698,7 @@ export class TransactionCoordinator {
651
698
  // non-participant is left unmarked and its refresh behaves exactly as a reader's.
652
699
  cycle.inFlightDisposers.push(collection.beginInFlightAction(transaction.id));
653
700
  }
654
- await this.commitOnceLatched(transaction, collectionData, cycle);
701
+ return await this.commitOnceLatched(transaction, collectionData, cycle);
655
702
  } finally {
656
703
  for (const release of latchReleases.reverse()) {
657
704
  release();
@@ -667,14 +714,16 @@ export class TransactionCoordinator {
667
714
  * is latch-free by contract.
668
715
  *
669
716
  * `cycle` is written only on a partial landing that is retried forward: the participants this
670
- * attempt committed go into `cycle.saved`, so the retry loop reports every later failure as the
671
- * partial landing it is (see {@link reportSaved}).
717
+ * attempt committed go into `cycle.saved`, with who holds each, so the retry loop reports every
718
+ * later failure as the partial landing it is (see {@link reportSaved}).
719
+ *
720
+ * @returns on success, every participant with who holds it (see {@link commitOnce}).
672
721
  */
673
722
  private async commitOnceLatched(
674
723
  transaction: Transaction,
675
724
  collectionData: { collectionId: CollectionId; collection: Collection<any> }[],
676
725
  cycle: CommitCycle
677
- ): Promise<void> {
726
+ ): Promise<ReadonlyMap<CollectionId, WriteDurability>> {
678
727
  // Append each collection's staged actions to its log, then collect the
679
728
  // resulting transforms + critical (log-tail) block for consensus.
680
729
  //
@@ -717,14 +766,7 @@ export class TransactionCoordinator {
717
766
  preCommitSnapshots.set(collectionId, collection.snapshotPending());
718
767
  }
719
768
 
720
- let coordResult: {
721
- success: boolean;
722
- error?: string;
723
- committedCollections?: Set<CollectionId>;
724
- failedCollections?: Set<CollectionId>;
725
- staleLoss?: boolean;
726
- expired?: TransactionExpiredError;
727
- };
769
+ let coordResult: CoordinationResult;
728
770
  try {
729
771
  for (const { collectionId, collection } of collectionData) {
730
772
  const applyResult = await this.applyActionsToCollection(
@@ -764,7 +806,7 @@ export class TransactionCoordinator {
764
806
  }
765
807
 
766
808
  if (!coordResult.success) {
767
- const committed = coordResult.committedCollections ?? new Set<CollectionId>();
809
+ const committed = coordResult.committedCollections ?? new Map<CollectionId, WriteDurability>();
768
810
  // Keep exactly what each participant that did NOT commit sent, BEFORE the restores below
769
811
  // swap its tracker out. A refused commit is not proof nothing landed: a participant's log
770
812
  // tail is committed first and can be stored while the answer is still a failure, and
@@ -831,8 +873,10 @@ export class TransactionCoordinator {
831
873
  // ABOVE the held revision. Collection.consumeOwnEntry is therefore unreachable for
832
874
  // a sibling committed here, and no attempt was retained for it (the loop above
833
875
  // skips committed participants) — the refresh is a reader's, at a cost of one walk.
834
- for (const collectionId of committed) cycle.saved.add(collectionId);
835
- log('commit:partial-retry tx=%s committed=%o failed=%o reason=%s', transaction.id, [...committed], failed, coordResult.error);
876
+ for (const [collectionId, durability] of committed) {
877
+ recordCollectionDurability(cycle.saved, collectionId, durability);
878
+ }
879
+ log('commit:partial-retry tx=%s committed=%o failed=%o reason=%s', transaction.id, [...committed.keys()], failed, coordResult.error);
836
880
  throw new CoordinatorStaleLossError(failed, coordResult.error);
837
881
  }
838
882
  // Half-landed on a HARD failure (the transport budget spent on a thrown fault, a
@@ -840,7 +884,7 @@ export class TransactionCoordinator {
840
884
  // stamp tracking (the success path does the same at the end) and surface the
841
885
  // structured signal for reconciliation at once.
842
886
  this.stampData.delete(transaction.stamp.id);
843
- throw new CoordinatorPartialCommitError([...committed], failed, coordResult.expired ?? coordResult.error);
887
+ throw new CoordinatorPartialCommitError(committed, failed, coordResult.expired ?? coordResult.error);
844
888
  }
845
889
 
846
890
  // EMPTY committed set: PEND failed, or the whole commit failed cleanly with
@@ -884,6 +928,7 @@ export class TransactionCoordinator {
884
928
  // precisely because the coordinator enforces at most ONE open stamp (the invariant on
885
929
  // stampData): no sibling stamp's snapshot exists to go stale against this commit.
886
930
  this.stampData.delete(transaction.stamp.id);
931
+ return coordResult.committedCollections;
887
932
  }
888
933
 
889
934
  /**
@@ -1224,7 +1269,7 @@ export class TransactionCoordinator {
1224
1269
  // (docs/transactions.md). If a host ever commits multi-collection transactions
1225
1270
  // through execute(), route its coordination through commit()'s retry rather than
1226
1271
  // duplicating that recovery here.
1227
- const committed = coordResult.committedCollections ?? new Set<CollectionId>();
1272
+ const committed = coordResult.committedCollections ?? new Map<CollectionId, WriteDurability>();
1228
1273
  if (committed.size > 0) {
1229
1274
  for (const collectionId of batches.keys()) {
1230
1275
  const collection = this.collections.get(collectionId);
@@ -1256,7 +1301,9 @@ export class TransactionCoordinator {
1256
1301
  return {
1257
1302
  success: false,
1258
1303
  error: coordResult.error,
1259
- committedCollections: committed.size > 0 ? [...committed] : undefined,
1304
+ ...(committed.size > 0
1305
+ ? { committedCollections: [...committed.keys()], durability: transactionDurability(committed) }
1306
+ : {}),
1260
1307
  failedCollections: coordResult.failedCollections ? [...coordResult.failedCollections] : undefined,
1261
1308
  };
1262
1309
  }
@@ -1282,6 +1329,7 @@ export class TransactionCoordinator {
1282
1329
 
1283
1330
  // Clean up stamp tracking data
1284
1331
  this.stampData.delete(transaction.stamp.id);
1332
+ const durability = writtenDurability(coordResult.committedCollections);
1285
1333
 
1286
1334
  // 6. Return results from actions.
1287
1335
  // `actions` is the engine's ORIGINAL batch list, un-coalesced — the field is documented
@@ -1293,7 +1341,8 @@ export class TransactionCoordinator {
1293
1341
  return {
1294
1342
  success: true,
1295
1343
  actions: result.actions,
1296
- results: actionResults
1344
+ results: actionResults,
1345
+ ...(durability === undefined ? {} : { durability })
1297
1346
  };
1298
1347
  } finally {
1299
1348
  for (const release of latchReleases.reverse()) {
@@ -1418,18 +1467,7 @@ export class TransactionCoordinator {
1418
1467
  collectionTransforms: Map<CollectionId, Transforms>,
1419
1468
  criticalBlocks: Map<CollectionId, BlockId>,
1420
1469
  pendedRevs: ReadonlyMap<CollectionId, number>
1421
- ): Promise<{
1422
- success: boolean;
1423
- error?: string;
1424
- committedCollections?: Set<CollectionId>;
1425
- failedCollections?: Set<CollectionId>;
1426
- /** True when the failure was a clean optimistic-concurrency conflict (stale loss / pending
1427
- * contention) with nothing durable — i.e. safe to re-drive after a re-read. */
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;
1432
- }> {
1470
+ ): Promise<CoordinationResult> {
1433
1471
  const trxId = transaction.id;
1434
1472
  const t0 = Date.now();
1435
1473
 
@@ -1459,7 +1497,7 @@ export class TransactionCoordinator {
1459
1497
  const commitResult = await this.commitPhase(
1460
1498
  transaction.id as ActionId,
1461
1499
  criticalBlockIds,
1462
- pendResult.pendedBlockIds!,
1500
+ pendResult.pendedBlockIds,
1463
1501
  pendedRevs
1464
1502
  );
1465
1503
  const commitMs = Date.now() - tCommit;
@@ -1467,7 +1505,7 @@ export class TransactionCoordinator {
1467
1505
  // Targeted cancel: only cancel collections that are still pending (not already committed)
1468
1506
  await this.cancelPhase(
1469
1507
  transaction.id as ActionId,
1470
- pendResult.pendedBlockIds!,
1508
+ pendResult.pendedBlockIds,
1471
1509
  commitResult.committedCollections
1472
1510
  );
1473
1511
  log('trx:phases trxId=%s gather=%dms pend=%dms commit=%dms (failed) total=%dms', trxId, gatherMs, pendMs, commitMs, Date.now() - t0);
@@ -1488,7 +1526,7 @@ export class TransactionCoordinator {
1488
1526
  // (as per user's note: "managed by each cluster, the client doesn't have to worry about them")
1489
1527
 
1490
1528
  log('trx:phases trxId=%s gather=%dms pend=%dms commit=%dms total=%dms', trxId, gatherMs, pendMs, commitMs, Date.now() - t0);
1491
- return { success: true };
1529
+ return { success: true, committedCollections: commitResult.committedCollections };
1492
1530
  }
1493
1531
 
1494
1532
  /**
@@ -1553,7 +1591,10 @@ export class TransactionCoordinator {
1553
1591
  collectionTransforms: ReadonlyMap<CollectionId, Transforms>,
1554
1592
  pendedRevs: ReadonlyMap<CollectionId, number>,
1555
1593
  superclusterNominees: ReadonlySet<PeerId> | null
1556
- ): Promise<{ success: boolean; error?: string; pendedBlockIds?: Map<CollectionId, BlockId[]>; staleLoss?: boolean; expired?: TransactionExpiredError }> {
1594
+ ): Promise<
1595
+ | { success: true; pendedBlockIds: Map<CollectionId, BlockId[]> }
1596
+ | { success: false; error: string; staleLoss?: boolean; expired?: TransactionExpiredError }
1597
+ > {
1557
1598
  if (collectionTransforms.size === 0) {
1558
1599
  return { success: false, error: 'No transforms to pend' };
1559
1600
  }
@@ -1688,7 +1729,8 @@ export class TransactionCoordinator {
1688
1729
  ): Promise<{
1689
1730
  success: boolean;
1690
1731
  error?: string;
1691
- committedCollections: Set<CollectionId>;
1732
+ /** Who holds each collection that committed. */
1733
+ committedCollections: Map<CollectionId, WriteDurability>;
1692
1734
  failedCollections: Set<CollectionId>;
1693
1735
  staleLoss?: boolean;
1694
1736
  expired?: TransactionExpiredError;
@@ -1701,7 +1743,7 @@ export class TransactionCoordinator {
1701
1743
  )
1702
1744
  );
1703
1745
 
1704
- const committedCollections = new Set<CollectionId>();
1746
+ const committedCollections = new Map<CollectionId, WriteDurability>();
1705
1747
  const failedCollections = new Set<CollectionId>();
1706
1748
  const errors: string[] = [];
1707
1749
  // Classify failures: a returned stale loss (someone committed a newer rev) is retryable after
@@ -1713,14 +1755,14 @@ export class TransactionCoordinator {
1713
1755
  let expired: TransactionExpiredError | undefined;
1714
1756
  for (const outcome of outcomes) {
1715
1757
  if (outcome.status === 'fulfilled') {
1716
- const { collectionId, committed, error, stale } = outcome.value;
1717
- if (committed) {
1718
- committedCollections.add(collectionId);
1758
+ const result = outcome.value;
1759
+ if (result.committed) {
1760
+ committedCollections.set(result.collectionId, result.durability);
1719
1761
  } else {
1720
- failedCollections.add(collectionId);
1721
- if (error) errors.push(error);
1722
- if (stale) anyStale = true; else anyHard = true;
1723
- expired ??= outcome.value.expired;
1762
+ failedCollections.add(result.collectionId);
1763
+ errors.push(result.error);
1764
+ if (result.stale) anyStale = true; else anyHard = true;
1765
+ expired ??= result.expired;
1724
1766
  }
1725
1767
  } else {
1726
1768
  // commitCollection resolves rather than rejects, but treat any unexpected
@@ -1747,7 +1789,8 @@ export class TransactionCoordinator {
1747
1789
  /**
1748
1790
  * Commit a single collection's pended blocks, retrying transient failures up to three
1749
1791
  * times (forward recovery). Always resolves — success is carried in the returned
1750
- * `committed` flag — so the fan-out in {@link commitPhase} can aggregate every result.
1792
+ * `committed` flag, with the commit's `durability` beside it — so the fan-out in
1793
+ * {@link commitPhase} can aggregate every result.
1751
1794
  */
1752
1795
  private async commitCollection(
1753
1796
  actionId: ActionId,
@@ -1758,7 +1801,7 @@ export class TransactionCoordinator {
1758
1801
  * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
1759
1802
  * trips, could stamp the CommitRequest with a different number than the pend named. */
1760
1803
  rev: number
1761
- ): Promise<{ collectionId: CollectionId; committed: boolean; error?: string; stale?: boolean; expired?: TransactionExpiredError }> {
1804
+ ): Promise<CollectionCommitOutcome> {
1762
1805
  const collection = this.collections.get(collectionId);
1763
1806
  if (!collection) {
1764
1807
  return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
@@ -1800,7 +1843,7 @@ export class TransactionCoordinator {
1800
1843
  try {
1801
1844
  const commitResult = await this.transactor.commit(commitRequest);
1802
1845
  if (commitResult.success) {
1803
- return { collectionId, committed: true };
1846
+ return { collectionId, committed: true, durability: withBlockRevs(commitResult.durability, blockIds, rev) };
1804
1847
  }
1805
1848
  if (isExpiryFailure(commitResult)) {
1806
1849
  // Not a stale loss: a re-drive's expiration comes from the same clock.
@@ -1846,7 +1889,7 @@ export class TransactionCoordinator {
1846
1889
  private async cancelPhase(
1847
1890
  actionId: ActionId,
1848
1891
  pendedBlockIds: Map<CollectionId, BlockId[]>,
1849
- excludeCollections?: Set<CollectionId>
1892
+ excludeCollections?: ReadonlyMap<CollectionId, unknown>
1850
1893
  ): Promise<void> {
1851
1894
  // Fan out the per-collection cancels concurrently. Each is best-effort: a cancel
1852
1895
  // fault is logged and swallowed so it cannot mask the pend/commit failure that
@@ -0,0 +1,60 @@
1
+ import type { CollectionId } from "../collection/index.js";
2
+ import type { WriteDurability } from "../network/struct.js";
3
+ import { mergeDurability } from "../network/durability.js";
4
+
5
+ /** What a multi-collection commit wrote, and who holds it. */
6
+ export type TransactionDurability = {
7
+ /** Every collection this commit durably wrote, across all of its attempts, with who holds it.
8
+ * A key present with an `undefined` value means the collection IS saved, but the layer that
9
+ * recognised it as saved could not say who holds it (a participant the refresh between
10
+ * attempts finished without re-sending anything — see `RefreshReport.ownEntryFinished`). Test
11
+ * with `has`, never with `get(...) !== undefined`, for "was it written". Never empty. */
12
+ readonly collections: ReadonlyMap<CollectionId, WriteDurability | undefined>;
13
+ /** `mergeDurability` over every value in `collections` — the weakest class, so a caller that
14
+ * reads only this is reading the binding constraint. ABSENT when any collection's class is
15
+ * unknown: the overall answer is never fabricated, and a caller testing
16
+ * `overall !== undefined && isFullyDurable(overall)` then shows the transaction as pending. */
17
+ readonly overall?: WriteDurability;
18
+ };
19
+
20
+ /**
21
+ * Builds a {@link TransactionDurability} from what each collection reported. The map is copied, so
22
+ * later writes to the caller's map do not reach the result.
23
+ *
24
+ * THROWS on an empty map, for the reason `mergeDurability` does: a commit that wrote something wrote
25
+ * at least one collection, and one that wrote nothing has no report at all (`undefined`).
26
+ */
27
+ export function transactionDurability(
28
+ collections: ReadonlyMap<CollectionId, WriteDurability | undefined>
29
+ ): TransactionDurability {
30
+ if (collections.size === 0) {
31
+ throw new Error('transactionDurability: no collections — a commit that wrote nothing reports undefined, not an empty durability');
32
+ }
33
+ const copy = new Map(collections);
34
+ const known: WriteDurability[] = [];
35
+ for (const d of copy.values()) {
36
+ if (d === undefined) {
37
+ return { collections: copy };
38
+ }
39
+ known.push(d);
40
+ }
41
+ return { collections: copy, overall: mergeDurability(known) };
42
+ }
43
+
44
+ /**
45
+ * Merges one more report for a collection into a per-collection map: an absent key is set; when
46
+ * either side is `undefined` the result is `undefined` (an unknown class is never upgraded to a
47
+ * known one by a second report); otherwise the weaker of the two wins (`mergeDurability`).
48
+ */
49
+ export function recordCollectionDurability(
50
+ into: Map<CollectionId, WriteDurability | undefined>,
51
+ id: CollectionId,
52
+ d: WriteDurability | undefined
53
+ ): void {
54
+ if (!into.has(id)) {
55
+ into.set(id, d);
56
+ return;
57
+ }
58
+ const prev = into.get(id);
59
+ into.set(id, prev === undefined || d === undefined ? undefined : mergeDurability([prev, d]));
60
+ }
@@ -1,4 +1,6 @@
1
1
  import type { CollectionId } from "../collection/index.js";
2
+ import type { WriteDurability } from "../network/struct.js";
3
+ import { transactionDurability, type TransactionDurability } from "./durability.js";
2
4
 
3
5
  /**
4
6
  * Thrown by {@link TransactionCoordinator.commit} when a multi-collection commit
@@ -49,12 +51,22 @@ import type { CollectionId } from "../collection/index.js";
49
51
  * treat it as a clean abort: `committedCollections` are durable and cannot be rolled back,
50
52
  * so a whole-transaction retry would double-apply them. Reconcile the named committed set
51
53
  * against `failedCollections` (re-drive only the failed collections, or repair the split).
54
+ * `durability` says who holds the committed half, in the same shape a successful commit reports.
52
55
  */
53
56
  export class CoordinatorPartialCommitError extends Error {
57
+ /** Collections durably committed before the failure (NOT rolled back) — by an attempt, or
58
+ * by the refresh between attempts finishing the collection's own log entry. Exactly the keys of
59
+ * {@link durability}'s `collections`. */
60
+ readonly committedCollections: readonly CollectionId[];
61
+ /** Who holds the half that DID commit: exactly {@link committedCollections}, each with its class,
62
+ * and `overall` over them (absent when any one's class is unknown). Says nothing about
63
+ * {@link failedCollections}, which wrote nothing. */
64
+ readonly durability: TransactionDurability;
65
+
54
66
  constructor(
55
- /** Collections durably committed before the failure (NOT rolled back) — by an attempt, or
56
- * by the refresh between attempts finishing the collection's own log entry. */
57
- public readonly committedCollections: readonly CollectionId[],
67
+ /** The committed collections with who holds each (`undefined` where that is unknown). Never
68
+ * empty: a commit in which nothing was committed is not a partial commit. */
69
+ committed: ReadonlyMap<CollectionId, WriteDurability | undefined>,
58
70
  /** Collections of this transaction that never committed (local state reverted for retry —
59
71
  * their staged actions are still in place). Can be empty when the failure came after every
60
72
  * collection was already saved. */
@@ -65,6 +77,7 @@ export class CoordinatorPartialCommitError extends Error {
65
77
  * refusal never cleared within the retry budget (its own `reason` names the last refusal). */
66
78
  public readonly reason?: unknown,
67
79
  ) {
80
+ const committedCollections = [...committed.keys()];
68
81
  super(
69
82
  `Multi-collection commit was not atomic: ${committedCollections.length} collection(s) ` +
70
83
  `durably committed via distributed consensus before the commit failed and CANNOT be ` +
@@ -73,6 +86,8 @@ export class CoordinatorPartialCommitError extends Error {
73
86
  `Failed (never committed; local state reverted for retry): [${failedCollections.join(', ')}]. ` +
74
87
  `Underlying failure: ${reason instanceof Error ? reason.message : String(reason)}`
75
88
  );
89
+ this.committedCollections = committedCollections;
90
+ this.durability = transactionDurability(committed);
76
91
  this.name = 'CoordinatorPartialCommitError';
77
92
  }
78
93
  }
@@ -37,6 +37,8 @@ export { ReadDependencyCollector } from './read-dependency-collector.js';
37
37
  export { TransactionCoordinator } from './coordinator.js';
38
38
  export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
39
39
  export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
40
+ export { transactionDurability, recordCollectionDurability } from './durability.js';
41
+ export type { TransactionDurability } from './durability.js';
40
42
  export { TransactionSession } from './session.js';
41
43
  export { TransactionValidator } from './validator.js';
42
44
  export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';
@@ -123,6 +123,8 @@ export class TransactionSession {
123
123
  *
124
124
  * @param options - Optional retry knobs forwarded to {@link TransactionCoordinator.commit}
125
125
  * (bounded backoff+jitter retry of a clean stale loss). Defaults are safe out of the box.
126
+ * @returns on success, `durability` says who holds what the commit wrote; it is absent when the
127
+ * transaction wrote nothing (see {@link ExecutionResult.durability}).
126
128
  */
127
129
  async commit(options?: SyncOptions): Promise<ExecutionResult> {
128
130
  if (this.committed) {
@@ -165,13 +167,13 @@ export class TransactionSession {
165
167
 
166
168
  // Commit through coordinator (which will orchestrate PEND/COMMIT, with bounded
167
169
  // backoff+jitter retry of a clean stale loss)
168
- await this.coordinator.commit(transaction, options);
170
+ const durability = await this.coordinator.commit(transaction, options);
169
171
 
170
172
  // Clear read dependencies after successful commit
171
173
  this.coordinator.clearReadDependencies();
172
174
 
173
175
  this.committed = true;
174
- return { success: true };
176
+ return { success: true, ...(durability === undefined ? {} : { durability }) };
175
177
  }
176
178
 
177
179
  /**
@@ -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 { BlockId } from "../blocks/index.js";
4
4
  import type { CollectionId } from "../collection/index.js";
5
+ import type { TransactionDurability } from "./durability.js";
5
6
  import { hashString } from "../utility/hash-string.js";
6
7
 
7
8
  /**
@@ -386,6 +387,14 @@ export type ExecutionResult = {
386
387
  committedCollections?: CollectionId[];
387
388
  /** On a partial multi-collection commit failure, the collections that failed to commit. */
388
389
  failedCollections?: CollectionId[];
390
+ /**
391
+ * Who holds what this commit wrote, present whenever something was written: on success, every
392
+ * collection the commit wrote; on a partial failure, exactly {@link committedCollections}. Absent
393
+ * when nothing was written — a failure where nothing landed, or a success with nothing staged.
394
+ * Test it through `isFullyDurable(durability.overall)`; an absent `overall` means a collection is
395
+ * saved but who holds it is unknown, so show the change as pending.
396
+ */
397
+ durability?: TransactionDurability;
389
398
  };
390
399
 
391
400
  /**