@optimystic/db-core 1.0.0-beta.3 → 1.1.0

package/dist/src/transaction/coordinator.d.ts

@@ -2,6 +2,25 @@ import type { ITransactor, CollectionId, Transforms } from "../index.js";
 import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
 import type { Collection } from "../collection/collection.js";
 import type { SyncOptions } from "../collection/index.js";
+/**
+ * What a pend this coordinator sends carries for the receiving cluster members to re-check.
+ *
+ * - `'transaction'` (default): the transaction and the hash of every operation it produced — the
+ *   session-mode shape. A member with a transaction validator re-executes the statements and
+ *   compares hashes; the aged retry priority rides inside the transaction.
+ * - `'none'`: bare transforms, exactly the shape a single-collection `Collection.sync` pend has.
+ *   For a commit that has no statements to re-execute — the Quereus adapter's legacy multi-tree
+ *   commit, whose rows were staged directly into the trees — a validating member would otherwise
+ *   refuse the pend as a validator fault. The aged priority then rides on the pend itself
+ *   (`PendRequest.priority`), which is the other carrier a member's race resolution reads, so a
+ *   repeatedly-losing commit still ages. Members configured `unvalidatablePendPolicy: 'reject'`
+ *   refuse these pends, as they refuse every unvalidatable pend.
+ */
+export type PendValidationMode = 'transaction' | 'none';
+export interface CoordinatorOptions {
+    /** See {@link PendValidationMode}. Default `'transaction'`. */
+    pendValidation?: PendValidationMode;
+}
 /**
  * Coordinates multi-collection transactions.
  *
@@ -50,7 +69,19 @@ export declare class TransactionCoordinator {
      * appears in `this.collections` (see {@link captureUncaptured}), so a collection registered
      * mid-transaction is still captured before anything stages into it. */
     private stampData;
-    constructor(transactor: ITransactor, collections: Map<CollectionId, Collection<any>>);
+    /** See {@link PendValidationMode}; fixed for the coordinator's lifetime, so every pend it
+     * sends has one shape. */
+    private readonly pendValidation;
+    constructor(transactor: ITransactor, collections: Map<CollectionId, Collection<any>>, options?: CoordinatorOptions);
+    /**
+     * The validation pair every pend of this attempt carries, or `undefined` when this coordinator
+     * sends unvalidated pends (see {@link PendValidationMode}). Built once per attempt, AFTER the
+     * log append: the hash covers ALL operations across ALL collections, which a validator
+     * recomputes from its own re-execution and compares. The shared operations-hash module
+     * canonicalises (sort + canonical JSON), so the fingerprint is order-independent. Skipped
+     * entirely — not computed and discarded — when no pend will carry it.
+     */
+    private pendValidationFor;
     /**
      * Apply actions to collections (called by engines during statement execution).
      *
@@ -110,30 +141,110 @@ export declare class TransactionCoordinator {
     /**
      * Commit a transaction with a bounded, jittered backoff retry around a CLEAN stale loss.
      *
-     * The single-attempt work lives in {@link commitOnce}; this wrapper re-drives it when the attempt
-     * fails as a clean optimistic-concurrency loss ({@link CoordinatorStaleLossError} — nothing
-     * durably committed, every tracker restored to its pre-append state). Before each re-attempt it
-     * re-reads each collection to fresh revisions (so the retry pends against current state rather
-     * than immediately re-failing stale), then backs off with the same jitter policy as
+     * The single-attempt work lives in {@link commitOnce}; {@link commitAttempts} re-drives it when
+     * the attempt fails as a clean optimistic-concurrency loss ({@link CoordinatorStaleLossError} —
+     * nothing durably committed, every tracker restored to its pre-append state). Before each
+     * re-attempt it re-reads each collection to fresh revisions (so the retry pends against current
+     * state rather than immediately re-failing stale), then backs off with the same jitter policy as
      * {@link Collection.sync}. Retry is bounded by `maxAttempts` and an optional wall-clock
      * `deadlineMs`, and honours an abort `signal`.
      *
-     * A {@link CoordinatorPartialCommitError} (a partial landing — some collection durably committed)
-     * is NOT retryable and escapes immediately: blindly retrying would re-log already-durable actions.
-     * Any other failure (expired transaction, unavailable transactor, unreachable cluster) also
-     * propagates without retry — only genuine clean stale losses are re-driven.
+     * A PARTIAL landing — some collection durably committed while a sibling's commit was refused —
+     * is re-driven too when every refusal was a returned one (a member behind on the block's base,
+     * a rival that took the revision slot): the committed collections are recorded as saved and the
+     * next attempt commits only what is still staged, so the durable half is never re-logged and the
+     * refused collection gets the same refresh-and-finish recovery a clean loss gets. A caller must
+     * still never re-drive a partial landing itself. A partial landing on a HARD failure (the
+     * transport budget spent, a structural rejection) escapes at once as
+     * {@link CoordinatorPartialCommitError}, and any other failure (expired transaction,
+     * unavailable transactor, unreachable cluster) also propagates without retry.
+     *
+     * A participant can also be SAVED between attempts: an attempt that reported a loss may still
+     * have stored that participant's log tail, and the refresh before the next attempt then finishes
+     * and consumes the participant's own entry (see {@link refreshBetweenAttempts}). From that moment
+     * the commit can no longer fail cleanly, so EVERY failure that escapes afterwards — a torn sibling,
+     * a sibling that keeps losing until the budget runs out, an abort, an expiry, a hard error — is
+     * rethrown as {@link CoordinatorPartialCommitError}, counting the refresh-saved participants as
+     * committed and carrying the original error as its `reason` (see {@link reportSaved}). A commit in
+     * which nothing was saved fails with exactly the error it failed with.
      *
      * Defaults are safe out of the box: a caller that passes no options gets bounded, jittered retry.
      *
+     * NOTE: this returns nothing, so a multi-collection commit reports NO durability — unlike
+     * `Collection.sync`, which now answers with the {@link WriteDurability} of what it committed. The
+     * gap is deliberate and tracked in `tickets/backlog/feat-multi-collection-commit-reports-durability.md`:
+     * folding a class across collections that may individually have committed or been dropped (see
+     * {@link CoordinatorPartialCommitError}) is its own design problem, not a pass-through. Until that
+     * lands, a caller that needs to know whether a write is fully held has to use the single-collection
+     * path; do not infer one here from a plain successful return.
+     *
      * @param transaction - The transaction to commit
      * @param options - Retry knobs; shares the {@link SyncOptions} vocabulary with `Collection.sync`.
      */
     commit(transaction: Transaction, options?: SyncOptions): Promise<void>;
