@serfab/cadre-core 0.9.0 → 0.10.0

package/dist/strand-backfill.d.ts

@@ -0,0 +1,109 @@
+import type { Libp2p, PeerId } from '@libp2p/interface';
+import type { IPeerNetwork } from '@optimystic/db-core';
+import { BlockTransferClient, type IRawStorage } from '@optimystic/db-p2p';
+/**
+ * The block-transfer protocol's hard cap on one length-prefixed message. Mirrors
+ * `MAX_BLOCK_MESSAGE_BYTES` in `@optimystic/db-p2p`'s `protocol-limits.ts` (8 MiB), which
+ * that package does not re-export from its index — keep the two in sync if upstream ever
+ * changes it or starts exporting it.
+ */
+export declare const MAX_BLOCK_MESSAGE_BYTES: number;
+/** Tuning for the per-peer strand catch-up. Every field optional; defaults in {@link DEFAULT_STRAND_BACKFILL}. */
+export interface StrandBackfillConfig {
+    /** Default true. False disables the catch-up entirely (the pre-existing behaviour). */
+    enabled?: boolean;
+    /** Settle time after a connection opens before catching that peer up, ms. Default 1000. */
+    debounceMs?: number;
+    /** Ceiling on blocks copied in one catch-up. Default 10_000. Reaching it is LOGGED, never silent. */
+    maxBlocks?: number;
+    /** Soft byte budget per push message. Default 1 MiB. Protocol hard cap is {@link MAX_BLOCK_MESSAGE_BYTES} (8 MiB). */
+    maxChunkBytes?: number;
+    /** Max blocks per push message. Default 64. */
+    maxChunkBlocks?: number;
+    /** Per-push dial deadline, ms. Default 3000 (matches SpreadOnChurnMonitor). */
+    dialTimeoutMs?: number;
+    /** Per-push response deadline, ms. Default 10_000 (matches SpreadOnChurnMonitor). */
+    responseTimeoutMs?: number;
+}
+/** The resolved defaults every {@link StrandBackfill} starts from. */
+export declare const DEFAULT_STRAND_BACKFILL: Required<StrandBackfillConfig>;
+/**
+ * The one capability the catch-up needs from a transfer client. Structural (rather than
+ * the concrete `BlockTransferClient`) so unit tests can capture pushes without dialing
+ * libp2p — see {@link StrandBackfillDeps.createPushClient}.
+ */
+export type StrandBackfillPushClient = Pick<BlockTransferClient, 'pushBlocks'>;
+export interface StrandBackfillDeps {
+    strandId: string;
+    /** The STRAND's libp2p node (not the control node) — source of connection events and peer ids. */
+    libp2p: Libp2p;
+    /** `node.keyNetwork`, the IPeerNetwork BlockTransferClient dials through. */
+    peerNetwork: IPeerNetwork;
+    /** This strand's own raw block store — the same instance handed to the libp2p node. */
+    storage: IRawStorage;
+    /** Must equal the prefix the receiver registered its handler under: `/optimystic/strand-<strandId>`. */
+    protocolPrefix: string;
+    /**
+     * Test seam: build the per-peer push client. Defaults to a real
+     * `BlockTransferClient` over {@link peerNetwork} + {@link protocolPrefix}.
+     */
+    createPushClient?: (peerId: PeerId) => StrandBackfillPushClient;
+}
+/** What one peer's catch-up actually did. Returned for tests and logged at the end of each run. */
+export interface StrandBackfillResult {
+    /** Blocks offered: had a committed `latest` AND materialized content locally. */
+    offered: number;
+    /** Blocks the remote reported it persisted. */
+    accepted: number;
+    /** Block ids the remote reported in `missing` (parse or persist failure on its side). */
+    rejected: string[];
+    /** Skipped: metadata has no `latest` (pending-only — not yet a durability claim here). */
+    uncommitted: number;
+    /** Skipped: `latest` exists but no materialized block is stored for that actionId. */
+    unmaterialized: number;
+    /** Not attempted because `maxBlocks` was reached. */
+    capped: number;
+    /** Skipped: a single block whose wire size alone exceeds {@link MAX_BLOCK_MESSAGE_BYTES}. */
+    oversized: string[];
+}
+/**
+ * Copies every block in one strand's own raw store to each peer its libp2p node connects
+ * to, so a peer that joined the strand after blocks were committed still ends up holding
+ * them physically (the receiver persists each push via `saveReplicatedBlock`, which is
+ * monotonic and idempotent — crossing pushes from both ends cannot regress a revision).
+ *
+ * Best-effort throughout: nothing here throws into a libp2p event handler or into
+ * `buildStrandRuntime`; a failed chunk is logged and the run continues. A peer is marked
+ * fully caught up ONLY after a run with no thrown chunk and an empty `missing` list, so
+ * the next `connection:open` from a peer whose catch-up failed retries it.
+ */
+export declare class StrandBackfill {
+    private readonly deps;
+    private readonly config;
+    private readonly createPushClient;
+    private started;
+    private stopped;
+    /** Peers fully caught up this runtime (never retried until the runtime is rebuilt). */
+    private readonly done;
+    /** Peers with a catch-up currently running (suppresses concurrent duplicates). */
+    private readonly inFlight;
+    /** Pending per-peer debounce timers, cleared on stop. */
+    private readonly timers;
+    private readonly onConnectionOpen;
+    private loggedNoListBlockIds;
+    constructor(deps: StrandBackfillDeps, config?: StrandBackfillConfig);
+    /** Subscribe to connection:open AND schedule a catch-up for peers already connected. */
+    start(): void;
+    /** Unsubscribe, clear timers; in-flight runs observe the stopped flag and bail. */
+    stop(): void;
+    /** Debounced entry point for connection churn: one run per peer per settle window. */
+    private schedulePeer;
+    /**
+     * Run one peer's catch-up now, bypassing the debounce. Never rejects. Returns an
+     * all-zero result without pushing when the peer is already caught up, already being
+     * caught up, or this backfill is stopped.
+     */
+    catchUpPeer(peerId: PeerId): Promise<StrandBackfillResult>;
+    /** The actual copy. `clean` = every chunk pushed and the remote persisted every block. */
+    private runCatchUp;
+}

