@optimystic/db-p2p 1.0.0-beta.3 → 1.0.0

package/dist/src/repo/client.js

@@ -1,4 +1,4 @@
-import { blockIdsForTransforms, blockIdToBytes } from "@optimystic/db-core";
+import { blockIdsForTransforms } from "@optimystic/db-core";
 import { ProtocolClient } from "../protocol-client.js";
 import { MAX_BLOCK_MESSAGE_BYTES } from "../protocol-limits.js";
 import { peerIdFromString } from "@libp2p/peer-id";
@@ -59,9 +59,28 @@ export class RepoClient extends ProtocolClient {
         // ResponseTimeoutError and mask the caller-facing 'RepoClient timeout' message.
         const deadlineController = new AbortController();
         const timer = setTimeout(() => deadlineController.abort(new Error('RepoClient timeout')), deadlineMs);
-        const combinedSignal = options?.signal
-            ? AbortSignal.any([options.signal, deadlineController.signal])
-            : deadlineController.signal;
+        // Explicit combinator rather than the native `AbortSignal.any`, which Hermes
+        // (React Native's JS engine) does not provide. This has to forward whichever
+        // source signal's *reason* fired — that's how the caller-facing 'RepoClient
+        // timeout' message above (and any reason a caller's own `options.signal` carries)
+        // survives the combine. `any-signal` (the package libp2p itself uses for this) was
+        // tried and rejected here: it calls the composite `AbortController.abort()` with no
+        // argument, which discards the source reason and replaces it with a generic
+        // AbortError — confirmed against both Node's native `AbortSignal.any` and
+        // `any-signal@4.1.1` directly. Listeners are removed in the `finally` below so a
+        // long-lived caller `options.signal` never accumulates one per call.
+        const abortController = new AbortController();
+        const forwardAbort = (source) => () => abortController.abort(source.reason);
+        const onCallerAbort = options?.signal ? forwardAbort(options.signal) : undefined;
+        const onDeadlineAbort = forwardAbort(deadlineController.signal);
+        deadlineController.signal.addEventListener('abort', onDeadlineAbort, { once: true });
+        if (options?.signal) {
+            if (options.signal.aborted)
+                abortController.abort(options.signal.reason);
+            else
+                options.signal.addEventListener('abort', onCallerAbort, { once: true });
+        }
+        const combinedSignal = abortController.signal;
         let response;
         try {
             response = await super.processMessage(message, preferred, {
@@ -74,6 +93,9 @@ export class RepoClient extends ProtocolClient {
         }
         finally {
             clearTimeout(timer);
+            deadlineController.signal.removeEventListener('abort', onDeadlineAbort);
+            if (onCallerAbort)
+                options?.signal?.removeEventListener('abort', onCallerAbort);
         }
         // Type the redirect branch against the payload the service actually produces
         // (`RedirectPayload`) rather than reading it off the `any` response — the untyped read
@@ -94,50 +116,37 @@ export class RepoClient extends ProtocolClient {
             // notice we get that this peer matters, and if it is relay-only we have no address
             // for it at all. Merging after the dial would help only some later hop.
             this.peerNetwork.recordPeerAddresses?.(nextId, next.addrs ?? []);
-            // cache hint — await so the recorded key bytes match what findCoordinator
-            // later looks up (blockIdToBytes is async); deterministic ordering also
-            // keeps the hint testable. The redirect retry below is async anyway.
-            await this.recordCoordinatorForOpsIfSupported(operations, nextId);
+            // Cache hint: a follow-up op on this block can dial the target directly.
+            const coordinated = this.coordinatedBlockId(operations);
+            if (coordinated)
+                this.recordCoordinatorHint(coordinated, nextId);
             // single-hop retry against target peer using repo protocol
             const nextClient = RepoClient.create(nextId, this.peerNetwork, this.protocolPrefix);
             return await nextClient.processRepoMessage(operations, options, hop + 1);
         }
         return response;
     }
-    async extractKeyFromOperations(ops) {
+    /**
+     * The block a redirected op is coordinated on — the block `RepoService.deriveBlockKey` redirected
+     * it by, and so the block its coordinator hint belongs to.
+     */
+    coordinatedBlockId(ops) {
         const op = ops[0];
-        // The recorded key MUST be the sha256 digest produced by blockIdToBytes — the
-        // exact bytes findCoordinator/recordCoordinator key the coordinator cache on
-        // (NetworkTransactor passes blockIdToBytes(blockId)). Raw utf8 of the id would
-        // never match, so the hint would silently never be retrieved.
-        if ('get' in op) {
-            const id = op.get.blockIds[0];
-            return id ? await blockIdToBytes(id) : undefined;
-        }
-        if ('pend' in op) {
-            // Key on a real block id the pend touches, NOT a structural transforms field
-            // name ('inserts'/'updates'/'deletes'); see RepoService.deriveBlockKey.
-            const id = blockIdsForTransforms(op.pend.transforms)[0];
-            return id ? await blockIdToBytes(id) : undefined;
-        }
-        if ('commit' in op) {
-            // Anchor on blockIds[0] (where CoordinatorRepo.commit runs consensus +
-            // verifyResponsibility), NOT tailId — they differ for a non-tail batch.
-            const id = op.commit.blockIds[0];
-            return id ? await blockIdToBytes(id) : undefined;
-        }
-        if ('cancel' in op) {
-            const id = op.cancel.actionRef.blockIds[0];
-            return id ? await blockIdToBytes(id) : undefined;
-        }
+        if (!op)
+            return undefined;
+        if ('get' in op)
+            return op.get.blockIds[0];
+        // Key on a real block id the pend touches, NOT a structural transforms field
+        // name ('inserts'/'updates'/'deletes'); see RepoService.deriveBlockKey.
+        if ('pend' in op)
+            return blockIdsForTransforms(op.pend.transforms)[0];
+        // Anchor on blockIds[0] (where CoordinatorRepo.commit runs consensus +
+        // verifyResponsibility), NOT tailId — they differ for a non-tail batch.
+        if ('commit' in op)
+            return op.commit.blockIds[0];
+        if ('cancel' in op)
+            return op.cancel.actionRef.blockIds[0];
         return undefined;
     }
-    async recordCoordinatorForOpsIfSupported(ops, peerId) {
-        const keyBytes = await this.extractKeyFromOperations(ops);
-        const pn = this.peerNetwork;
-        if (keyBytes != null && typeof pn?.recordCoordinator === 'function') {
-            pn.recordCoordinator(keyBytes, peerId);
-        }
-    }
 }
 //# sourceMappingURL=client.js.map

package/dist/src/repo/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/repo/client.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,OAAO,UAAW,SAAQ,cAAc;IAC2B;IAAxE,YAAoB,MAAc,EAAE,WAAyB,EAAW,cAAuB;QAC9F,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAD4C,mBAAc,GAAd,cAAc,CAAS;IAE/F,CAAC;IAED,mCAAmC;IAC5B,MAAM,CAAC,MAAM,CAAC,MAAc,EAAE,WAAyB,EAAE,cAAuB;QACtF,OAAO,IAAI,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,SAAoB,EAAE,OAAuB;QACtD,OAAO,IAAI,CAAC,kBAAkB,CAC7B,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,EACpB,OAAO,CACP,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAoB,EAAE,OAAuB;QACvD,OAAO,IAAI,CAAC,kBAAkB,CAC7B,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EACnB,OAAO,CACP,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAuB,EAAE,OAAuB;QAC5D,OAAO,IAAI,CAAC,kBAAkB,CAC7B,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,EAC3B,OAAO,CACP,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAsB,EAAE,OAAuB;QAC3D,OAAO,IAAI,CAAC,kBAAkB,CAC7B,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EACrB,OAAO,CACP,CAAC;IACH,CAAC;IAEO,oBAAoB,CAAC,UAAqC;QACjE,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,EAAE;YAAE,OAAO,SAAS,CAAC;QAC1B,IAAI,MAAM,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC1C,IAAI,QAAQ,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC9C,IAAI,QAAQ,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;QACxD,OAAO,SAAS,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,kBAAkB,CAC/B,UAAqC,EACrC,OAAuB,EACvB,MAAc,CAAC;QAEf,MAAM,OAAO,GAAgB;YAC5B,UAAU;YACV,UAAU,EAAE,OAAO,CAAC,UAAU;SAC9B,CAAC;QACF,MAAM,aAAa,GAAG,IAAI,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,CAAA;QAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QACrD,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,SAAS,CAAC,GAAG,aAAa,CAAA;QAEpE,2EAA2E;QAC3E,6EAA6E;QAC7E,4EAA4E;QAC5E,+EAA+E;QAC/E,yEAAyE;QACzE,gFAAgF;QAChF,4EAA4E;QAC5E,qEAAqE;QACrE,EAAE;QACF,+EAA+E;QAC/E,+DAA+D;QAC/D,gFAAgF;QAChF,MAAM,kBAAkB,GAAG,IAAI,eAAe,EAAE,CAAA;QAChD,MAAM,KAAK,GAAG,UAAU,CACvB,GAAG,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,EAC/D,UAAU,CACV,CAAA;QACD,MAAM,cAAc,GAAG,OAAO,EAAE,MAAM;YACrC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAC9D,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAA;QAC5B,IAAI,QAAa,CAAA;QACjB,IAAI,CAAC;YACJ,QAAQ,GAAG,MAAM,KAAK,CAAC,cAAc,CAAM,OAAO,EAAE,SAAS,EAAE;gBAC9D,MAAM,EAAE,cAAc;gBACtB,aAAa;gBACb,aAAa,EAAE,OAAO,EAAE,aAAa;gBACrC,+DAA+D;gBAC/D,aAAa,EAAE,uBAAuB;aACtC,CAAC,CAAA;QACH,CAAC;gBAAS,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;QAED,6EAA6E;QAC7E,uFAAuF;QACvF,iEAAiE;QACjE,MAAM,gBAAgB,GAAG,QAAoC,CAAA;QAC7D,IAAI,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAC/C,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAA;YAC3E,CAAC;YACD,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAA;YAC3C,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAA;YAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,YAAY,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,CAAA;YAClE,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACxC,IAAI,IAAI,CAAC,EAAE,KAAK,YAAY,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;YACpE,CAAC;YACD,oFAAoF;YACpF,mFAAmF;YACnF,wEAAwE;YACxE,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;YAChE,0EAA0E;YAC1E,wEAAwE;YACxE,qEAAqE;YACrE,MAAM,IAAI,CAAC,kCAAkC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;YACjE,2DAA2D;YAC3D,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,CAAA;YACnF,OAAO,MAAM,UAAU,CAAC,kBAAkB,CAAI,UAAU,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,CAAC,CAAA;QAC5E,CAAC;QACD,OAAO,QAAa,CAAC;IACtB,CAAC;IAEO,KAAK,CAAC,wBAAwB,CAAC,GAA8B;QACpE,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,8EAA8E;QAC9E,6EAA6E;QAC7E,+EAA+E;QAC/E,8DAA8D;QAC9D,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;YACjB,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC9B,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClD,CAAC;QACD,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC;YAClB,6EAA6E;YAC7E,wEAAwE;YACxE,MAAM,EAAE,GAAG,qBAAqB,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;YACxD,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClD,CAAC;QACD,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;YACpB,uEAAuE;YACvE,wEAAwE;YACxE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YACjC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClD,CAAC;QACD,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;YACpB,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC3C,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClD,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,kCAAkC,CAAC,GAA8B,EAAE,MAAc;QAC9F,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAA;QACzD,MAAM,EAAE,GAAQ,IAAI,CAAC,WAAkB,CAAA;QACvC,IAAI,QAAQ,IAAI,IAAI,IAAI,OAAO,EAAE,EAAE,iBAAiB,KAAK,UAAU,EAAE,CAAC;YACrE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QACvC,CAAC;IACF,CAAC;CAED"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/repo/client.ts"],"names":[],"mappings":"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"}

package/dist/src/repo/cluster-coordinator.d.ts

@@ -43,6 +43,29 @@ export declare class ConflictRaceLostError extends Error {
     /** peerId → messageHash of the rival transaction that member holds as the race winner. */
     conflicts: Record<string, string>);
 }
