@serfab/cadre-core 1.7.0 → 1.8.0

package/dist/strand-addr-protocol.d.ts

@@ -20,7 +20,7 @@
  *
  * **Authorization (v1):** like wake, the receiver defers entirely to the injected
  * `isMember` predicate and requires no further signature; a peer it rejects gets
- * an empty address list. `CadreNode` injects its AUTHORIZED-membership predicate
+ * a `refused` reply with no addresses. `CadreNode` injects its AUTHORIZED-membership predicate
  * (`isAuthorizedMember`: voucher on the requester's `CadrePeer` row verified
  * against the node-local trusted-owner anchor), so an outsider that published its
  * own rows into the replicated control DB cannot harvest live strand addresses.
@@ -64,7 +64,7 @@ export interface StrandAddrServiceOptions {
     readTimeoutMs?: number;
     /**
      * Cap on concurrent inbound strand-addr streams (defaults to
-     * {@link DEFAULT_MAX_CONCURRENT_ADDRS}). Over the cap, an empty response is
+     * {@link DEFAULT_MAX_CONCURRENT_ADDRS}). Over the cap, an `unavailable` reply is
      * returned without looking up any strand address.
      */
     maxConcurrent?: number;
@@ -73,7 +73,8 @@ export interface StrandAddrServiceOptions {
  * Receiver side of the strand-address RPC. Registers a `STRAND_ADDR_PROTOCOL`
  * handler on the control node and, for each inbound {@link StrandAddrRequest},
  * gates on cadre membership, then replies with the local strand instance's live
- * multiaddrs (or an empty list when not a member / not running).
+ * multiaddrs — `ok` with an empty list when the strand is not running, `refused`
+ * for a non-member, `unavailable` when it could not answer at all.
  */
 export declare class StrandAddrService {
     private readonly options;
@@ -85,30 +86,40 @@ export declare class StrandAddrService {
     constructor(options: StrandAddrServiceOptions);
     /** Number of in-flight inbound strand-addr streams. */
     get activeCount(): number;
-    /** Register the strand-addr protocol handler on the control node. */
-    initialize(node: Libp2p): void;
+    /**
+     * Register the strand-addr protocol handler on the control node. Rejects when
+     * libp2p refuses the registration (a duplicate handler, a peer-store write
+     * failure); the node reference is kept only once the handler is in place.
+     */
+    initialize(node: Libp2p): Promise<void>;
     /** Unregister the handler and release the node reference. */
     shutdown(): Promise<void>;
     /**
      * Read the inbound request, decide the response, and write it back.
      *
-     * Three hardening layers, all reported as an empty {@link StrandAddrResponse}
-     * rather than a dropped/hung stream: a concurrency cap (over
-     * {@link maxConcurrent}, reply without looking up any address), a read timeout
-     * (a peer that never half-closes is aborted inside {@link readFrame}/
-     * `readStreamToEnd`), and the existing malformed/oversized-frame guard.
+     * Three hardening layers, all reported as an `unavailable`
+     * {@link StrandAddrResponse} rather than a dropped/hung stream: a concurrency cap
+     * (over {@link maxConcurrent}, reply without looking up any address), a read
+     * timeout (a peer that never half-closes is aborted inside {@link readFrame}/
+     * `readStreamToEnd`), and the existing malformed/oversized-frame guard. A
+     * lookup that throws — the membership read failing, say — is `unavailable` too,
+     * never a `refused` or an empty `ok` the asker would wait ten minutes on.
      */
     private handleStream;
+    /** Read and decide one inbound request; any failure becomes an `unavailable` response. */
+    private answerStream;
     /**
      * Decide the response for a decoded request. Exposed (not private) so the
      * decision matrix can be unit-tested directly (mirrors wake's
      * `processWakeRequest`).
      *
-     * - Non-member sender → empty `multiaddrs` (refused), no delegate grant.
+     * - Non-member sender → `refused`, no delegate grant.
      * - Member request carrying a `delegatePeerId` → recorded via
      *   {@link StrandAddrServiceOptions.onDelegateAnnounce} before the lookup.
-     * - Strand not running locally → empty `multiaddrs` (`getStrandMultiaddrs` → `[]`).
-     * - Member + running strand → the strand's live, signaling-first multiaddrs.
+     * - Strand not running locally → `ok` with empty `multiaddrs` (`getStrandMultiaddrs` → `[]`).
+     * - Member + running strand → `ok` with the strand's live, signaling-first multiaddrs.
+     *
+     * A throwing `isMember` propagates; {@link handleStream} answers it `unavailable`.
      */
     processAddrRequest(request: StrandAddrRequest, remotePeerId: string): Promise<StrandAddrResponse>;
     /**
@@ -132,7 +143,13 @@ export interface StrandAddrPeer {
 }
 /** Options for {@link collectStrandAddrs}. */
 export interface CollectStrandAddrsOptions {
-    /** Per-dial timeout in ms (default {@link DEFAULT_ADDR_TIMEOUT_MS}). */
+    /**
+     * The asker's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which the
+     * per-dial timeout is derived when {@link timeoutMs} is not given. Unset means the declared
+     * default.
+     */
+    linkRoundTripMs?: number;
+    /** Per-dial timeout in ms (default: {@link attemptTimeoutMs}). */
     timeoutMs?: number;
     /** Override the protocol id (defaults to {@link STRAND_ADDR_PROTOCOL}). */
     protocolId?: string;
@@ -144,18 +161,38 @@ export interface CollectStrandAddrsOptions {
      */
     delegatePeerId?: string;
 }
+/**
+ * What asking one sibling produced, as {@link collectStrandAddrs} reports it.
+ *
+ * - `answered` — status `ok` with at least one address.
+ * - `empty` — status `ok` with no address: the sibling does not run the strand
+ *   right now, a normal steady state.
+ * - `unavailable` — the sibling replied that it could not answer.
+ * - `refused` — the sibling does not (yet) count the asker as an authorized member.
+ * - `unreachable` — no reply at all: every dial target failed or timed out, or
+ *   the reply was malformed.
+ */
+export type StrandAddrOutcome = 'answered' | 'empty' | 'unavailable' | 'refused' | 'unreachable';
+/** Result of {@link collectStrandAddrs}. */
+export interface StrandAddrCollection {
+    /** Deduplicated union of every answer, signaling-first. */
+    addrs: string[];
+    /** One entry per candidate (self excluded), keyed by the sibling's control peerId. */
+    outcomes: Map<string, StrandAddrOutcome>;
+}
 /**
  * Client side: ask each candidate sibling for its live strand-`strandId`
  * multiaddrs and return the **deduplicated union** of every answer, ordered
- * signaling-first.
+ * signaling-first, alongside each sibling's {@link StrandAddrOutcome}.
  *
- * Best-effort per peer: a failed/timed-out/empty sibling is logged and skipped,
- * never fatal — an empty union (no sibling online or running the strand) returns
- * `[]`, which the caller treats as an acceptable seed that self-heals on the next
- * resume/reconcile pass. The local node (`node.peerId`) is excluded so we never
- * RPC ourselves or seed with our own strand address.
+ * Best-effort per peer: a failed/timed-out/empty sibling contributes no address
+ * and never fails the collection — an empty union (no sibling online or running
+ * the strand) is an acceptable seed that self-heals on the next resume/reconcile
+ * pass. `outcomes` is what lets a caller retry the siblings that could not answer
+ * sooner than the ones that answered with nothing. The local node (`node.peerId`)
+ * is excluded so we never RPC ourselves or seed with our own strand address.
  *
  * Dials run concurrently but the union preserves candidate order, so the result
  * is deterministic regardless of which sibling answers first.
  */
-export declare function collectStrandAddrs(node: Libp2p, peers: StrandAddrPeer[], strandId: string, options?: CollectStrandAddrsOptions): Promise<string[]>;
+export declare function collectStrandAddrs(node: Libp2p, peers: StrandAddrPeer[], strandId: string, options?: CollectStrandAddrsOptions): Promise<StrandAddrCollection>;

package/dist/strand-addr-protocol.js

@@ -20,7 +20,7 @@
  *
  * **Authorization (v1):** like wake, the receiver defers entirely to the injected
  * `isMember` predicate and requires no further signature; a peer it rejects gets
- * an empty address list. `CadreNode` injects its AUTHORIZED-membership predicate
+ * a `refused` reply with no addresses. `CadreNode` injects its AUTHORIZED-membership predicate
  * (`isAuthorizedMember`: voucher on the requester's `CadrePeer` row verified
  * against the node-local trusted-owner anchor), so an outsider that published its
  * own rows into the replicated control DB cannot harvest live strand addresses.
@@ -31,7 +31,8 @@ import debug from 'debug';
 import { peerIdFromString } from '@libp2p/peer-id';
 import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
 import { orderSignalingFirst } from './peer-record.js';
-import { writeFrame, withDeadline, exchangeFrame, readStreamToEnd } from './control-stream.js';
+import { withDeadline, exchangeFrame, readStreamToEnd, replyAndClose } from './control-stream.js';
+import { relayedRequestBudgetMs } from './link-budget.js';
 const log = debug('sereus:cadre:strand-addr');
 /** Protocol id for the control-network strand-address RPC (parallel to `/sereus/strand-wake/1.0.0`). */
 export const STRAND_ADDR_PROTOCOL = '/sereus/strand-addr/1.0.0';
@@ -41,9 +42,8 @@ export const STRAND_ADDR_PROTOCOL = '/sereus/strand-addr/1.0.0';
  * that bounds the bytes a peer can make the receiver buffer per stream.
  */
 const MAX_ADDR_SIZE = 64 * 1024;
-/** Default time to wait for the response before abandoning a strand-addr dial (ms). */
-const DEFAULT_ADDR_TIMEOUT_MS = 10000;
 /** Default time the receiver waits for an inbound request frame before aborting (ms). */
+// eslint-disable-next-line no-restricted-syntax -- link-independent: a receiver cap on one small request frame on a stream the peer already opened; it bounds a peer that opens a stream and never sends, not the dial
 const DEFAULT_ADDR_READ_TIMEOUT_MS = 10000;
 /** Default cap on concurrent inbound strand-addr streams a single peer can pin open. */
 const DEFAULT_MAX_CONCURRENT_ADDRS = 100;
@@ -58,15 +58,16 @@ async function readFrame(stream, timeoutMs) {
     const body = decodeLengthPrefixedFrame(data, MAX_ADDR_SIZE);
     return JSON.parse(new TextDecoder().decode(body));
 }
-/** Empty response used on every reject/error path (cap, malformed frame, non-member). */
-function emptyResponse(strandId) {
-    return { strandId, multiaddrs: [] };
+/** An address-free reply, for every path but a member's lookup: cap, unreadable request, lookup failure, non-member. */
+function addrlessResponse(status, strandId) {
+    return { status, strandId, multiaddrs: [] };
 }
 /**
  * Receiver side of the strand-address RPC. Registers a `STRAND_ADDR_PROTOCOL`
  * handler on the control node and, for each inbound {@link StrandAddrRequest},
  * gates on cadre membership, then replies with the local strand instance's live
- * multiaddrs (or an empty list when not a member / not running).
+ * multiaddrs — `ok` with an empty list when the strand is not running, `refused`
+ * for a non-member, `unavailable` when it could not answer at all.
  */
 export class StrandAddrService {
     constructor(options) {
@@ -81,19 +82,23 @@ export class StrandAddrService {
     get activeCount() {
         return this.activeStreams;
     }
-    /** Register the strand-addr protocol handler on the control node. */
-    initialize(node) {
-        this.node = node;
+    /**
+     * Register the strand-addr protocol handler on the control node. Rejects when
+     * libp2p refuses the registration (a duplicate handler, a peer-store write
+     * failure); the node reference is kept only once the handler is in place.
+     */
+    async initialize(node) {
         // `runOnLimitedConnection: true` is REQUIRED for the relay path: a NAT'd
         // sibling is reached over a circuit-relay connection, which libp2p marks
         // "limited" (the relay caps its data/duration). Without this the receiver
         // would refuse the inbound stream on exactly the connection the protocol is
         // designed to use (same reasoning as wake; see the relay note on
         // `collectStrandAddrs`).
-        void node.handle(STRAND_ADDR_PROTOCOL, async (rawStream, rawConnection) => {
+        await node.handle(STRAND_ADDR_PROTOCOL, async (rawStream, rawConnection) => {
             const remotePeerId = rawConnection.remotePeer.toString();
             await this.handleStream(rawStream, remotePeerId);
         }, { runOnLimitedConnection: true });
+        this.node = node;
         log('StrandAddrService registered handler: %s', STRAND_ADDR_PROTOCOL);
     }
     /** Unregister the handler and release the node reference. */
@@ -107,58 +112,42 @@ export class StrandAddrService {
     /**
      * Read the inbound request, decide the response, and write it back.
      *
-     * Three hardening layers, all reported as an empty {@link StrandAddrResponse}
-     * rather than a dropped/hung stream: a concurrency cap (over
-     * {@link maxConcurrent}, reply without looking up any address), a read timeout
-     * (a peer that never half-closes is aborted inside {@link readFrame}/
-     * `readStreamToEnd`), and the existing malformed/oversized-frame guard.
+     * Three hardening layers, all reported as an `unavailable`
+     * {@link StrandAddrResponse} rather than a dropped/hung stream: a concurrency cap
+     * (over {@link maxConcurrent}, reply without looking up any address), a read
+     * timeout (a peer that never half-closes is aborted inside {@link readFrame}/
+     * `readStreamToEnd`), and the existing malformed/oversized-frame guard. A
+     * lookup that throws — the membership read failing, say — is `unavailable` too,
+     * never a `refused` or an empty `ok` the asker would wait ten minutes on.
      */
     async handleStream(stream, remotePeerId) {
         log('Incoming strand-addr request from: %s', remotePeerId);
         if (this.activeStreams >= this.maxConcurrent) {
             log('Rejecting strand-addr from %s: %d concurrent streams at cap %d', remotePeerId, this.activeStreams, this.maxConcurrent);
             // The request frame is unread here, so the strand id is unknown — reply
-            // with an empty list under an empty strand id; the client treats any empty
-            // response as "no addrs" and skips this sibling.
-            try {
-                writeFrame(stream, emptyResponse(''));
-            }
-            catch {
-                // Ignore send errors on the reject path.
-            }
-            try {
-                await stream.close();
-            }
-            catch {
-                // Ignore close errors.
-            }
+            // under an empty strand id; the asker retries an `unavailable` sibling soon.
+            await replyAndClose(stream, addrlessResponse('unavailable', ''), 'Strand-addr');
             return;
         }
         this.activeStreams++;
+        try {
+            await replyAndClose(stream, await this.answerStream(stream, remotePeerId), 'Strand-addr');
+        }
+        finally {
+            this.activeStreams--;
+        }
+    }
+    /** Read and decide one inbound request; any failure becomes an `unavailable` response. */
+    async answerStream(stream, remotePeerId) {
         try {
             const request = await readFrame(stream, this.readTimeoutMs);
-            const response = await this.processAddrRequest(request, remotePeerId);
-            writeFrame(stream, response);
+            return await this.processAddrRequest(request, remotePeerId);
         }
         catch (err) {
             log('Error handling strand-addr request from %s: %o', remotePeerId, err);
-            // Malformed/oversized/timed-out request: strand id is unknown, so reply
-            // with an empty list under an empty strand id rather than hanging.
-            try {
-                writeFrame(stream, emptyResponse(''));
-            }
-            catch {
-                // Ignore send errors on the error path.
-            }
-        }
-        finally {
-            this.activeStreams--;
-            try {
-                await stream.close();
-            }
-            catch {
-                // Ignore close errors.
-            }
+            // Malformed/oversized/timed-out request, or a lookup that threw: reply
+            // under an empty strand id rather than hanging.
+            return addrlessResponse('unavailable', '');
         }
     }
     /**
@@ -166,23 +155,25 @@ export class StrandAddrService {
      * decision matrix can be unit-tested directly (mirrors wake's
      * `processWakeRequest`).
      *
-     * - Non-member sender → empty `multiaddrs` (refused), no delegate grant.
+     * - Non-member sender → `refused`, no delegate grant.
      * - Member request carrying a `delegatePeerId` → recorded via
      *   {@link StrandAddrServiceOptions.onDelegateAnnounce} before the lookup.
-     * - Strand not running locally → empty `multiaddrs` (`getStrandMultiaddrs` → `[]`).
-     * - Member + running strand → the strand's live, signaling-first multiaddrs.
+     * - Strand not running locally → `ok` with empty `multiaddrs` (`getStrandMultiaddrs` → `[]`).
+     * - Member + running strand → `ok` with the strand's live, signaling-first multiaddrs.
+     *
+     * A throwing `isMember` propagates; {@link handleStream} answers it `unavailable`.
      */
     async processAddrRequest(request, remotePeerId) {
         // Control-network membership is the v1 authorization: only this party's
         // cadre peers may ask us for a strand address (or announce a delegate).
         if (!(await this.options.isMember(remotePeerId))) {
             log('Refusing strand-addr from non-member %s', remotePeerId);
-            return emptyResponse(request.strandId);
+            return addrlessResponse('refused', request.strandId);
         }
         this.recordDelegateAnnounce(request, remotePeerId);
         const multiaddrs = this.options.getStrandMultiaddrs(request.strandId);
         log('Strand-addr for %s → %d addr(s)', request.strandId, multiaddrs.length);
-        return { strandId: request.strandId, multiaddrs };
+        return { status: 'ok', strandId: request.strandId, multiaddrs };
     }
     /**
      * Validate and forward a member's delegate announcement. A malformed field
@@ -212,13 +203,14 @@ export class StrandAddrService {
 /**
  * Client side: ask each candidate sibling for its live strand-`strandId`
  * multiaddrs and return the **deduplicated union** of every answer, ordered
- * signaling-first.
+ * signaling-first, alongside each sibling's {@link StrandAddrOutcome}.
  *
- * Best-effort per peer: a failed/timed-out/empty sibling is logged and skipped,
- * never fatal — an empty union (no sibling online or running the strand) returns
- * `[]`, which the caller treats as an acceptable seed that self-heals on the next
- * resume/reconcile pass. The local node (`node.peerId`) is excluded so we never
- * RPC ourselves or seed with our own strand address.
+ * Best-effort per peer: a failed/timed-out/empty sibling contributes no address
+ * and never fails the collection — an empty union (no sibling online or running
+ * the strand) is an acceptable seed that self-heals on the next resume/reconcile
+ * pass. `outcomes` is what lets a caller retry the siblings that could not answer
+ * sooner than the ones that answered with nothing. The local node (`node.peerId`)
+ * is excluded so we never RPC ourselves or seed with our own strand address.
  *
  * Dials run concurrently but the union preserves candidate order, so the result
  * is deterministic regardless of which sibling answers first.
@@ -229,48 +221,54 @@ export async function collectStrandAddrs(node, peers, strandId, options = {}) {
         ? { strandId, delegatePeerId: options.delegatePeerId }
         : { strandId };
     const candidates = peers.filter(p => p.peerId !== selfId);
-    // Concurrent dials; `dialOneSibling` swallows per-peer failure into `[]`, so
+    // Concurrent dials; `dialOneSibling` folds per-peer failure into an outcome, so
     // `Promise.all` never rejects and the result array stays in candidate order.
-    const perPeer = await Promise.all(candidates.map(peer => dialOneSibling(node, peer, request, options)));
+    const answers = await Promise.all(candidates.map(async (peer) => ({ peerId: peer.peerId, ...await dialOneSibling(node, peer, request, options) })));
+    const outcomes = new Map();
     // Deduplicated union in candidate order, then signaling-first for a usable
     // dial sequence (relay/`p2p-circuit` ahead of direct addrs).
     const seen = new Set();
     const union = [];
-    for (const addrs of perPeer) {
-        for (const addr of addrs) {
+    for (const { peerId, outcome, multiaddrs } of answers) {
+        outcomes.set(peerId, outcome);
+        for (const addr of multiaddrs) {
             if (!seen.has(addr)) {
                 seen.add(addr);
                 union.push(addr);
             }
         }
     }
-    return orderSignalingFirst(union);
+    return { addrs: orderSignalingFirst(union), outcomes };
 }
 /**
- * Ask one sibling for its strand address, returning its multiaddrs or `[]` on any
- * failure. Tries each dial target in order (peerId first to reuse an open control
- * connection, then explicit addrs) until one answers; a total failure is logged
- * and folded to `[]` so a single dead sibling never aborts the collection.
+ * Ask one sibling for its strand address. Tries each dial target in order (peerId
+ * first to reuse an open control connection, then explicit addrs) until one
+ * produces a well-formed reply, and reports that reply's outcome; a total failure
+ * is `unreachable`, so a single dead sibling never aborts the collection. Never
+ * throws.
+ *
+ * A reply of any status ends the loop: every target reaches the same responder,
+ * so asking it again by another address would get the same answer.
  *
- * A total failure logs ONE line naming every target and its cause. `[]` alone
- * cannot tell the caller "this sibling was unreachable" apart from "this sibling
- * answered and has no strand address" — and per-target lines scattered through a
- * concurrent fan-out do not reassemble into that answer either. The return
- * contract is unchanged: best-effort `[]`, never a throw.
+ * A total failure logs ONE line naming every target and its cause, because
+ * per-target lines scattered through a concurrent fan-out do not reassemble into
+ * "this sibling was unreachable".
  *
- * NOTE: cost is (targets × `timeoutMs`) with no whole-sibling budget, the same
- * shape `dialWake` bounds with `DEFAULT_WAKE_DIAL_BUDGET_MS`. Fine today —
- * `dialTargets` yields the peerId plus whatever `resolvePeerAddrs` returned,
- * which for a cadre device is one or two addresses. If a sibling's record ever
- * carries a long address list, give this the same whole-sibling budget.
+ * NOTE: cost is (targets × `timeoutMs`, 23 s each at the default declared link) with
+ * no whole-sibling budget, the same shape `dialWake` bounds with
+ * `DEFAULT_WAKE_DIAL_BUDGET_MS`. Siblings are asked concurrently, so a collection costs
+ * its slowest sibling, not the sum. Fine today — `dialTargets` yields the peerId plus
+ * whatever `resolvePeerAddrs` returned, which for a cadre device is one or two
+ * addresses. If a sibling's record ever carries a long address list, give this the same
+ * whole-sibling budget.
  */
 async function dialOneSibling(node, peer, request, options) {
     const protocolId = options.protocolId ?? STRAND_ADDR_PROTOCOL;
-    const timeoutMs = options.timeoutMs ?? DEFAULT_ADDR_TIMEOUT_MS;
+    const timeoutMs = attemptTimeoutMs(options);
     const targets = dialTargets(peer);
     if (targets.length === 0) {
         log('No dial target for sibling %s', peer.peerId);
-        return [];
+        return { outcome: 'unreachable', multiaddrs: [] };
     }
     const failures = [];
     for (const target of targets) {
@@ -278,7 +276,7 @@ async function dialOneSibling(node, peer, request, options) {
             // One deadline per attempt: its signal aborts the in-flight dialProtocol and
             // resets the live stream, so neither the connect nor the response-read leaks.
             const response = await withDeadline(timeoutMs, `Strand-addr dial ${peer.peerId}`, (signal) => sendStrandAddr(node, target, protocolId, request, timeoutMs, signal));
-            return response.multiaddrs;
+            return siblingAnswer(response);
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
@@ -287,7 +285,35 @@ async function dialOneSibling(node, peer, request, options) {
         }
     }
     log('Strand-addr dial to %s failed on all %d target(s), contributing no addrs: %s', peer.peerId, failures.length, failures.join('; '));
-    return [];
+    return { outcome: 'unreachable', multiaddrs: [] };
+}
+/**
+ * Deadline for ONE attempt to ask a sibling — dial, request, response — unless the caller set
+ * its own: `relayedRequestBudgetMs` at the declared link (23 s at the default).
+ *
+ * An attempt is either a dial by peer id, which normally reuses an open control connection
+ * (`CIRCUIT_REQUEST_ROUND_TRIPS`, 2), or the fallback to the sibling's control addresses, a
+ * fresh and possibly relayed dial. One deadline covers both, so it is sized for the fallback.
+ *
+ * NOTE: the receiver's membership check (two live control reads) runs inside this deadline and
+ * is not counted. In steady state those reads touch only held blocks and do not consult the
+ * cohort. If a wake or address request is seen timing out while the receiver's membership read
+ * is consulting, count one membership decision in this deadline or answer the check from the
+ * materialized authorized-peer snapshot. See docs/cadre-consistency.md → "Deadlines Over
+ * Optimystic's Reads and Commits".
+ */
+function attemptTimeoutMs(options) {
+    return options.timeoutMs ?? relayedRequestBudgetMs(options.linkRoundTripMs);
+}
+/** Map a validated reply to its outcome; only an `ok` reply contributes addresses. */
+function siblingAnswer(response) {
+    if (response.status !== 'ok') {
+        return { outcome: response.status, multiaddrs: [] };
+    }
+    return {
+        outcome: response.multiaddrs.length > 0 ? 'answered' : 'empty',
+        multiaddrs: response.multiaddrs
+    };
 }
 /**
  * Dial targets for a sibling, peerId first. Dialing by peerId lets libp2p reuse
@@ -329,7 +355,29 @@ async function sendStrandAddr(node, target, protocolId, request, timeoutMs, sign
     // and is the whole point of dialing over the relay.
     const rawStream = await node.dialProtocol(target, protocolId, { runOnLimitedConnection: true, signal });
     const response = await exchangeFrame(rawStream, signal, request, (stream) => readFrame(stream, timeoutMs), 'Strand-addr dial aborted by timeout');
-    log('Strand-addr response: %d addr(s) for %s', response.multiaddrs.length, response.strandId);
+    if (!isStrandAddrResponse(response)) {
+        throw new Error('Malformed strand-addr response');
+    }
+    log('Strand-addr response: %s, %d addr(s) for %s', response.status, response.multiaddrs.length, response.strandId);
     return response;
 }
+const STRAND_ADDR_STATUSES = new Set(['ok', 'unavailable', 'refused']);
+/**
+ * Shape check on a decoded reply: the responder is another machine, so a reply
+ * missing its status (an older responder, or a buggy one) or carrying anything but
+ * strings in `multiaddrs` is a failed exchange, not an answer.
+ *
+ * Deliberately not `sanitizeStrandAddrs` (strand-formation-protocol.ts): that drops
+ * bad entries and caps the list at 16, which suits a cross-party formation result
+ * but would silently truncate a sibling's full address list here.
+ */
+function isStrandAddrResponse(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { status, strandId, multiaddrs } = value;
+    return typeof status === 'string' && STRAND_ADDR_STATUSES.has(status)
+        && typeof strandId === 'string'
+        && Array.isArray(multiaddrs) && multiaddrs.every((addr) => typeof addr === 'string');
+}
 //# sourceMappingURL=strand-addr-protocol.js.map

package/dist/strand-addr-protocol.js.map

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

package/dist/strand-database.d.ts

@@ -6,8 +6,12 @@ import type { SAppConfig } from './types.js';
 export interface StrandDatabaseConfig {
     /** The strand ID */
     strandId: string;
-    /** sApp configuration containing the schema */
-    sAppConfig: SAppConfig;
+    /**
+     * sApp configuration containing the schema. Absent for a storage replica — a strand
+     * this node stores and serves without the app installed: only the `Strand` membership
+     * schema is applied, and such a database can never found (see {@link founderSApp}).
+     */
+    sAppConfig?: SAppConfig;
     /** Libp2p node for the strand network */
     libp2pNode: Libp2p;
     /** Coordinated repo from the libp2p node */
@@ -81,6 +85,12 @@ export declare class StrandDatabase {
      * no keypair (Header only). Idempotent — see {@link bootstrapFounderMembership}.
      */
     private bootstrapFounder;
+    /**
+     * The sApp a founder bootstrap records in the `Strand.Header`. Throws for a storage
+     * replica (no sApp config): its Header's sApp columns would have nothing to say.
+     * `CadreNode` always launches a replica as a joiner, so this guards a future caller.
+     */
+    private founderSApp;
     /**
      * Derive the founding keypair for a closed strand from the party's own
      * `partyMemberPrivateKey`, failing loudly when the key is absent (a closed strand
@@ -104,6 +114,14 @@ export declare class StrandDatabase {
      *   exist: it is the identity this instance launched under.
      */
     ensureFounderBootstrap(partyMemberPrivateKey?: string): Promise<void>;
+    /**
+     * Give a live storage replica the app's schema: apply `App` to the already-composed
+     * database — same libp2p node, same store, so the new tables read the blocks this node
+     * already holds — and record the sApp, so a later {@link ensureFounderBootstrap} has it
+     * for the `Header`. Idempotent: the apply is a declarative diff, so re-applying the same
+     * schema emits nothing. A failed apply records nothing.
+     */
+    attachAppSchema(sAppConfig: SAppConfig): Promise<void>;
     /**
      * Get the underlying database for queries
      */