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

package/src/network/struct.ts

@@ -34,11 +34,14 @@ export type PendRequest = ActionTransforms & {
 	 * 'r' is return, which fails but returns the pending ActionIds and their transforms */
 	policy: 'c' | 'f' | 'r';
 	/**
-	 * Present only on the multi-collection path (`TransactionCoordinator.pendCollection`): the
-	 * transaction to re-execute plus the hash of ALL operations across all blocks it must produce.
-	 * Absent on the single-collection `Collection.sync` path, which carries bare transforms and is
-	 * therefore not re-checkable — see `ClusterConsensusConfig.unvalidatablePendPolicy` for what a
-	 * validating receiver does with that shape. ONE optional pair, deliberately: "transaction
+	 * Present only on a validated multi-collection pend (`TransactionCoordinator.pendCollection`
+	 * under its default `pendValidation: 'transaction'`): the transaction to re-execute plus the
+	 * hash of ALL operations across all blocks it must produce. Absent on every pend that carries
+	 * bare transforms and is therefore not re-checkable — the single-collection `Collection.sync`
+	 * path, and a coordinator built with `pendValidation: 'none'` (the Quereus adapter's legacy
+	 * multi-tree commit, which has no statements to re-execute) — see
+	 * `ClusterConsensusConfig.unvalidatablePendPolicy` for what a validating receiver does with
+	 * that shape. ONE optional pair, deliberately: "transaction
 	 * without its hash" (or the reverse) was a state the old two independent optional fields
 	 * permitted and no producer ever created — and a receiver whose guard required both could be
 	 * talked out of validating by a sender that omitted one.
@@ -52,27 +55,103 @@ export type PendRequest = ActionTransforms & {
 	/** For multi-collection transactions: supercluster nominees for consensus */
 	superclusterNominees?: PeerId[];
 	/**
-	 * Aged, advisory retry priority for the *single-collection* pend path (default 0 when absent).
-	 * The multi-collection path instead carries priority on the transaction inside
+	 * Aged, advisory retry priority for a pend that carries no transaction (default 0 when absent).
+	 * A validated multi-collection pend instead carries priority on the transaction inside
 	 * {@link PendRequest.validation} ({@link Transaction.priority}); this top-level field is the
-	 * carrier for a `Collection.sync` pend, which has no transaction. A cluster member reads whichever is present as the first
+	 * carrier for every pend without one — a `Collection.sync` pend, and an unvalidated
+	 * coordinator pend (`pendValidation: 'none'`). A cluster member reads whichever is present as the first
 	 * `resolveRace` tiebreak. FAIRNESS-ONLY: it rides inside the signed cluster `message` (so it is
 	 * integrity-protected in transit) but MUST NOT affect the operations hash, stale-read checks, or
 	 * validity — a stale pend is still rejected regardless of priority.
 	 */
 	priority?: number;
+	/**
+	 * Per block, the committed revision of the base the author's update operations were computed
+	 * against (`Tracker.stagedBaseRevs`). Present for a block whose transform is update-only and
+	 * whose base the author knows; never for an inserted or deleted block (base-independent), and
+	 * absent for a block the author did not read through a source that reports revisions. Omitted
+	 * entirely when empty (`baseRevsField`): the request is hashed verbatim into every cohort
+	 * signature preimage, so a pend that declares nothing must serialize exactly as it did before
+	 * the field existed. Action-wide here; the transactor narrows it to each per-coordinator batch's
+	 * own block ids at send time, exactly as it narrows {@link CommitRequest.blockDigests}.
+	 *
+	 * Storage keeps it beside the pending record (`BlockMetadata.pendingBases` in db-p2p), so every
+	 * later step that applies the record can refuse to apply it to a different version of the block
+	 * — including the read-driven promotion in `StorageRepo.get`, which has no commit message to
+	 * consult. The commit's own `blockDigests[id].baseRev` is now the fallback for a record whose
+	 * pend named no base, not the primary check.
+	 */
+	baseRevs?: BlockBaseRevs;
 };
 
 export type BlockActionStatus = ActionBlocks & {
 	statuses: ('pending' | 'committed' | 'checkpointed' | 'aborted' | 'committed-invalidated')[];
 };
 