+/**
+ * The transaction's pend could not proceed because one or more members answered with a signed `held`
+ * vote: the requested blocks are reserved by a different unresolved action in that member's durable
+ * storage. Sibling of {@link ConflictRaceLostError} and retryable for the same reason — nobody judged
+ * this write invalid; it queued behind a reservation that disappears when the holder commits or
+ * cancels.
+ *
+ * The two are separate because they name different things. A conflict vote names the winning rival's
+ * `messageHash`, which the member holds whole; a held vote can only name the rival's **action id**,
+ * because it fires in the window where the rival has left the member's in-memory table but not yet its
+ * storage. `CoordinatorRepo.pend` converts this into a `StaleFailure` with `conflict: true` so the
+ * normal retry machinery (`isConflictFailure`) absorbs it, exactly as it does a lost race.
+ *
+ * Only a PEND record can produce it: `held` votes come from `ClusterMember.validatePendOperations`,
+ * which inspects pend operations only, so `CoordinatorRepo.commit` never meets one.
+ */
+export declare class BlocksHeldError extends Error {
+    /** peerId → actionId of the unresolved action that member's storage says holds the blocks. */
+    readonly heldBy: Record<string, string>;
+    constructor(message: string, 
+    /** peerId → actionId of the unresolved action that member's storage says holds the blocks. */
+    heldBy: Record<string, string>);
+}
 /** Cancel handle for an injected timer; cancels a not-yet-fired timer (safe no-op after fire/cancel). */
 export type TimerCancel = () => void;
 /**
@@ -57,6 +80,19 @@ export interface ClusterCoordinatorClock {
     setTimer?: (fn: () => void, delayMs: number) => TimerCancel;
 }
 /** Manages distributed transactions across clusters */