package/dist/strand-backfill.js

@@ -0,0 +1,279 @@
+import debug from 'debug';
+import { BlockTransferClient } from '@optimystic/db-p2p';
+// NOTE: this copies the WHOLE local store to every newly connected strand peer, which is
+// right while a strand mesh is one party's handful of machines (see docs/architecture.md →
+// Replication cluster size, "On a strand, the machine count is not a party count"). If
+// strand meshes ever get large, filter the pushed set by FRET cohort responsibility for
+// each block id instead of pushing everything.
+//
+// NOTE: this lives in cadre-core only because `../optimystic` is read-only from this repo.
+// If Optimystic ever grows a cohort-join catch-up of its own, delete this module rather
+// than running two.
+//
+// Membership: anything connected on the strand's own libp2p network already receives
+// cohort replicas of new commits, so pushing older blocks to it exposes nothing new. No
+// membership gate here — adding one would diverge from what ordinary replication already
+// does on this network. A peer that does NOT speak this strand's block-transfer protocol
+// (a bare circuit relay or bootstrap node the strand node also connects to) cannot receive
+// anything: the protocol id is namespaced per strand, so the dial fails and the push is
+// dropped.
+//
+// NOTE: that failing case costs one dial timeout per connection:open from such a peer, and
+// is never memoized (only clean runs are). Bounded today by the debounce plus the
+// unreachable-peer bail in `runCatchUp` — one dial per event, not one per chunk. If a strand
+// node ever holds many non-strand connections, or the enumeration ahead of the first chunk
+// gets expensive, pre-check `libp2p.peerStore` for this strand's block-transfer protocol
+// before enumerating.
+//
+// NOTE: a run that fails is retried only when that peer next opens a connection. Over a
+// stable connection a transient push failure therefore leaves the peer partially copied
+// until the next reconnect (read repair still covers reads meanwhile). If strand meshes
+// ever hold long-lived connections where that matters, re-arm the debounce timer with a
+// backoff on a non-clean run instead of waiting for connection:open.
+const log = debug('sereus:cadre:strand-backfill');
+/**
+ * The block-transfer protocol's hard cap on one length-prefixed message. Mirrors
+ * `MAX_BLOCK_MESSAGE_BYTES` in `@optimystic/db-p2p`'s `protocol-limits.ts` (8 MiB), which
+ * that package does not re-export from its index — keep the two in sync if upstream ever
+ * changes it or starts exporting it.
+ */
+export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
+/** The resolved defaults every {@link StrandBackfill} starts from. */
+export const DEFAULT_STRAND_BACKFILL = {
+    enabled: true,
+    debounceMs: 1000,
+    maxBlocks: 10000,
+    maxChunkBytes: 1024 * 1024,
+    maxChunkBlocks: 64,
+    dialTimeoutMs: 3000,
+    responseTimeoutMs: 10000
+};
+function emptyResult() {
+    return { offered: 0, accepted: 0, rejected: [], uncommitted: 0, unmaterialized: 0, capped: 0, oversized: [] };
+}
+/**
+ * Base64 wire size of a raw buffer — `pushBlocks` base64-encodes each block into the JSON
+ * request, so the protocol cap must be judged against the encoded size, not the raw bytes.
+ */
+function base64WireBytes(rawBytes) {
+    return Math.ceil(rawBytes / 3) * 4;
+}
+/**
+ * Copies every block in one strand's own raw store to each peer its libp2p node connects
+ * to, so a peer that joined the strand after blocks were committed still ends up holding
+ * them physically (the receiver persists each push via `saveReplicatedBlock`, which is
+ * monotonic and idempotent — crossing pushes from both ends cannot regress a revision).
+ *
+ * Best-effort throughout: nothing here throws into a libp2p event handler or into
+ * `buildStrandRuntime`; a failed chunk is logged and the run continues. A peer is marked
+ * fully caught up ONLY after a run with no thrown chunk and an empty `missing` list, so
+ * the next `connection:open` from a peer whose catch-up failed retries it.
+ */
+export class StrandBackfill {
+    constructor(deps, config) {
+        this.deps = deps;
+        this.started = false;
+        this.stopped = false;
+        /** Peers fully caught up this runtime (never retried until the runtime is rebuilt). */
+        this.done = new Set();
+        /** Peers with a catch-up currently running (suppresses concurrent duplicates). */
+        this.inFlight = new Set();
+        /** Pending per-peer debounce timers, cleared on stop. */
+        this.timers = new Map();
+        this.loggedNoListBlockIds = false;
+        this.config = { ...DEFAULT_STRAND_BACKFILL, ...config };
+        this.createPushClient = deps.createPushClient
+            ?? ((peerId) => new BlockTransferClient(peerId, deps.peerNetwork, deps.protocolPrefix));
+        this.onConnectionOpen = (evt) => this.schedulePeer(evt.detail.remotePeer);
+    }
+    /** Subscribe to connection:open AND schedule a catch-up for peers already connected. */
+    start() {
+        if (this.started || this.stopped || !this.config.enabled)
+            return;
+        this.started = true;
+        this.deps.libp2p.addEventListener('connection:open', this.onConnectionOpen);
+        // A runtime rebuilt over live connections (resumeStrand) never sees their
+        // connection:open, so walk what is already connected once.
+        const existing = this.deps.libp2p.getConnections();
+        for (const connection of existing) {
+            this.schedulePeer(connection.remotePeer);
+        }
+        log('[%s] started (%d peer(s) already connected)', this.deps.strandId, existing.length);
+    }
+    /** Unsubscribe, clear timers; in-flight runs observe the stopped flag and bail. */
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.started) {
+            this.deps.libp2p.removeEventListener('connection:open', this.onConnectionOpen);
+        }
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        log('[%s] stopped', this.deps.strandId);
+    }
+    /** Debounced entry point for connection churn: one run per peer per settle window. */
+    schedulePeer(peerId) {
+        const key = peerId.toString();
+        if (this.stopped || this.done.has(key) || this.inFlight.has(key))
+            return;
+        const existing = this.timers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        this.timers.set(key, setTimeout(() => {
+            this.timers.delete(key);
+            void this.catchUpPeer(peerId);
+        }, this.config.debounceMs));
+    }
+    /**
+     * Run one peer's catch-up now, bypassing the debounce. Never rejects. Returns an
+     * all-zero result without pushing when the peer is already caught up, already being
+     * caught up, or this backfill is stopped.
+     */
+    async catchUpPeer(peerId) {
+        const key = peerId.toString();
+        if (this.stopped || this.done.has(key) || this.inFlight.has(key)) {
+            return emptyResult();
+        }
+        this.inFlight.add(key);
+        try {
+            const { result, clean } = await this.runCatchUp(peerId);
+            // NOTE: a run that hit `maxBlocks` is still "clean" and still memoizes the peer, so
+            // the tail past the ceiling never reaches it. Deliberate: enumeration is not
+            // resumable, so not memoizing would re-push the same prefix on every reconnect
+            // without ever advancing. Loud in the log below (capped > 0). If a strand's store can
+            // realistically exceed maxBlocks, the fix is a resumable cursor, not either policy.
+            if (clean && !this.stopped) {
+                this.done.add(key);
+            }
+            log('[%s] catch-up peer=%s offered=%d accepted=%d rejected=%d uncommitted=%d unmaterialized=%d capped=%d oversized=%d done=%s', this.deps.strandId, key, result.offered, result.accepted, result.rejected.length, result.uncommitted, result.unmaterialized, result.capped, result.oversized.length, clean);
+            return result;
+        }
+        catch (error) {
+            // runCatchUp already contains a per-chunk catch; this guards the enumeration and
+            // metadata reads too — a backfill fault must never surface through a libp2p event.
+            log('[%s] catch-up peer=%s failed: %o', this.deps.strandId, key, error);
+            return emptyResult();
+        }
+        finally {
+            this.inFlight.delete(key);
+        }
+    }
+    /** The actual copy. `clean` = every chunk pushed and the remote persisted every block. */
+    async runCatchUp(peerId) {
+        const result = emptyResult();
+        const { storage } = this.deps;
+        if (!storage.listBlockIds) {
+            if (!this.loggedNoListBlockIds) {
+                this.loggedNoListBlockIds = true;
+                log('[%s] raw storage does not implement listBlockIds(); backfill is inert', this.deps.strandId);
+            }
+            return { result, clean: false };
+        }
+        const client = this.createPushClient(peerId);
+        const encoder = new TextEncoder();
+        let chunk = { ids: [], buffers: [], meta: {}, bytes: 0 };
+        let chunkFailed = false;
+        let anyChunkDelivered = false;
+        /**
+         * A peer that has answered no push at all, and failed one, is not reachable on this
+         * protocol — abandon rather than spend a dial timeout per remaining chunk. Once ONE
+         * push has been answered the peer demonstrably speaks it, so a later failure is a
+         * transient blip and the rest of the store is still worth pushing.
+         */
+        const peerUnreachable = () => chunkFailed && !anyChunkDelivered;
+        const flush = async () => {
+            if (chunk.ids.length === 0)
+                return;
+            const { ids, buffers, meta } = chunk;
+            chunk = { ids: [], buffers: [], meta: {}, bytes: 0 };
+            try {
+                const response = await client.pushBlocks(ids, buffers, 'replication', meta, {
+                    dialTimeoutMs: this.config.dialTimeoutMs,
+                    responseTimeoutMs: this.config.responseTimeoutMs
+                });
+                anyChunkDelivered = true;
+                const missing = new Set(response.missing);
+                for (const id of ids) {
+                    if (missing.has(id)) {
+                        result.rejected.push(id);
+                    }
+                    else {
+                        result.accepted += 1;
+                    }
+                }
+                if (response.missing.length > 0) {
+                    log('[%s] peer=%s rejected %d block(s): %o', this.deps.strandId, peerId.toString(), response.missing.length, response.missing);
+                }
+            }
+            catch (error) {
+                chunkFailed = true;
+                log('[%s] push to peer=%s failed for %d block(s): %s', this.deps.strandId, peerId.toString(), ids.length, error.message);
+            }
+        };
+        for await (const blockId of storage.listBlockIds()) {
+            if (this.stopped)
+                break;
+            if (result.offered >= this.config.maxBlocks) {
+                // Past the ceiling: count what is left (id enumeration only — no more reads or
+                // pushes) so the cap is loud in the end-of-run log rather than silent.
+                result.capped += 1;
+                continue;
+            }
+            const metadata = await storage.getMetadata(blockId);
+            const latest = metadata?.latest;
+            if (!latest) {
+                result.uncommitted += 1;
+                continue;
+            }
+            // NOTE: a block whose latest revision is a DELETE materializes to nothing (a
+            // tombstone), so it is skipped here — a peer that joins after such a delete never
+            // receives the tombstone from this path and relies on read repair for it. Fine
+            // while nothing deletes whole blocks pre-join; if the whole-store coverage gate in
+            // strand-membership-closed-strand-e2e ever reports a tombstone residue, teach this
+            // to push the promoted delete transform instead of skipping.
+            const block = await storage.getMaterializedBlock(blockId, latest.actionId);
+            if (!block) {
+                result.unmaterialized += 1;
+                log('[%s] block=%s has latest rev %d but no materialized content; skipped', this.deps.strandId, blockId, latest.rev);
+                continue;
+            }
+            const buffer = encoder.encode(JSON.stringify(block));
+            // NOTE: MAX_BLOCK_MESSAGE_BYTES caps the whole framed request, not one block, and
+            // this test ignores the request envelope (ids array, blockMeta, JSON punctuation).
+            // A lone block within a few KiB of the cap therefore still ships and is rejected by
+            // the receiver's length-prefix decoder — a permanent chunk failure for that peer. No
+            // block in a strand comes close today; if one ever can, subtract a measured envelope
+            // allowance here rather than raising the cap.
+            if (base64WireBytes(buffer.length) >= MAX_BLOCK_MESSAGE_BYTES) {
+                result.oversized.push(blockId);
+                log('[%s] block=%s is %d bytes (%d on the wire) — exceeds the %d-byte protocol cap alone; skipped', this.deps.strandId, blockId, buffer.length, base64WireBytes(buffer.length), MAX_BLOCK_MESSAGE_BYTES);
+                continue;
+            }
+            // Flush before adding when this block would overflow either budget. A single block
+            // larger than maxChunkBytes still ships — alone, in its own chunk.
+            if (chunk.ids.length > 0
+                && (chunk.ids.length + 1 > this.config.maxChunkBlocks || chunk.bytes + buffer.length > this.config.maxChunkBytes)) {
+                await flush();
+                if (this.stopped || peerUnreachable())
+                    break;
+            }
+            chunk.ids.push(blockId);
+            chunk.buffers.push(buffer);
+            chunk.meta[blockId] = { rev: latest.rev, actionId: latest.actionId };
+            chunk.bytes += buffer.length;
+            result.offered += 1;
+        }
+        if (!this.stopped && !peerUnreachable()) {
+            await flush();
+        }
+        if (result.capped > 0) {
+            log('[%s] peer=%s catch-up CAPPED at %d blocks; %d block id(s) not attempted', this.deps.strandId, peerId.toString(), this.config.maxBlocks, result.capped);
+        }
+        const clean = !chunkFailed && result.rejected.length === 0;
+        return { result, clean };
+    }
+}
+//# sourceMappingURL=strand-backfill.js.map