+    /** The retry loop behind {@link commit}: every attempt, and the refresh between them. Records
+     * what it learns in `cycle`; {@link commit} owns turning a failure into the right report. */
+    private commitAttempts;
+    /**
+     * Refresh every registered collection between attempts, recording in `cycle.saved` each one
+     * whose refresh finished this transaction's own log entry (see {@link Collection.refreshInFlight}).
+     *
+     * Visits EVERY collection even after one throws. Stopping at the first throw would leave a
+     * participant later in the map unfinished whenever an earlier one is torn — its log tail stored
+     * and its other blocks never landed, the silent loss `Collection.completeOwnEntry` exists to
+     * prevent — and unreported. Each refresh is independent (its own latch, its own instance state),
+     * so one failing says nothing about the next.
+     *
+     * NOTE: refreshes EVERY registered collection, not only the participants of this transaction.
+     * Not free: a non-participant's refresh throws CollectionHeaderVanishedError if its header
+     * momentarily reads absent while it holds a committed revision, aborting this retry. And because
+     * a throw no longer stops the round, an unreachable cluster costs one failed read per registered
+     * collection rather than one. The registered set is small today; if that (or retry latency) ever
+     * bites, narrow this to the transaction's participants.
+     *
+     * @param lastChance - this is the round that spends the last of the retry budget, so a
+     * participant whose half-landed write is refused again settles it (`Collection.completeOwnEntry`)
+     * rather than asking for a round it will not get; the error returned then carries `final`.
+     * @returns the first `completion-refused` {@link TornActionError} when that is the only way any
+     * refresh failed — the round is worth retrying; `undefined` when every refresh succeeded.
+     * @throws the first other error, once every collection has been visited.
+     */
+    private refreshBetweenAttempts;
+    /** Every registered collection with something to push — the participants an attempt starting
+     * now would commit. The predicate is {@link Collection.hasUnsyncedChanges}, the one
+     * `Collection.sync` loops on: staged actions OR uncommitted tracker transforms. Not the
+     * transforms alone: an action can be staged and have changed no block — a delete of an index
+     * entry this instance's stale view never held (the shape `blind-index-delete-is-logged-but-
+     * never-applied` fixed for the single-collection path) — and such a collection MUST still take
+     * part. Its stale pend is refused, and the refresh between attempts replays the action against
+     * the adopted revision, where it finds the entry and produces the delete the retry commits.
+     * Filtering on transforms dropped it from the batch entirely, so the row went and its index
+     * entry stayed behind, on every node. */
+    private stagedCollections;
+    /**
+     * What a failure escaping {@link commit} must be reported as. When nothing is saved, the error
+     * itself, untouched. When a refresh between attempts already saved a participant, the commit
+     * half-landed whatever the error says — a {@link CoordinatorStaleLossError}'s "nothing durably
+     * committed, safe to re-drive" would be false, and a re-drive would apply the saved half twice —
+     * so it becomes a {@link CoordinatorPartialCommitError}:
+     *
+     * - `committedCollections`: every refresh-saved participant, plus the committed set of `err`
+     *   when it is itself a partial landing (merged, never wrapped twice — its `reason` is kept);
+     * - `failedCollections`: every other participant of any attempt. Empty when a failure came after
+     *   every participant was saved (a refresh that finished its entry and then threw, say);
+     * - `reason`: the original error.
+     *
+     * Local state already matches that report: a saved participant was consumed by its refresh, and
+     * an unsaved one kept its staged actions (a failed finish throws before touching anything, and
+     * commitOnceLatched restores every participant it did not commit). The stamp is released, as on
+     * the existing partial path, because the transaction can no longer be cleanly rolled back.
+     */
+    private reportSaved;
     /**
      * Commit a transaction (single attempt): materialise a log entry from each collection's staged
      * pending actions, then orchestrate the distributed consensus (GATHER/PEND/COMMIT).
      *
-     * Called by {@link commit} (which wraps it in the backoff+jitter retry loop). The
+     * Called by {@link commitAttempts} (the backoff+jitter retry loop behind {@link commit}). The
      * staged mutations already live in each collection's tracker — applied either via
      * applyActions() (engine-driven path) or directly via Collection.act()/Tree.stage
      * (the vtab's deferred-DML path) — but in BOTH cases without a log entry yet, so
@@ -141,16 +252,18 @@ export declare class TransactionCoordinator {
      * and folds the committed transforms back into each collection's read cache.
      *
      * On a clean stale loss (nothing durable, every tracker restored) it throws
-     * {@link CoordinatorStaleLossError} so the caller can retry; on a partial landing it throws
+     * {@link CoordinatorStaleLossError} so the caller can retry. On a partial landing it throws the
+     * same, after recording the committed collections in `cycle.saved`, when every refusal was a
+     * returned one (the retry finishes the refused collection); on a hard failure it throws
      * {@link CoordinatorPartialCommitError} (not retryable).
      *
      * @param transaction - The transaction to commit
-     * @param inFlightDisposers - Collects one disposer per participant marked in flight under this
-     * transaction's id (see {@link Collection.beginInFlightAction}). REQUIRED, so a future caller
-     * cannot silently reintroduce the unmarked refresh this parameter exists to prevent: a caller
-     * that never refreshes between attempts passes a throwaway array and simply ignores it. The
-     * caller owns clearing them, because the mark has to survive past this attempt — see the
-     * array's declaration in {@link commit}.
+     * @param cycle - The state this commit keeps across attempts (see {@link CommitCycle}). This
+     * attempt adds its participants to `cycle.participants` and one disposer per participant it marks
+     * in flight under this transaction's id (see {@link Collection.beginInFlightAction}) to
+     * `cycle.inFlightDisposers`. REQUIRED, so a future caller cannot silently reintroduce the
+     * unmarked refresh the disposers exist to prevent, nor lose track of who took part. The caller
+     * owns clearing the marks, because they have to survive past this attempt.
      */
     private commitOnce;
     /**
@@ -159,6 +272,10 @@ export declare class TransactionCoordinator {
      * participant's latch — every Collection member it touches (snapshotPending, getPendingActions,
      * recordCommitted, applyCommittedToCache, restorePending, clearPendingActions, tracker.reset)
      * is latch-free by contract.
+     *
+     * `cycle` is written only on a partial landing that is retried forward: the participants this
+     * attempt committed go into `cycle.saved`, so the retry loop reports every later failure as the
+     * partial landing it is (see {@link reportSaved}).
      */
     private commitOnceLatched;
     /**
@@ -225,7 +342,8 @@ export declare class TransactionCoordinator {
      * Coordinate a transaction across multiple collections.
      *
      * @param transaction - The transaction to coordinate
-     * @param operationsHash - Hash of all operations for validation
+     * @param validation - What every pend carries for members to re-check, or undefined for an
+     * unvalidated pend (see {@link pendValidationFor})
      * @param collectionTransforms - Map of collectionId to its transforms
      * @param criticalBlocks - Map of collectionId to its log tail blockId
      * @param pendedRevs - Per collection, the revision its log entry was stamped with (from
@@ -245,8 +363,10 @@ export declare class TransactionCoordinator {
     /**
      * PEND phase: Distribute transaction to all affected block clusters.
      *
-     * @param transaction - The full transaction for replay/validation
-     * @param operationsHash - Hash of all operations for validation
+     * @param transaction - The transaction being pended (its id names the action; its aged
+     * priority rides on an unvalidated pend)
+     * @param validation - What every pend carries for members to re-check, or undefined for an
+     * unvalidated pend (see {@link pendValidationFor})
      * @param collectionTransforms - Map of collectionId to its transforms
      * @param pendedRevs - Per collection, the revision its log entry was stamped with — the pend
      * request repeats it verbatim rather than recomputing from the collection (a recompute after

package/dist/src/transaction/coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAW,YAAY,EAAE,UAAU,EAAwC,MAAM,aAAa,CAAC;AACxH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAG5H,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AA2C1D;;;;;;;;;GASG;AACH,qBAAa,sBAAsB;IAwCjC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAxC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2EAiCuE;IACvE,OAAO,CAAC,SAAS,CAEZ;gBAGa,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IAGjE;;;;;;;;;OASG;IACG,YAAY,CACjB,OAAO,EAAE,iBAAiB,EAAE,EAC5B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAwBhB;;wCAEoC;IACpC,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;;OASG;YACW,eAAe;IAiB7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAsF5E;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,UAAU;IAkExB;;;;;;OAMG;YACW,iBAAiB;IAkK/B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC9C;;;;;;OAMG;IACH,aAAa,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC;IAe9C;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAMvB;;OAEG;IACH,mBAAmB,IAAI,cAAc,EAAE;IAQvC;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAM7B;;;;;;;;OAQG;IACG,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IA+R7F;;;;OAIG;YACW,wBAAwB;IA8EtC;;;;;;;;;;OAUG;YACW,qBAAqB;IA2EnC;;;;;;;OAOG;YACW,WAAW;IAmCzB;;;;;;;;;;OAUG;YACW,SAAS;IA4DvB;;;;OAIG;YACW,cAAc;IAwC5B;;;;;;OAMG;YACW,WAAW;IA4DzB;;;;OAIG;YACW,gBAAgB;IA0E9B;;;;;OAKG;YACW,WAAW;CAsBzB"}
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAW,YAAY,EAAE,UAAU,EAAwC,MAAM,aAAa,CAAC;AACxH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAG5H,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,6BAA6B,CAAC;AACjG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAwE1D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,qBAAa,sBAAsB;IA4CjC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IA5C7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2EAiCuE;IACvE,OAAO,CAAC,SAAS,CAEZ;IAEL;8BAC0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAGlC,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,EAChE,OAAO,GAAE,kBAAuB;IAKjC;;;;;;;OAOG;YACW,iBAAiB;IAU/B;;;;;;;;;OASG;IACG,YAAY,CACjB,OAAO,EAAE,iBAAiB,EAAE,EAC5B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAwBhB;;wCAEoC;IACpC,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;;OASG;YACW,eAAe;IAiB7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACG,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC5E;iGAC6F;YAC/E,cAAc;IA4F5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;YACW,sBAAsB;IA0BpC;;;;;;;;;6CASyC;IACzC,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,WAAW;IAqBnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;YACW,UAAU;IAgExB;;;;;;;;;;OAUG;YACW,iBAAiB;IAkN/B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC9C;;;;;;OAMG;IACH,aAAa,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC;IAe9C;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAMvB;;OAEG;IACH,mBAAmB,IAAI,cAAc,EAAE;IAQvC;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAM7B;;;;;;;;OAQG;IACG,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6S7F;;;;OAIG;YACW,wBAAwB;IA+EtC;;;;;;;;;;;OAWG;YACW,qBAAqB;IA2EnC;;;;;;;OAOG;YACW,WAAW;IAmCzB;;;;;;;;;;;;OAYG;YACW,SAAS;IA4DvB;;;;OAIG;YACW,cAAc;IAuD5B;;;;;;OAMG;YACW,WAAW;IA4DzB;;;;OAIG;YACW,gBAAgB;IAkF9B;;;;;OAKG;YACW,WAAW;CAsBzB"}