@optimystic/db-core 1.0.0-beta.2 → 1.0.0

package/dist/src/transactor/network-transactor.d.ts

@@ -1,5 +1,5 @@
 import type { PeerId } from "../network/types.js";
-import type { ActionTransforms, ActionBlocks, BlockActionStatus, ITransactor, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, CommitRequest, ClusterNomineesResult, CollectionId } from "../index.js";
+import type { ActionTransforms, ActionBlocks, ActionLineage, BlockActionStatus, ITransactor, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, CommitRequest, ClusterNomineesResult, CollectionId } from "../index.js";
 import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
 type NetworkTransactorInit = {
     timeoutMs: number;
@@ -23,6 +23,17 @@ type NetworkTransactorInit = {
      * absent, `onCollectionChange` is a logged no-op.
      */
     localChangeNotifier?: IBlockChangeNotifier;
+    /**
+     * The peer id of the node this transactor runs on, when `getRepo` hands that id the node's own
+     * co-located repo rather than a network client — the same "co-located node" idea as
+     * `localChangeNotifier`. It only breaks ties when a pend's blocks are grouped onto coordinators:
+     * among cohort members covering equally many blocks, this node wins, so a write it is responsible
+     * for is coordinated without a network hop. It never wins over a member covering more blocks
+     * (fewer batches come first), and it never makes this node a coordinator for a block whose cohort
+     * does not include it. Omit when nothing is co-located; ties then go to the member seen first,
+     * which is the nearest.
+     */
+    localPeerId?: PeerId;
 };
 export declare class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
     private readonly keyNetwork;
@@ -31,6 +42,8 @@ export declare class NetworkTransactor implements ITransactor, IBlockChangeNotif
     private readonly dialTimeoutMs;
     private readonly getRepo;
     private readonly localChangeNotifier;
+    /** `NetworkTransactorInit.localPeerId` as a string, the form cohort peer ids arrive in. */
+    private readonly localPeerId;
     /**
      * Per-transaction coordinator cache: `actionId → (blockId → resolved coordinator)`.
      * {@link pend} populates it from its final (retry-adjusted) batch assignment; commit
@@ -75,6 +88,26 @@ export declare class NetworkTransactor implements ITransactor, IBlockChangeNotif
     private refineInvalidatedStatuses;
     /** Whether `actionId` has a durable invalidation entry in `collectionId`'s log (opened once, cached). */
     private hasDurableInvalidation;
+    /**
+     * See {@link ITransactor.getLineage}. Asks EVERY member of each block's cohort, directly, and
+     * folds their answers with {@link judgeCohortLineage} — not the coordinator round {@link get}
+     * runs, because no single member can answer for the cohort: a member that took a later revision
+     * as a replica cannot say what it was built from, while the member it came from can.
+     *
+     * The per-member `get` carries no context, so it pins nothing and promotes nothing; asking is
+     * never what makes a write land.
+     *
+     * NOTE: one request per cohort member per block. Reached only when a writer's own half-landed
+     * write was refused as superseded, which is rare, so the fan-out is not batched by member. If a
+     * write path ever calls this routinely, group the blocks a member is in the cohort of into one
+     * request per member.
+     */
+    getLineage(ref: ActionBlocks & {
+        rev: number;
+    }): Promise<ActionLineage>;
+    /** One block's cohort answer: every member asked in parallel, a member that cannot be reached
+     *  (or whose cohort cannot be resolved at all) counted as `unknown` rather than left out. */
+    private cohortLineage;
     private consolidateCoordinators;
     pend(blockAction: PendRequest): Promise<PendResult>;
     /**
@@ -120,6 +153,9 @@ export declare class NetworkTransactor implements ITransactor, IBlockChangeNotif
      * `debt-unpromotable-pending-records-need-a-sweep`); and this covers only the sweep's abandonment
      * — `StorageRepo.commit`'s genuine-fault arm deliberately KEEPS a failed batch's pendings for a
      * retry, so it is a second producer of the same durable state whenever that retry never comes.
+     *
+     * @returns the abandoned block ids — exactly the set cancelled here — so {@link commit} can name
+     * them as `torn` on the acknowledgement without re-deriving the set by a second rule.
      */
     private cancelAbandonedSweepBlocks;
     private commitBlock;
@@ -130,11 +166,12 @@ export declare class NetworkTransactor implements ITransactor, IBlockChangeNotif
      * both must distinguish a confirmed conflict (return it; the caller cancels and re-drives) from
      * a transient fault (throw / tolerate).
      *
-     * NOTE: a reason-only StaleFailure (success:false, no `missing`) lands here too and returns
-     * `{ missing: [], success:false }` — the `reason` PROSE is dropped rather than surfaced.
-     * `staleAt` is carried, so the one machine-readable fact in that prose (which block is at which
-     * revision) survives; only the free-form wording is lost. If the wording itself is ever needed,
-     * gate this on non-empty missing rather than reinstating it unconditionally.
+     * Rebuilt the same way {@link pend}'s aggregate is: `reason` is the first one any batch gave
+     * (the only diagnostic that survives into the coordinator's error text — a refusal whose reason
+     * is `commit-not-durable` must not read as "stale commit", a rival's win), `conflict` holds when
+     * any batch was a classified conflict, and `staleAt` is the highest confirmed revision. A
+     * reason-only StaleFailure (success:false, no `missing`) lands here too and comes out with
+     * `missing: []` and its reason intact.
      */
     private staleFromBatches;
     /** Attempts to commit a set of blocks, and handles failures and errors.

package/dist/src/transactor/network-transactor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/network-transactor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"network-transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/network-transactor.ts"],"names":[],"mappings":"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"}