+/** How widely a successful write is known to be held at the moment it was acknowledged. */
+export type DurabilityQuorum =
+	/** Every member of the resolved cohort confirmed it holds the revision. */
+	| 'full'
+	/** A strict majority confirmed — the acknowledgement bar — but at least one member did not.
+	 *  Also the class of a torn action whose cohort confirmed everything it was asked for
+	 *  (`withTornBlocks` clamps `full` down to this; `torn` then names the blocks, and `unconfirmed`
+	 *  may be empty). */
+	| 'majority'
+	/** The cohort resolved, and it is this node alone. Nobody else holds the revision yet. */
+	| 'local'
+	/** The cohort did NOT resolve: the lookup threw, or named nobody, or named a single peer that
+	 *  is not this node. The write is on this node's storage and the network was never consulted.
+	 *  Deliberately NOT `local`: a genuine cohort of one is a correct, complete write, whereas this
+	 *  is a write whose correct destination is unknown. */
+	| 'unrouted';
+
+/** What the answering layer knows about who holds a successful write. Each layer refines it:
+ *  `StorageRepo` answers for itself alone, `CoordinatorRepo` answers for the cohort the write ran
+ *  on, and `NetworkTransactor` merges the per-coordinator answers into one action-level answer.
+ *  Never a policy input — read it to DISPLAY or to REPAIR, never to decide acceptance.
+ *
+ *  The only "this write is completely saved" test is `isFullyDurable` (`network/durability.ts`);
+ *  do not compare `quorum` by hand, because a `full` cohort report can still sit on an action that
+ *  abandoned blocks (`torn`). */
+export type WriteDurability = {
+	readonly quorum: DurabilityQuorum;
+	/** Cohort members confirmed to hold the write, including this node when it holds it.
+	 *  For a commit this means "reported that its storage durably holds the revision"; for a pend
+	 *  it means "accepted the pending record". The two are NOT comparable — a pend confers no
+	 *  storage durability (see the note in `CoordinatorRepo.pendThroughCluster`). */
+	readonly confirmed: number;
+	/** Size of the cohort the write ran on. Zero exactly when `quorum` is 'unrouted'. */
+	readonly cohort: number;
+	/** Cohort members that did not confirm, by peer-id string. Empty when `quorum` is 'full'.
+	 *  ABSENT (not empty) when the answering layer could not name the cohort — an empty array
+	 *  here means "named the cohort, nobody is missing". */
+	readonly unconfirmed?: readonly string[];
+	/** The cohort the write ran on, by peer-id string. Absent where the answering layer has no
+	 *  cohort view at all (a bare `StorageRepo` verdict). */
+	readonly cohortPeerIds?: readonly string[];
+	/** Present only on an action-level result assembled from MORE THAN ONE distinct coordinator
+	 *  answer: the other answers. Identical answers are collapsed (`mergeDurability`), so a healthy
+	 *  single-cohort commit has none; one cohort answering differently for two batches appears
+	 *  twice. The scalar fields above always describe the WEAKEST answer, so a consumer that reads
+	 *  only them is reading the binding constraint and is never over-optimistic. */
+	readonly otherCohorts?: readonly WriteDurability[];
+	/** Blocks this action wrote that are NOT committed — a torn sweep abandoned and cancelled them
+	 *  (`NetworkTransactor.cancelAbandonedSweepBlocks`). Action-level commit results only.
+	 *  These blocks NEVER heal by replication: their transform is gone, and only the writer
+	 *  re-driving the action puts them back. */
+	readonly torn?: readonly BlockId[];
+};
+
 export type PendSuccess = {
 	success: true;
 	/** List of already pending actions that were found on blocks touched by this pend */
 	pending: ActionPending[];
 	/** The affected blocks */
 	blockIds: BlockId[];
+	/** Who accepted the pending record. REQUIRED, not optional: an absent field would read as plain
+	 *  success, which is exactly the ambiguity this field exists to remove (a solo write, a write
+	 *  whose cohort never resolved, and a quorum write all used to answer `{ success: true }`). */
+	durability: WriteDurability;
 };
 
 export type StaleFailure = {
@@ -124,6 +203,12 @@ export type BlockContentDigest = {
  *  digest without a network read is simply omitted, and falls back to corroboration downstream. */
 export type BlockContentDigests = Record<BlockId, BlockContentDigest>;
 
+/** Per block, the committed revision its update operations were computed against — the shape
+ *  `Tracker.stagedBaseRevs` produces and {@link PendRequest.baseRevs} carries. Optional per id: an
+ *  inserted or deleted block is base-independent and never named; a block updated without a known
+ *  base is simply omitted. */
+export type BlockBaseRevs = Record<BlockId, number>;
+
 export type CommitRequest = ActionBlocks & {
 	/** The header block of the collection, present only when this commit creates the collection
 	 *  (the header is a fresh insert). Collection-identifying metadata, not an ordering signal —
@@ -185,6 +270,11 @@ export type CommitSuccess = {
 	success: true;
 	/** If present, the identified collection acts as the coordinator for the multi-collection transaction */
 	coordinatorId?: CollectionId;
+	/** Who holds the committed revision. REQUIRED for the same reason as {@link PendSuccess.durability}:
+	 *  a quorum commit, a solo commit, a commit whose cohort lookup failed, and a torn multi-block
+	 *  commit all answered `{ success: true }` before this field existed, and a writer could not tell
+	 *  them apart (GitHub #19). Test it through `isFullyDurable`, never by comparing `quorum`. */
+	durability: WriteDurability;
 };
 
 export type BlockActionState = {
@@ -197,6 +287,61 @@ export type BlockActionState = {
 export type BlockGets = {
 	blockIds: BlockId[];
 	context?: ActionContext;	// Latest if this is omitted
+	/** Per block, the lowest revision the ASKER can accept for it — its floor. Omit a block that
+	 *  has none; omit the field entirely when no block does.
+	 *
+	 *  A floor is knowledge only the asker holds: a collection that walked the log entry
+	 *  "action A, committed at revision r, changed block X" knows a read of X at a context at or
+	 *  above `r` must come back materialized at `r` or later, while the repo answering may honestly
+	 *  believe its older copy is current. `TransactorSource.tryGet` fills this from the collection's
+	 *  `BlockFloors`; `NetworkTransactor.get` treats an answer under a block's floor as NOT answered,
+	 *  so it earns the same second-chance round against a different coordinator that `unavailable`
+	 *  and `unconfirmedAheadRev` earn.
+	 *
+	 *  CLIENT-SIDE HINT, never on the wire: `NetworkTransactor.get` builds its own
+	 *  `{ blockIds, context }` for each downstream `IRepo.get`, so this field reaches no peer and no
+	 *  coordinator's freshness decision. An `ITransactor` that ignores it (`TestTransactor`, the
+	 *  reference peer's) stays correct, because the reader-side check that actually enforces the
+	 *  floor runs on the merged answer either way (`TransactorSource` / `BlockFloorCheck`).
+	 *
+	 *  NOTE: the retry `NetworkTransactor.get` runs is per BATCH, not per block, so one below-floor
+	 *  block re-asks every block that shared its coordinator. Costs nothing today — `tryGet` asks
+	 *  for one block per request, so this map never holds more than one entry — but a read source
+	 *  that batches would pay it. Split the retry payload down to the failing block ids then. */
+	floors?: Record<BlockId, number>;
+	/** Ask the answering repo whether each block's CURRENT content was built from this committed
+	 *  action at this revision; it answers per block in {@link GetBlockResult.lineage}. On the wire,
+	 *  unlike `floors`. A repo that predates the field leaves `lineage` absent, which every consumer
+	 *  reads as `unknown`. Asked only by a writer deciding whether its own superseded write is saved
+	 *  (`ITransactor.getLineage`); an ordinary read never sets it. */
+	lineageOf?: ActionRev;
+};
+
+/**
+ * Whether a block's current content was BUILT FROM a given committed `(actionId, rev)` — the
+ * write's transform is part of what the block holds now, even though later actions have since
+ * taken later revisions.
+ *
+ * - `contains` — it was. Holding that exact revision as the latest counts.
+ * - `excludes` — it provably was not: another action holds that revision of the block, or the
+ *   block's history spans that revision without it. Nothing can land the write there any more.
+ * - `behind` — the block has not reached that revision (or does not exist). The write is not
+ *   there, and could only get there through one of its own pending records.
+ * - `unknown` — not established either way.
+ *
+ * One repo answers from its own records only ({@link GetBlockResult.lineage}); a transactor
+ * answers for the block's cohort ({@link ActionLineage}).
+ */
+export type BlockLineage = 'contains' | 'excludes' | 'behind' | 'unknown';
+
+/** A cohort-level answer to "is this committed write part of what these blocks hold now?" — see
+ *  `ITransactor.getLineage`. */
+export type ActionLineage = {
+	/** One answer per requested block id, in request order. */
+	blocks: BlockLineage[];
+	/** Who holds the write, present exactly when EVERY block answered `contains`: the weakest
+	 *  block's cohort report, by the same rule a commit's durability is merged. */
+	durability?: WriteDurability;
 };
 
 /** Why a repo could not establish whether a block exists. Present ONLY when the repo
@@ -262,6 +407,9 @@ export type GetBlockResult = {
 	 *  the content here is real, it may just be behind. Absent = confirmed, so every
 	 *  producer that omits it keeps its meaning. */
 	unconfirmedAheadRev?: number;
+	/** This repo's answer to {@link BlockGets.lineageOf}, from its OWN records only — no cohort
+	 *  view. Absent when the question was not asked, or the repo predates it. */
+	lineage?: BlockLineage;
 };
 
 /**