@serfab/cadre-core 0.7.1 → 0.9.0

package/dist/strand-addr-protocol.js

@@ -0,0 +1,313 @@
+/**
+ * Control-network strand-address RPC.
+ *
+ * A strand runs as its own libp2p node (`strand-<id>`, random port), separate
+ * from the control node (`control-<partyId>`) even though both share the same
+ * peerId. To seed a strand's mesh, a node needs a sibling's **strand-network**
+ * address — but `CadrePeer.Multiaddr` only stores the **control** node's
+ * addresses. This protocol resolves the strand address on demand: a node asks
+ * its connected co-cadre siblings "what are your live strand-`X` multiaddrs?" and
+ * uses the union of their answers as the seed.
+ *
+ * Modeled directly on `strand-wake-protocol.ts`: a dedicated libp2p protocol id,
+ * 4-byte big-endian length-prefixed JSON frames, `node.handle` for the receiver,
+ * `node.dialProtocol` for the client, and the shared `ControlStream` primitives
+ * from `control-stream.ts`. The exchange is a single request → single response on
+ * one stream, so each side reads to EOF (under a read timeout) and decodes one
+ * frame via the shared {@link decodeLengthPrefixedFrame} guard.
+ *
+ * **Authorization (v1):** the control network is single-party — only this party's
+ * cadre peers connect (schema-gated `CadrePeer`). Like wake, the receiver gates
+ * on cadre membership (via the injected `isMember`) and requires no further
+ * signature; a non-member is refused with an empty address list. This is
+ * defense-in-depth (the control mesh already restricts membership) kept for
+ * parity with wake. Cross-party strand bootstrap is a different mechanism
+ * (strand formation / `MemberPeer`) and is out of scope here.
+ */
+import debug from 'debug';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
+import { orderSignalingFirst } from './peer-record.js';
+import { writeFrame, withTimeout, readStreamToEnd } from './control-stream.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';
+/**
+ * Maximum strand-addr frame size. Responses are tiny (a strand id + a few
+ * multiaddrs), so this is a defensive cap — far below the 1MB seed ceiling —
+ * 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). */
+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;
+/**
+ * Read a libp2p stream to EOF and decode the single length-prefixed JSON frame
+ * it carries. Bounded by `timeoutMs` (a never-half-closing peer is aborted, not
+ * awaited forever) and capped at {@link MAX_ADDR_SIZE}, reusing the shared
+ * {@link decodeLengthPrefixedFrame} guard for the prefix/length checks.
+ */
+async function readFrame(stream, timeoutMs) {
+    const data = await readStreamToEnd(stream, { maxBytes: MAX_ADDR_SIZE, timeoutMs, label: 'Strand-addr' });
+    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: [] };
+}
+/**
+ * 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).
+ */
+export class StrandAddrService {
+    constructor(options) {
+        this.node = null;
+        /** In-flight inbound strand-addr streams, used to enforce {@link maxConcurrent}. */
+        this.activeStreams = 0;
+        this.options = options;
+        this.readTimeoutMs = options.readTimeoutMs ?? DEFAULT_ADDR_READ_TIMEOUT_MS;
+        this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT_ADDRS;
+    }
+    /** Number of in-flight inbound strand-addr streams. */
+    get activeCount() {
+        return this.activeStreams;
+    }
+    /** Register the strand-addr protocol handler on the control node. */
+    initialize(node) {
+        this.node = 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) => {
+            const remotePeerId = rawConnection.remotePeer.toString();
+            await this.handleStream(rawStream, remotePeerId);
+        }, { runOnLimitedConnection: true });
+        log('StrandAddrService registered handler: %s', STRAND_ADDR_PROTOCOL);
+    }
+    /** Unregister the handler and release the node reference. */
+    async shutdown() {
+        if (this.node) {
+            await this.node.unhandle(STRAND_ADDR_PROTOCOL);
+            this.node = null;
+            log('StrandAddrService shutdown');
+        }
+    }
+    /**
+     * 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.
+     */
+    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.
+            }
+            return;
+        }
+        this.activeStreams++;
+        try {
+            const request = await readFrame(stream, this.readTimeoutMs);
+            const response = await this.processAddrRequest(request, remotePeerId);
+            writeFrame(stream, response);
+        }
+        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.
+            }
+        }
+    }
+    /**
+     * 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).
+     * - Strand not running locally → empty `multiaddrs` (`getStrandMultiaddrs` → `[]`).
+     * - Member + running strand → the strand's live, signaling-first multiaddrs.
+     */
+    async processAddrRequest(request, remotePeerId) {
+        // Control-network membership is the v1 authorization: only this party's
+        // cadre peers may ask us for a strand address.
+        if (!(await this.options.isMember(remotePeerId))) {
+            log('Refusing strand-addr from non-member %s', remotePeerId);
+            return emptyResponse(request.strandId);
+        }
+        const multiaddrs = this.options.getStrandMultiaddrs(request.strandId);
+        log('Strand-addr for %s → %d addr(s)', request.strandId, multiaddrs.length);
+        return { strandId: request.strandId, multiaddrs };
+    }
+}
+/**
+ * Client side: ask each candidate sibling for its live strand-`strandId`
+ * multiaddrs and return the **deduplicated union** of every answer, ordered
+ * signaling-first.
+ *
+ * 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.
+ *
+ * Dials run concurrently but the union preserves candidate order, so the result
+ * is deterministic regardless of which sibling answers first.
+ */
+export async function collectStrandAddrs(node, peers, strandId, options = {}) {
+    const selfId = node.peerId.toString();
+    const request = { strandId };
+    const candidates = peers.filter(p => p.peerId !== selfId);
+    // Concurrent dials; `dialOneSibling` swallows per-peer failure into `[]`, 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)));
+    // 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) {
+            if (!seen.has(addr)) {
+                seen.add(addr);
+                union.push(addr);
+            }
+        }
+    }
+    return orderSignalingFirst(union);
+}
+/**
+ * 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.
+ */
+async function dialOneSibling(node, peer, request, options) {
+    const protocolId = options.protocolId ?? STRAND_ADDR_PROTOCOL;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_ADDR_TIMEOUT_MS;
+    const targets = dialTargets(peer);
+    if (targets.length === 0) {
+        log('No dial target for sibling %s', peer.peerId);
+        return [];
+    }
+    for (const target of targets) {
+        // One controller per attempt: on timeout, `withTimeout`'s `onTimeout` aborts
+        // it, which aborts the in-flight dialProtocol (via the dial `signal`) and the
+        // live stream — so neither the connect nor the unbounded response-read leaks.
+        const controller = new AbortController();
+        try {
+            const response = await withTimeout(timeoutMs, `Strand-addr dial ${peer.peerId}`, () => sendStrandAddr(node, target, protocolId, request, timeoutMs, controller.signal), () => controller.abort());
+            return response.multiaddrs;
+        }
+        catch (err) {
+            log('Strand-addr dial to %s via %s failed: %o', peer.peerId, describeTarget(target), err);
+        }
+    }
+    return [];
+}
+/**
+ * Dial targets for a sibling, peerId first. Dialing by peerId lets libp2p reuse
+ * an already-open control connection (the common case — the wiring ticket passes
+ * connected siblings); the explicit control addrs are a fallback for when no
+ * connection is open. An unparsable peerId is skipped (rely on addrs).
+ */
+function dialTargets(peer) {
+    const targets = [];
+    try {
+        targets.push(peerIdFromString(peer.peerId));
+    }
+    catch (err) {
+        log('Unparsable peer id %s, falling back to addrs: %o', peer.peerId, err);
+    }
+    if (peer.addrs) {
+        targets.push(...peer.addrs);
+    }
+    return targets;
+}
+/** Short label for a dial target (peerId or multiaddr) for logging. */
+function describeTarget(target) {
+    return target.toString();
+}
+/**
+ * Open one stream to a target, send the request, half-close, and read the
+ * response.
+ *
+ * `signal` is the per-attempt abort signal from {@link dialOneSibling}: it is
+ * passed to `dialProtocol` so a timeout during connect aborts the dial, and once
+ * the stream is open an abort listener resets the live stream — releasing the
+ * otherwise unbounded response-read. `readFrame` still applies `timeoutMs` as a
+ * backstop for the case where an abort does not propagate (e.g. a stream double
+ * whose `abort()` is a no-op).
+ */
+async function sendStrandAddr(node, target, protocolId, request, timeoutMs, signal) {
+    // `runOnLimitedConnection: true`: the sibling may be reachable only over a
+    // circuit-relay connection (the signaling-first addr), which libp2p marks
+    // "limited". The exchange is a single tiny request→response well within the
+    // relay's data/duration cap, so opening it on the limited connection is safe
+    // and is the whole point of dialing over the relay.
+    const rawStream = await node.dialProtocol(target, protocolId, { runOnLimitedConnection: true, signal });
+    const stream = rawStream;
+    const abortErr = new Error('Strand-addr dial aborted by timeout');
+    const onAbort = () => stream.abort(abortErr);
+    // If the timeout already fired during connect, release the freshly-opened stream now.
+    if (signal.aborted) {
+        onAbort();
+        throw abortErr;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        writeFrame(stream, request);
+        // close() half-closes the write end (EOF) while the read end stays open for
+        // the response — the same libp2p 3.x pattern as wake/seed delivery.
+        await stream.close();
+        const response = await readFrame(stream, timeoutMs);
+        log('Strand-addr response: %d addr(s) for %s', response.multiaddrs.length, response.strandId);
+        return response;
+    }
+    catch (err) {
+        stream.abort(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+//# sourceMappingURL=strand-addr-protocol.js.map

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

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

package/dist/strand-cohort.d.ts

@@ -0,0 +1,54 @@
+import type { StrandMode } from './types.js';
+/**
+ * A single CadrePeer membership row, as returned by
+ * `ControlDatabase.queryCadrePeers()`.
+ */
+export interface CohortPeerRow {
+    peerId: string;
+    /** Comma-joined list of multiaddr strings; `''` when no addrs were recorded. */
+    multiaddr: string | null;
+}
+/**
+ * Cohort-derived discovery seed for a strand's libp2p node. `bootstrapNodes`
+ * here are **strand-network** addresses resolved on demand from co-cadre
+ * siblings (see `collectStrandAddrs` / `STRAND_ADDR_PROTOCOL`), NOT the control
+ * addresses stored in `CadrePeer.Multiaddr`.
+ */
+export interface CohortSeed {
+    /** Dialable strand-network multiaddr strings for cohort peers other than self (deduplicated). */
+    bootstrapNodes: string[];
+    /** True when at least one CadrePeer row other than self exists (even if it has no resolvable strand addr). */
+    hasOtherPeers: boolean;
+}
+/**
+ * Membership-only view of a strand's cohort, derived from the control network's
+ * CadrePeer rows. The bootstrap addresses themselves are resolved separately
+ * (over the strand-addr RPC) from these peerIds, never from the rows' addr field.
+ */
+export interface CohortMembers {
+    /** PeerIds of cohort members other than self — the strand-addr RPC fan-out targets (deduplicated, in row order). */
+    otherPeerIds: string[];
+    /** True when at least one CadrePeer row other than self exists (even if it has no resolvable strand addr). */
+    hasOtherPeers: boolean;
+}
+/**
+ * Derive the membership view of a strand's cohort from the control network's
+ * CadrePeer rows: the peerIds of members other than `selfPeerId` (the strand-addr
+ * RPC fan-out targets) and whether any other member exists at all.
+ *
+ * Deliberately does NOT read `CadrePeer.Multiaddr` — that field carries each
+ * node's *control*-network address, which must not seed the *strand* mesh
+ * (dialing it reaches the remote's control instance, not its strand instance).
+ * The strand-network bootstrap addresses are resolved on demand over the control
+ * mesh from these peerIds. `hasOtherPeers` reflects membership presence, NOT
+ * dialability, so a cohort whose strand addrs are not yet resolvable still
+ * selects `networked` mode.
+ */
+export declare function deriveCohortMembers(peers: CohortPeerRow[], selfPeerId?: string): CohortMembers;
+/**
+ * Choose the strand mode. An explicit mode (from `addStrand`) always wins. When
+ * omitted (the `handleStrandAdded` discovery path, or an `addStrand` caller that
+ * leaves it unset), infer: `bootstrap` for a solo/first node (no other peers),
+ * `networked` once the cohort has other members.
+ */
+export declare function selectStrandMode(explicitMode: StrandMode | undefined, hasOtherPeers: boolean): StrandMode;

package/dist/strand-cohort.js

@@ -0,0 +1,38 @@
+/**
+ * Derive the membership view of a strand's cohort from the control network's
+ * CadrePeer rows: the peerIds of members other than `selfPeerId` (the strand-addr
+ * RPC fan-out targets) and whether any other member exists at all.
+ *
+ * Deliberately does NOT read `CadrePeer.Multiaddr` — that field carries each
+ * node's *control*-network address, which must not seed the *strand* mesh
+ * (dialing it reaches the remote's control instance, not its strand instance).
+ * The strand-network bootstrap addresses are resolved on demand over the control
+ * mesh from these peerIds. `hasOtherPeers` reflects membership presence, NOT
+ * dialability, so a cohort whose strand addrs are not yet resolvable still
+ * selects `networked` mode.
+ */
+export function deriveCohortMembers(peers, selfPeerId) {
+    const otherPeerIds = [];
+    const seen = new Set();
+    for (const peer of peers) {
+        if (selfPeerId !== undefined && peer.peerId === selfPeerId) {
+            continue;
+        }
+        if (seen.has(peer.peerId)) {
+            continue;
+        }
+        seen.add(peer.peerId);
+        otherPeerIds.push(peer.peerId);
+    }
+    return { otherPeerIds, hasOtherPeers: otherPeerIds.length > 0 };
+}
+/**
+ * Choose the strand mode. An explicit mode (from `addStrand`) always wins. When
+ * omitted (the `handleStrandAdded` discovery path, or an `addStrand` caller that
+ * leaves it unset), infer: `bootstrap` for a solo/first node (no other peers),
+ * `networked` once the cohort has other members.
+ */
+export function selectStrandMode(explicitMode, hasOtherPeers) {
+    return explicitMode ?? (hasOtherPeers ? 'networked' : 'bootstrap');
+}
+//# sourceMappingURL=strand-cohort.js.map

package/dist/strand-cohort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-cohort.js","sourceRoot":"","sources":["../src/strand-cohort.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAsB,EAAE,UAAmB;IAC7E,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,YAAoC,EAAE,aAAsB;IAC3F,OAAO,YAAY,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;AACrE,CAAC"}

package/dist/strand-database.d.ts

@@ -26,28 +26,76 @@ export interface StrandDatabaseConfig {
      * across the two consumers.
      */
     rawStorage?: IRawStorage;
+    /**
+     * Strand type (`'o'` open / `'c'` closed) from the control-network strand row.
+     * Drives the founder bootstrap: open strands get a `Header` only; closed strands
+     * also get the founding `Member`+`Manager`.
+     */
+    strandType: 'o' | 'c';
+    /**
+     * The closed-strand `MemberPrivateKey` (base64 protobuf) from the strand row.
+     * Required when `founder` is true and `strandType` is `'c'` — it derives the
+     * founding `Member.Key`/`Manager.MemberKey`. Absent for open strands.
+     */
+    memberPrivateKey?: string;
+    /**
+     * Whether this node founds the strand. When true, {@link initialize} runs the
+     * one-time founder membership bootstrap after the schema is applied. Joiners
+     * leave this false and write nothing (rows arrive via sync). Defaults to false.
+     */
+    founder?: boolean;
 }
 /**
- * StrandDatabase manages the sApp schema for a strand using Quereus with Optimystic backend.
- * Each strand instance has its own isolated database with the sApp's schema applied.
+ * StrandDatabase manages the sApp schema for a strand using Quereus with the
+ * Optimystic backend. Each strand instance has its own isolated database with
+ * the sApp's schema applied.
+ *
+ * This class owns the `Database` lifecycle (creation, `getDatabase()`, `close()`)
+ * but delegates the actual SQL-surface composition — plugin registration, node
+ * wiring, catalog hydration, schema apply — to `connectToStrand` from
+ * `@serfab/quereus-plugin-sereus`, the single shared composition. The libp2p
+ * node is injected here, so `connectToStrand` never *creates* the node;
+ * `StrandInstanceManager` owns the node lifecycle. (The strand connection's
+ * `shutdown` still stops the injected node via the collection factory, so the
+ * manager's own `node.stop()` is an idempotent second stop — see `close()`.)
  */
 export declare class StrandDatabase {
     private db;
-    private collectionFactory;
+    private shutdownStrand;
     private readonly config;
     private initialized;
     constructor(config: StrandDatabaseConfig);
     /**
-     * Initialize the database - register plugins and execute sApp schema
+     * Initialize the database — create the `Database` and delegate the strand
+     * SQL-surface composition (plugins, node wiring, hydrate, schema apply) to
+     * `connectToStrand` with the injected libp2p node.
      */
     initialize(): Promise<void>;
-    private executeSchema;
+    /**
+     * Run the founder membership bootstrap against the freshly-composed strand DB.
+     *
+     * Derives the founding keypair from the closed-strand `memberPrivateKey` (the
+     * `Member.Key`/`Manager.MemberKey` are its public key); a closed strand with no
+     * `memberPrivateKey` throws, because it could never seat a founding manager.
+     * Open strands derive no keypair (Header only). Idempotent — see
+     * {@link bootstrapFounderMembership}.
+     */
+    private bootstrapFounder;
+    /**
+     * Derive the founding keypair for a closed strand from its `memberPrivateKey`,
+     * failing loudly when the key is absent (a closed strand with no founding
+     * Manager can never admit anyone).
+     */
+    private deriveFounderKeyPair;
     /**
      * Get the underlying database for queries
      */
     getDatabase(): Database;
     /**
-     * Close the database and cleanup resources
+     * Close the database and cleanup resources. Runs the strand-connection
+     * shutdown (collection-factory teardown, which also stops the injected node),
+     * then closes the `Database`. `StrandInstanceManager.releaseRuntime` issues a
+     * further idempotent `node.stop()` after this returns.
      */
     close(): Promise<void>;
     private ensureInitialized;