+/**
+ * What a cohort lookup established about a block's cohort. `resolved: false` covers BOTH a lookup
+ * that threw and one that answered with nobody: neither names a destination for a write, and the
+ * durability class both produce is the same (`unrouted`). `reason` is for logs only — never branch
+ * on it.
+ */
+export type CohortResolution = {
+    readonly resolved: true;
+    readonly peerIds: readonly string[];
+} | {
+    readonly resolved: false;
+    readonly reason: string;
+};
 export declare class ClusterCoordinator {
     private readonly keyNetwork;
     /** Factory for a per-peer cluster RPC handle; only `update` is ever called, hence `ICluster`. */
@@ -116,9 +152,45 @@ export declare class ClusterCoordinator {
      */
     private createMessageHash;
     /**
-     * Gets all peers in the cluster for a specific block ID
+     * The ONE cohort lookup every accessor on this class derives from: the raw peer map when the key
+     * network answered, otherwise the reason it did not. A thrown `findCluster` is logged here and
+     * nowhere else. Callers that need the map (`executeClusterTransaction`, which builds the record's
+     * `peers`) go through {@link getClusterForBlock}; callers that need to know whether the cohort
+     * RESOLVED go through {@link resolveCohort}.
+     */
+    private lookupCluster;
+    /**
+     * Gets all peers in the cluster for a specific block ID. Empty when the lookup failed — the
+     * consensus path treats "no cohort" and "lookup failed" alike (there is nobody to run consensus
+     * with either way); a caller that must tell them apart uses {@link resolveCohort}.
      */
     private getClusterForBlock;
+    /**
+     * Whether the block's cohort could be established, and who it is. The primitive behind
+     * {@link getClusterPeerIds} and {@link getClusterSize}: a lookup that threw and a lookup that named
+     * nobody used to reach every caller as the same empty list, and `CoordinatorRepo`'s solo
+     * short-circuit then acknowledged a write it had no idea where to send exactly as it acknowledged a
+     * write to a genuine cohort of one (GitHub #19). Both shapes are still `resolved: false` here —
+     * neither names a destination — but they are distinguishable from a resolved cohort, which is what
+     * the write's durability class needs (`unrouted` vs `local`).
+     */
+    resolveCohort(blockId: BlockId): Promise<CohortResolution>;
+    /**
+     * A node never runs a cluster transaction for a cohort it is not in. Behind members reconcile from the
+     * coordinator's own proof-carrying copy (its member applies before the merged record fans out), and a
+     * coordinator outside `record.peers` is not a reconcile target — so a cohort with no holder would stay
+     * behind and the commit durability gate would refuse, having first put this node's vote and storage
+     * where the cohort does not look. The invariant is held here, at the one place a record's `peers` is
+     * chosen, rather than left to the routing convention.
+     *
+     * Fires only on a RESOLVED cohort (at least one peer) that excludes the wired local member. An empty
+     * cohort is a failed lookup, not a cohort this node is outside of, so it is left to `executeTransaction`'s
+     * size checks; `CoordinatorRepo`'s solo short-circuit keeps unresolved and single-peer cohorts away from
+     * this method altogether in any case. After its responsibility check, what remains is a multi-member
+     * cohort that changed inside the responsibility cache's staleness window. With no local member wired the guard does not apply: that
+     * bypass exists for wiring without an identity (direct constructors, some tests), never for production.
+     */
+    private assertLocalMemberInCohort;
     private makeRecord;
     /**
      * Initiates a 2-phase transaction for a specific block ID.
@@ -181,10 +253,10 @@ export declare class ClusterCoordinator {
      */
     private executeTransaction;
     /**
-     * The block's cohort peer ids as currently derivable. Empty when `findCluster` fails
-     * (getClusterForBlock swallows the throw), so a caller branching on `length <= 1` is also taking
-     * the degraded-routing branch; `CoordinatorRepo.commit` uses the ids to log whether a solo cohort
-     * is genuinely just self or a routing failure.
+     * The block's cohort peer ids as currently derivable. Empty when the cohort did not resolve
+     * ({@link resolveCohort}: `findCluster` threw, or named nobody), so a caller branching on
+     * `length <= 1` is also taking the degraded-routing branch. Derived from `resolveCohort` rather
+     * than re-deriving the cohort, so there is exactly one lookup rule.
      */
     getClusterPeerIds(blockId: BlockId): Promise<string[]>;
     /** {@link getClusterPeerIds}, counted. Derived from it rather than re-deriving the cohort, so the

package/dist/src/repo/cluster-coordinator.d.ts.map

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

package/dist/src/repo/cluster-coordinator.js

@@ -1,8 +1,9 @@
 import { peerIdFromString } from "@libp2p/peer-id";
-import { CURRENT_MEMBERSHIP_VERSION, computeClusterMessageHash, isConflictFailure, membershipDigest } from "@optimystic/db-core";
+import { CURRENT_MEMBERSHIP_VERSION, computeClusterMessageHash, isConflictFailure, membershipDigest, routingKeyForBlock } from "@optimystic/db-core";
 import { Pending } from "@optimystic/db-core";
 import { createLogger, verbose } from '../logger.js';
 import { PenaltyReason } from "../reputation/types.js";
+import { ResponsibilityRefusalError } from "./responsibility.js";
 const log = createLogger('cluster');
 /**
  * Pick each peer's OWN {@link ClusterRecord.applyOutcomes} entry out of the record that peer answered
@@ -79,6 +80,32 @@ export class ConflictRaceLostError extends Error {
         this.name = 'ConflictRaceLostError';
     }
 }
+/**
+ * The transaction's pend could not proceed because one or more members answered with a signed `held`
+ * vote: the requested blocks are reserved by a different unresolved action in that member's durable
+ * storage. Sibling of {@link ConflictRaceLostError} and retryable for the same reason — nobody judged
+ * this write invalid; it queued behind a reservation that disappears when the holder commits or
+ * cancels.
+ *
+ * The two are separate because they name different things. A conflict vote names the winning rival's
+ * `messageHash`, which the member holds whole; a held vote can only name the rival's **action id**,
+ * because it fires in the window where the rival has left the member's in-memory table but not yet its
+ * storage. `CoordinatorRepo.pend` converts this into a `StaleFailure` with `conflict: true` so the
+ * normal retry machinery (`isConflictFailure`) absorbs it, exactly as it does a lost race.
+ *
+ * Only a PEND record can produce it: `held` votes come from `ClusterMember.validatePendOperations`,
+ * which inspects pend operations only, so `CoordinatorRepo.commit` never meets one.
+ */
+export class BlocksHeldError extends Error {
+    heldBy;
+    constructor(message, 
+    /** peerId → actionId of the unresolved action that member's storage says holds the blocks. */
+    heldBy) {
+        super(message);
+        this.heldBy = heldBy;
+        this.name = 'BlocksHeldError';
+    }
+}
 /**
  * Production timer binding: a one-shot `setTimeout` whose handle is **unref'd** so a pending
  * commit-retry (or the deferred transaction cleanup) never keeps an otherwise-idle process alive.
@@ -91,7 +118,6 @@ function defaultSetTimer(fn, delayMs) {
     handle.unref?.();
     return () => clearTimeout(handle);
 }
-/** Manages distributed transactions across clusters */
 export class ClusterCoordinator {
     keyNetwork;
     createClusterClient;
@@ -183,21 +209,76 @@ export class ClusterCoordinator {
         return computeClusterMessageHash(message, membershipDigestValue);
     }
     /**
-     * Gets all peers in the cluster for a specific block ID
+     * The ONE cohort lookup every accessor on this class derives from: the raw peer map when the key
+     * network answered, otherwise the reason it did not. A thrown `findCluster` is logged here and
+     * nowhere else. Callers that need the map (`executeClusterTransaction`, which builds the record's
+     * `peers`) go through {@link getClusterForBlock}; callers that need to know whether the cohort
+     * RESOLVED go through {@link resolveCohort}.
      */
-    async getClusterForBlock(blockId) {
-        const blockIdBytes = new TextEncoder().encode(blockId);
+    async lookupCluster(blockId) {
         try {
-            const peers = await this.keyNetwork.findCluster(blockIdBytes);
+            const peers = await this.keyNetwork.findCluster(routingKeyForBlock(blockId));
             const peerIds = Object.keys(peers ?? {});
             log('cluster-tx:cluster-members', { blockId, peerIds });
-            return peers;
+            return { peers: peers ?? {} };
         }
         catch (e) {
             log('WARN findCluster failed for %s: %o', blockId, e);
-            return {};
+            return { reason: `findCluster threw: ${e?.message ?? String(e)}` };
         }
     }
+    /**
+     * Gets all peers in the cluster for a specific block ID. Empty when the lookup failed — the
+     * consensus path treats "no cohort" and "lookup failed" alike (there is nobody to run consensus
+     * with either way); a caller that must tell them apart uses {@link resolveCohort}.
+     */
+    async getClusterForBlock(blockId) {
+        const outcome = await this.lookupCluster(blockId);
+        return 'peers' in outcome ? outcome.peers : {};
+    }
+    /**
+     * Whether the block's cohort could be established, and who it is. The primitive behind
+     * {@link getClusterPeerIds} and {@link getClusterSize}: a lookup that threw and a lookup that named
+     * nobody used to reach every caller as the same empty list, and `CoordinatorRepo`'s solo
+     * short-circuit then acknowledged a write it had no idea where to send exactly as it acknowledged a
+     * write to a genuine cohort of one (GitHub #19). Both shapes are still `resolved: false` here —
+     * neither names a destination — but they are distinguishable from a resolved cohort, which is what
+     * the write's durability class needs (`unrouted` vs `local`).
+     */
+    async resolveCohort(blockId) {
+        const outcome = await this.lookupCluster(blockId);
+        if ('reason' in outcome)
+            return { resolved: false, reason: outcome.reason };
+        const peerIds = Object.keys(outcome.peers);
+        if (peerIds.length === 0)
+            return { resolved: false, reason: 'findCluster named nobody' };
+        return { resolved: true, peerIds };
+    }
+    /**
+     * A node never runs a cluster transaction for a cohort it is not in. Behind members reconcile from the
+     * coordinator's own proof-carrying copy (its member applies before the merged record fans out), and a
+     * coordinator outside `record.peers` is not a reconcile target — so a cohort with no holder would stay
+     * behind and the commit durability gate would refuse, having first put this node's vote and storage
+     * where the cohort does not look. The invariant is held here, at the one place a record's `peers` is
+     * chosen, rather than left to the routing convention.
+     *
+     * Fires only on a RESOLVED cohort (at least one peer) that excludes the wired local member. An empty
+     * cohort is a failed lookup, not a cohort this node is outside of, so it is left to `executeTransaction`'s
+     * size checks; `CoordinatorRepo`'s solo short-circuit keeps unresolved and single-peer cohorts away from
+     * this method altogether in any case. After its responsibility check, what remains is a multi-member
+     * cohort that changed inside the responsibility cache's staleness window. With no local member wired the guard does not apply: that
+     * bypass exists for wiring without an identity (direct constructors, some tests), never for production.
+     */
+    assertLocalMemberInCohort(blockId, peers) {
+        if (!this.localCluster)
+            return;
+        const peerIds = Object.keys(peers);
+        const selfId = this.localCluster.peerId.toString();
+        if (peerIds.length === 0 || peerIds.includes(selfId))
+            return;
+        log('cluster-tx:not-in-cohort', { blockId, selfId, peerIds });
+        throw new ResponsibilityRefusalError('not-responsible', [blockId], `refusing to coordinate a cluster transaction for a cohort this node is not in: ${peerIds.join(', ')}`);
+    }
     makeRecord(peers, messageHash, message, membershipDigestValue) {
         const peerCount = Object.keys(peers ?? {}).length;
         const record = {
@@ -253,6 +334,7 @@ export class ClusterCoordinator {
             : { ...message, coordinatingBlockIds: [blockId] };
         // Get the cluster peers for this block
         const peers = await this.getClusterForBlock(blockId);
+        this.assertLocalMemberInCohort(blockId, peers);
         // Bind the responsible membership into the transaction identity (v2): the digest is folded into
         // the messageHash below, so two different peer sets produce two different messageHashes rather
         // than one hash with a silent internal disagreement about who is responsible.
@@ -382,17 +464,23 @@ export class ClusterCoordinator {
         // Collect promises with super-majority requirement
         const promised = await this.collectPromises(peers, record);
         const superMajority = Math.ceil(peerCount * this.cfg.superMajorityThreshold);
-        // Count approvals, rejections and conflict votes separately. A `conflict` vote is a member
-        // saying "not now — I hold the race winner": it must count toward NEITHER approvals NOR
-        // rejections, or a lost race would masquerade as a validator rejection (permanent) or as
-        // silence (indistinguishable from an unreachable cohort) — both wrong.
+        // Count approvals, rejections and the two RETRYABLE refusals separately. A `conflict` vote is a
+        // member saying "not now — I hold the race winner"; a `held` vote is a member saying "not now —
+        // a different unresolved action holds these blocks in my storage". Neither may count toward
+        // approvals OR rejections, or a transient refusal would masquerade as a validator rejection
+        // (permanent) or as silence (indistinguishable from an unreachable cohort) — both wrong.
         const promises = promised.record.promises;
         const approvalCount = Object.values(promises).filter(sig => sig.type === 'approve').length;
         const rejectionCount = Object.values(promises).filter(sig => sig.type === 'reject').length;
         const conflictCount = Object.values(promises).filter(sig => sig.type === 'conflict').length;
+        const heldCount = Object.values(promises).filter(sig => sig.type === 'held').length;
         // Check if rejections make super-majority impossible
         // If more than (peerCount - superMajority) nodes reject, we can never reach super-majority
         const maxAllowedRejections = peerCount - superMajority;
+        // Whether the merged record itself PROVES super-majority unreachable — the same sum a member
+        // re-derives as `ConflictSuperseded`/`Rejected` from the signed votes, which is what makes an
+        // abandonment broadcast proof-carrying rather than an unauthenticated "forget this".
+        const refusalsProveUnreachable = rejectionCount + conflictCount + heldCount > maxAllowedRejections;
         if (rejectionCount > maxAllowedRejections) {
             const rejectReasonsByPeer = Object.fromEntries(Object.entries(promises)
                 .flatMap(([peerId, sig]) => sig.type === 'reject' ? [[peerId, sig.rejectReason ?? 'unknown']] : []));
@@ -436,11 +524,33 @@ export class ClusterCoordinator {
             // super-majority (members re-derive ConflictSuperseded/Rejected from the signed votes and
             // clear their reservations immediately). Below that bar the record proves nothing and a
             // broadcast would be the unauthenticated "forget this" the shortfall NOTE below refuses.
-            if (rejectionCount + conflictCount > maxAllowedRejections) {
+            if (refusalsProveUnreachable) {
                 this.broadcastAbandonment(promised.record, 'conflict-race-lost');
             }
             throw new ConflictRaceLostError(`Conflict race lost: ${conflictCount}/${peerCount} member(s) hold a conflicting winner (${approvalCount}/${superMajority} approvals)`, conflicts);
         }
+        // A `held`-answered shortfall is the OTHER retryable refusal: the pend queued behind a rival's
+        // unresolved reservation. Checked after the conflict branch so a lost race still wins when both
+        // answer — a conflict vote names the winning transaction's messageHash, which is strictly more
+        // actionable than an action id — and, like it, before the generic shortfall, which must stay
+        // reserved for the genuinely-silent cohort.
+        if (heldCount > 0 && approvalCount < superMajority) {
+            const heldBy = Object.fromEntries(Object.entries(promises)
+                .flatMap(([peerId, sig]) => sig.type === 'held' ? [[peerId, sig.heldBy]] : []));
+            log('cluster-tx:pend-blocks-held', {
+                messageHash: record.messageHash,
+                peerCount,
+                approvals: approvalCount,
+                rejections: rejectionCount,
+                heldBy,
+                superMajority
+            });
+            this.updateTransactionRecord(promised.record, 'pend-blocks-held');
+            if (refusalsProveUnreachable) {
+                this.broadcastAbandonment(promised.record, 'pend-blocks-held');
+            }
+            throw new BlocksHeldError(`Pend blocks held: ${heldCount}/${peerCount} member(s) hold an unresolved rival action (${approvalCount}/${superMajority} approvals)`, heldBy);
+        }
         if (peerCount > 1 && approvalCount < superMajority) {
             log('cluster-tx:supermajority-failed', {
                 messageHash: record.messageHash,
@@ -459,7 +569,8 @@ export class ClusterCoordinator {
             // their own staleness sweep instead.
             // NOTE: the message below is load-bearing wire text — the consuming repo
             // (sereus cadre-core control-write-retry) matches it verbatim to retry a genuinely-silent
-            // cohort. Keep it byte-identical, and never fold conflict votes into its rejection count.
+            // cohort. Keep it byte-identical, and never fold `conflict` or `held` votes into its
+            // rejection count.
             throw new Error(`Failed to get super-majority: ${approvalCount}/${peerCount} approvals (needed ${superMajority}, ${rejectionCount} rejections)`);
         }
         // Mark as disputed when minority rejections exist but super-majority approves
@@ -492,14 +603,14 @@ export class ClusterCoordinator {
         return await this.commitTransaction(promised.record);
     }
     /**
-     * The block's cohort peer ids as currently derivable. Empty when `findCluster` fails
-     * (getClusterForBlock swallows the throw), so a caller branching on `length <= 1` is also taking
-     * the degraded-routing branch; `CoordinatorRepo.commit` uses the ids to log whether a solo cohort
-     * is genuinely just self or a routing failure.
+     * The block's cohort peer ids as currently derivable. Empty when the cohort did not resolve
+     * ({@link resolveCohort}: `findCluster` threw, or named nobody), so a caller branching on
+     * `length <= 1` is also taking the degraded-routing branch. Derived from `resolveCohort` rather
+     * than re-deriving the cohort, so there is exactly one lookup rule.
      */
     async getClusterPeerIds(blockId) {
-        const peers = await this.getClusterForBlock(blockId);
-        return Object.keys(peers ?? {});
+        const cohort = await this.resolveCohort(blockId);
+        return cohort.resolved ? [...cohort.peerIds] : [];
     }
     /** {@link getClusterPeerIds}, counted. Derived from it rather than re-deriving the cohort, so the
      *  size a caller branches on and the ids it logs can never come from two different rules. */