package/dist/strand-backfill.js.map

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

package/dist/strand-formation-manager.d.ts

@@ -9,6 +9,14 @@ export interface StrandFormationManagerConfig {
     sessionTimeoutMs?: number;
     /** Step timeout in milliseconds */
     stepTimeoutMs?: number;
+    /**
+     * Provisioning budget in milliseconds for the RESPONDER's `provisionStrand` hook call.
+     * The initiator's `await-response` wait is derived automatically from this value plus
+     * `PROVISION_RESPONSE_TRAVEL_MARGIN_MS` (`strand-formation-protocol.ts`) — never set
+     * directly — so the ordering documented there (approval hook < responder provisioning <
+     * initiator await-response < session) cannot collapse when this is configured.
+     */
+    provisionTimeoutMs?: number;
     /** Maximum concurrent sessions */
     maxConcurrentSessions?: number;
     /** Enable debug logging */
@@ -73,10 +81,16 @@ export declare class StrandFormationManager {
      * Form a strand with a responder via an open invitation (initiator side).
      *
      * Builds a contact message carrying the real token + disclosure + this party's
-     * real cadre addresses, dials the responder over the native protocol, and
-     * validates the responder's result before returning.
+     * real cadre addresses + the joiner's consent (minted and signed by the
+     * solicitation layer — this manager only places it on the contact), dials the
+     * responder over the native protocol, and validates the responder's result
+     * before returning.
      */
-    formStrand(invitation: OpenInvitation, disclosure: StrandFormationDisclosure, node: Libp2p): Promise<FormStrandResult>;
+    formStrand(invitation: OpenInvitation, disclosure: StrandFormationDisclosure, consent: {
+        peerKey: string;
+        usageStampId: string;
+        peerSignature: string;
+    }, node: Libp2p): Promise<FormStrandResult>;
     /**
      * Get the number of active sessions
      */
@@ -84,6 +98,16 @@ export declare class StrandFormationManager {
         listeners: number;
         dialers: number;
     };
+    /**
+     * Derive the initiator's await-response budget from the configured RESPONDER budget —
+     * never the same number (see `StrandFormationManagerConfig.provisionTimeoutMs`). Mirrors
+     * `resolveProvisionTimeoutMs`'s own "`0`/negative means unset" rule so an unset config
+     * still lets both sides fall back to their own independent defaults; must NOT hardcode
+     * `DEFAULT_PROVISION_TIMEOUT_MS` here, or the per-role clamping downstream is defeated.
+     * A value too large for the session is clamped per role, and the responder's ceiling holds
+     * the same margin back, so the ordering survives there too.
+     */
+    private initiatorProvisionTimeoutMs;
     private validateToken;
     private validateDisclosure;
     /**
@@ -101,12 +125,17 @@ export declare class StrandFormationManager {
      *   deferred `StrandExists` CHECK at commit and drop the frame.
      * - **unbound** (no binding): the responder-provisions fallback — see {@link provisionUnbound}.
      *
-     * Defense-in-depth: known provisioning/redeem failures (notably the concurrent
-     * `(Token, UseNumber)` PK collision when two redemptions of one unbound single-use invite
-     * race) are caught and mapped to a logged, retry-suggesting rejection rather than a thrown
-     * insert + a silently-closed stream. The LOG-before-reject keeps this a deliberate
-     * internal-error→protocol-rejection conversion (AGENTS.md: don't eat exceptions silently),
-     * not control-flow-by-exception.
+     * Defense-in-depth: known provisioning/redeem failures are caught and mapped to a logged
+     * protocol rejection rather than a thrown insert + a silently-closed stream. The mapping is
+     * per-failure, NOT blanket retry-suggesting: an exhausted invitation
+     * ({@link InvitationExhaustedError}, raised by `ControlDatabase` whenever a redemption's use
+     * number is past the invite's seat budget — including a first attempt racing another
+     * redemption of the same token on this node, not only a retry) is reported as `'Invalid
+     * token'`, because retrying it can never succeed. The
+     * `(Token, UseNumber)` PK collision that concurrent redemptions of one invite used to
+     * surface here is now retried a layer down and no longer reaches this method. The
+     * LOG-before-reject keeps this a deliberate internal-error→protocol-rejection conversion
+     * (AGENTS.md: don't eat exceptions silently), not control-flow-by-exception.
      */
     private provisionAsResponder;
     /**