@serfab/cadre-core 0.10.0 → 0.11.0

package/dist/types.d.ts

@@ -82,8 +82,28 @@ export interface HibernationTimeouts {
  */
 export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts>;
 /**
- * Storage provider type - either an IRawStorage instance or a factory function.
+ * Storage provider - either an `IRawStorage` instance or a factory function.
  * Factory functions are useful for creating strand-specific storage instances.
+ *
+ * **Called once per scope per runtime lifetime.** The scopes are the literal string
+ * `'control'` (once per `CadreNode.start()`) and each strand id (once per
+ * `startStrand`). Hibernation — `quiesceStrand` then `resumeStrand` — reuses the
+ * store already resolved for that strand and does NOT re-enter this callback.
+ *
+ * It IS re-entered for a scope after that scope's runtime has stopped
+ * (`stopStrand`, or a `stop()` then `start()` cycle on one `CadreNode`), so it must
+ * be able to hand back a store over the same durable backend a second time. A
+ * factory may mint a fresh object per call; it must not *need* to.
+ *
+ * cadre-core disposes only its own cache wrapper — it never closes the store you
+ * returned. Closing the underlying handle stays the embedder's job.
+ *
+ * **Prefer the factory form for any persistent backend.** One instance handed to
+ * every scope also shares ONE cache wrapper (`wrapStorageWithCache` memoizes per
+ * inner instance), and no scope solely owns it — so the first scope to stop retires
+ * the wrapper the still-running scopes are reading through. See
+ * `tickets/backlog/debt-storage-cache-wrap-unrefcounted.md`; an in-memory store is
+ * unaffected, since it is never wrapped.
  */
 export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorage);
 /**
@@ -92,6 +112,7 @@ export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorag
 export interface StorageConfig {
     /**
      * Storage provider - either an IRawStorage instance or a factory function.
+     * See {@link RawStorageProvider} for how often cadre-core calls it.
      *
      * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
      * ```typescript
@@ -212,9 +233,10 @@ export interface NetworkConfig {
      * Tuning for the proactive control-cohort dial routine
      * ({@link CadreNode.reconcileControlCohort}), which keeps a party's control
      * nodes connected so the `CadreControl` collections form a replicating cohort.
-     * Both fields are optional; omit for the defaults
+     * Every field is optional; omit for the defaults
      * ({@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE} /
-     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}).
+     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS} /
+     * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} / `STRAND_PEER_ADDR_REFRESH_MS`).
      */
     controlCohort?: {
         /**
@@ -228,6 +250,20 @@ export interface NetworkConfig {
          * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}.
          */
         reconcileMs?: number;
+        /**
+         * Budget for ONE sibling's proactive dial, in ms. Bounds a pass at
+         * (dialed siblings) × this, instead of leaving it to each address's own
+         * libp2p attempt timeout multiplied by address fan-out and relay hops.
+         * Defaults to {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}.
+         */
+        dialTimeoutMs?: number;
+        /**
+         * How often each running strand re-resolves its siblings' strand-network
+         * addresses into its own libp2p address book — a step of the reconcile pass,
+         * on its own much longer throttle. Defaults to `STRAND_PEER_ADDR_REFRESH_MS`
+         * (10 min); must stay well under the peerStore's one-hour address expiry.
+         */
+        strandAddrRefreshMs?: number;
     };
 }
 /**
@@ -475,13 +511,6 @@ export interface StrandInstance {
     strandId: string;
     status: StrandStatus;
     sAppInfo?: SAppInfo;
-    /**
-     * The lifecycle mode this instance's runtime was built with — `bootstrap`
-     * (purely local transactor) or `networked` (cluster transactor). Refreshed on
-     * every runtime (re)build, so a resume that shifts `bootstrap → networked`
-     * updates it. Read-only reporting; drives no behavior.
-     */
-    mode: StrandMode;
     /** The libp2p node for this strand (only when active/idle) */
     libp2pNode?: Libp2p;
     /** The Quereus database for this strand (only when active/idle) */
@@ -549,20 +578,6 @@ export interface SAppConfig {
     /** Latency hint for hibernation behavior (optional, defaults to config) */
     latencyHint?: LatencyHint;
 }
-/**
- * Lifecycle mode for a strand.
- *
- * - `bootstrap`: newly created locally; no remote peers exist for this strand yet.
- *   Schema apply and data operations route through a local (non-network) transactor
- *   so a solo node can fully initialize without any peer round trips.
- * - `networked`: strand has (or is expected to have) remote peers. Operations route
- *   through the network transactor.
- *
- * Transition `bootstrap -> networked` happens at first remote-peer enrollment for
- * the strand; because the transactor is fixed at plugin registration time, the
- * transition requires stopping and restarting the strand.
- */
-export type StrandMode = 'bootstrap' | 'networked';
 /**
  * Full strand configuration when adding a strand via the API
  */
@@ -571,13 +586,6 @@ export interface StrandConfig {
     strandRow: StrandRow;
     /** sApp configuration provided by the hosting application */
     sAppConfig: SAppConfig;
-    /**
-     * Lifecycle mode for this strand instance. When omitted, CadreNode infers the
-     * mode from cohort membership (`bootstrap` for a solo/first node with no other
-     * `CadrePeer` rows, `networked` once the cohort has other members). An explicit
-     * value always wins.
-     */
-    mode?: StrandMode;
     /**
      * Whether THIS node is the strand's founder — the party that provisioned and
      * published the strand (the responder in formation, the creator in host/solo

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA2KF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;GAWG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA+MF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;GAWG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -67,6 +67,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@libp2p/webrtc": "6.0.14",
     "@libp2p/websockets": "^10.1.3",
+    "@optimystic/db-p2p-storage-fs": "^0.24.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -79,12 +80,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@optimystic/db-core": "^0.22.0",
-    "@optimystic/db-p2p": "^0.22.0",
-    "@optimystic/quereus-plugin-crypto": "^0.22.0",
-    "@optimystic/quereus-plugin-optimystic": "^0.22.0",
-    "@quereus/quereus": "^4.10.0",
-    "@serfab/quereus-plugin-sereus": "^0.10.0",
+    "@optimystic/db-core": "^0.24.0",
+    "@optimystic/db-p2p": "^0.24.0",
+    "@optimystic/quereus-plugin-crypto": "^0.24.0",
+    "@optimystic/quereus-plugin-optimystic": "^0.24.0",
+    "@quereus/quereus": "^4.14.0",
+    "@serfab/quereus-plugin-sereus": "^0.11.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"

package/src/arachnode-stub.ts

@@ -1,159 +1,159 @@
-import debug from 'debug';
-import type { NodeProfile, ArachnodeConfig } from './types.js';
-
-const log = debug('sereus:cadre:arachnode');
-
-/**
- * Ring configuration for a storage node
- */
-export interface RingConfig {
-  /** Ring number (0 = full keyspace, higher = more partitions) */
-  ring: number;
-  /** Partition within the ring (depends on ring level) */
-  partition: number;
-  /** Keyspace range this node is responsible for */
-  keyspaceStart: Uint8Array;
-  keyspaceEnd: Uint8Array;
-}
-
-/**
- * Stub implementation of Arachnode ring participation.
- * 
- * Arachnode uses a concentric ring system where:
- * - Ring Zulu (transaction ring): All nodes participate for transaction verification
- * - Storage rings (0, 1, 2, 3...): Nodes join based on their storage capacity
- *   - Ring 0: Full keyspace (requires most storage)
- *   - Ring 1: 2 partitions
- *   - Ring 2: 4 partitions
- *   - Ring 3: 8 partitions
- *   - etc.
- * 
- * This is a stub that will be replaced when arachnode is fully implemented.
- */
-export class ArachnodeStub {
-  private readonly profile: NodeProfile;
-  private readonly config: ArachnodeConfig;
-  private ringConfig?: RingConfig;
-  private running = false;
-
-  constructor(profile: NodeProfile, config: ArachnodeConfig) {
-    this.profile = profile;
-    this.config = config;
-    log('ArachnodeStub created for profile=%s, config=%o', profile, config);
-  }
-
-  /**
-   * Start participating in rings
-   */
-  async start(): Promise<void> {
-    if (this.running) return;
-    this.running = true;
-
-    if (this.config.enableRingZulu) {
-      log('Joining Ring Zulu (transaction ring)');
-      // Stub: In real implementation, would register with transaction verification network
-    }
-
-    // Storage nodes join storage rings
-    if (this.profile === 'storage' && this.config.storageRing) {
-      const { ring, partition = 0 } = this.config.storageRing;
-      
-      log('Joining storage ring %d, partition %d', ring, partition);
-      
-      // Calculate keyspace range for this partition
-      // Stub: Using placeholder keyspace calculation
-      this.ringConfig = {
-        ring,
-        partition,
-        keyspaceStart: this.calculateKeyspaceStart(ring, partition),
-        keyspaceEnd: this.calculateKeyspaceEnd(ring, partition)
-      };
-      
-      // Stub: In real implementation, would:
-      // 1. Register with the storage ring
-      // 2. Begin accepting block storage requests for our keyspace
-      // 3. Participate in replication with other ring members
-    }
-
-    log('ArachnodeStub started');
-  }
-
-  /**
-   * Stop participating in rings
-   */
-  async stop(): Promise<void> {
-    if (!this.running) return;
-    this.running = false;
-
-    if (this.ringConfig) {
-      log('Leaving storage ring %d, partition %d', 
-          this.ringConfig.ring, this.ringConfig.partition);
-      // Stub: In real implementation, would gracefully leave the ring
-      this.ringConfig = undefined;
-    }
-
-    if (this.config.enableRingZulu) {
-      log('Leaving Ring Zulu');
-      // Stub: In real implementation, would leave transaction ring
-    }
-
-    log('ArachnodeStub stopped');
-  }
-
-  /**
-   * Get current ring configuration
-   */
-  getRingConfig(): RingConfig | undefined {
-    return this.ringConfig;
-  }
-
-  /**
-   * Check if participating in Ring Zulu
-   */
-  isInRingZulu(): boolean {
-    return this.running && this.config.enableRingZulu;
-  }
-
-  /**
-   * Check if participating in a storage ring
-   */
-  isInStorageRing(): boolean {
-    return this.running && this.ringConfig !== undefined;
-  }
-
-  // Stub keyspace calculations
-  private calculateKeyspaceStart(ring: number, partition: number): Uint8Array {
-    // Stub: Real implementation would calculate based on ring partition scheme
-    const numPartitions = Math.pow(2, ring);
-    const partitionSize = 256 / numPartitions;
-    const start = new Uint8Array(32);
-    start[0] = Math.floor(partition * partitionSize);
-    return start;
-  }
-
-  private calculateKeyspaceEnd(ring: number, partition: number): Uint8Array {
-    // Stub: Real implementation would calculate based on ring partition scheme
-    const numPartitions = Math.pow(2, ring);
-    const partitionSize = 256 / numPartitions;
-    const end = new Uint8Array(32);
-    end[0] = Math.floor((partition + 1) * partitionSize) - 1;
-    end.fill(0xFF, 1); // Fill rest with max values
-    return end;
-  }
-}
-
-/**
- * Create an arachnode instance for a strand
- */
-export function createArachnodeStub(
-  profile: NodeProfile, 
-  config?: Partial<ArachnodeConfig>
-): ArachnodeStub {
-  const fullConfig: ArachnodeConfig = {
-    enableRingZulu: config?.enableRingZulu ?? true,
-    storageRing: profile === 'storage' ? (config?.storageRing ?? { ring: 0 }) : undefined
-  };
-  
-  return new ArachnodeStub(profile, fullConfig);
-}
-
+import debug from 'debug';
+import type { NodeProfile, ArachnodeConfig } from './types.js';
+
+const log = debug('sereus:cadre:arachnode');
+
+/**
+ * Ring configuration for a storage node
+ */
+export interface RingConfig {
+  /** Ring number (0 = full keyspace, higher = more partitions) */
+  ring: number;
+  /** Partition within the ring (depends on ring level) */
+  partition: number;
+  /** Keyspace range this node is responsible for */
+  keyspaceStart: Uint8Array;
+  keyspaceEnd: Uint8Array;
+}
+
+/**
+ * Stub implementation of Arachnode ring participation.
+ * 
+ * Arachnode uses a concentric ring system where:
+ * - Ring Zulu (transaction ring): All nodes participate for transaction verification
+ * - Storage rings (0, 1, 2, 3...): Nodes join based on their storage capacity
+ *   - Ring 0: Full keyspace (requires most storage)
+ *   - Ring 1: 2 partitions
+ *   - Ring 2: 4 partitions
+ *   - Ring 3: 8 partitions
+ *   - etc.
+ * 
+ * This is a stub that will be replaced when arachnode is fully implemented.
+ */
+export class ArachnodeStub {
+  private readonly profile: NodeProfile;
+  private readonly config: ArachnodeConfig;
+  private ringConfig?: RingConfig;
+  private running = false;
+
+  constructor(profile: NodeProfile, config: ArachnodeConfig) {
+    this.profile = profile;
+    this.config = config;
+    log('ArachnodeStub created for profile=%s, config=%o', profile, config);
+  }
+
+  /**
+   * Start participating in rings
+   */
+  async start(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+
+    if (this.config.enableRingZulu) {
+      log('Joining Ring Zulu (transaction ring)');
+      // Stub: In real implementation, would register with transaction verification network
+    }
+
+    // Storage nodes join storage rings
+    if (this.profile === 'storage' && this.config.storageRing) {
+      const { ring, partition = 0 } = this.config.storageRing;
+      
+      log('Joining storage ring %d, partition %d', ring, partition);
+      
+      // Calculate keyspace range for this partition
+      // Stub: Using placeholder keyspace calculation
+      this.ringConfig = {
+        ring,
+        partition,
+        keyspaceStart: this.calculateKeyspaceStart(ring, partition),
+        keyspaceEnd: this.calculateKeyspaceEnd(ring, partition)
+      };
+      
+      // Stub: In real implementation, would:
+      // 1. Register with the storage ring
+      // 2. Begin accepting block storage requests for our keyspace
+      // 3. Participate in replication with other ring members
+    }
+
+    log('ArachnodeStub started');
+  }
+
+  /**
+   * Stop participating in rings
+   */
+  async stop(): Promise<void> {
+    if (!this.running) return;
+    this.running = false;
+
+    if (this.ringConfig) {
+      log('Leaving storage ring %d, partition %d', 
+          this.ringConfig.ring, this.ringConfig.partition);
+      // Stub: In real implementation, would gracefully leave the ring
+      this.ringConfig = undefined;
+    }
+
+    if (this.config.enableRingZulu) {
+      log('Leaving Ring Zulu');
+      // Stub: In real implementation, would leave transaction ring
+    }
+
+    log('ArachnodeStub stopped');
+  }
+
+  /**
+   * Get current ring configuration
+   */
+  getRingConfig(): RingConfig | undefined {
+    return this.ringConfig;
+  }
+
+  /**
+   * Check if participating in Ring Zulu
+   */
+  isInRingZulu(): boolean {
+    return this.running && this.config.enableRingZulu;
+  }
+
+  /**
+   * Check if participating in a storage ring
+   */
+  isInStorageRing(): boolean {
+    return this.running && this.ringConfig !== undefined;
+  }
+
+  // Stub keyspace calculations
+  private calculateKeyspaceStart(ring: number, partition: number): Uint8Array {
+    // Stub: Real implementation would calculate based on ring partition scheme
+    const numPartitions = Math.pow(2, ring);
+    const partitionSize = 256 / numPartitions;
+    const start = new Uint8Array(32);
+    start[0] = Math.floor(partition * partitionSize);
+    return start;
+  }
+
+  private calculateKeyspaceEnd(ring: number, partition: number): Uint8Array {
+    // Stub: Real implementation would calculate based on ring partition scheme
+    const numPartitions = Math.pow(2, ring);
+    const partitionSize = 256 / numPartitions;
+    const end = new Uint8Array(32);
+    end[0] = Math.floor((partition + 1) * partitionSize) - 1;
+    end.fill(0xFF, 1); // Fill rest with max values
+    return end;
+  }
+}
+
+/**
+ * Create an arachnode instance for a strand
+ */
+export function createArachnodeStub(
+  profile: NodeProfile, 
+  config?: Partial<ArachnodeConfig>
+): ArachnodeStub {
+  const fullConfig: ArachnodeConfig = {
+    enableRingZulu: config?.enableRingZulu ?? true,
+    storageRing: profile === 'storage' ? (config?.storageRing ?? { ring: 0 }) : undefined
+  };
+  
+  return new ArachnodeStub(profile, fullConfig);
+}
+

package/src/bootstrap-peer-store-file.ts

@@ -1,44 +1,44 @@
-/**
- * Node-only file-backed {@link BootstrapPeerStore}: one JSON file per party under
- * a configured directory (the node's state directory — `cadre-cli` passes
- * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated
- * cold-start dial targets a seed nominated.
- *
- * Nothing but the file itself lives here: the envelope, load policy, per-entry
- * validation (shape only — never signatures; see the `bootstrap-peer-store.ts`
- * module comment for why nothing persisted here is trust-bearing) and the
- * serialised snapshot writes are cross-platform in
- * `PersistentBootstrapPeerStore` / `node-local-snapshot.ts`, and the file is a
- * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of
- * the package's cross-platform default entry (`./index.js`) — import it from the
- * dedicated subpath instead:
- *
- * ```ts
- * import { FileBootstrapPeerStore } from '@serfab/cadre-core/bootstrap-peer-store-file';
- * ```
- *
- * A React Native / browser entry graph never resolves this path, so the
- * `node:fs` edge never reaches a bundler that cannot satisfy it (same isolation
- * pattern as `trusted-owner-store-file.ts` / `key-store-file.ts`).
- */
-import { FileDurableSlot } from './file-durable-slot.js';
-import { PersistentBootstrapPeerStore } from './bootstrap-peer-store.js';
-import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
-
-/** Base name of the store file: `<dir>/bootstrap-peers.<encoded partyId>.json`. */
-const SLOT_NAME = 'bootstrap-peers';
-
-/**
- * File-backed {@link BootstrapPeerStore}. Open via {@link open}, which loads the
- * existing file and returns the cross-platform store over it; an absent, corrupt, or wrong-party file is a cold
- * start (empty store) and structurally junk entries are dropped, while a
- * present-but-unreadable file throws. Those rules and their reasoning live on
- * `NodeLocalSnapshot.open` — including the in-process-only write serialisation,
- * which two nodes sharing one directory for one party would defeat.
- */
-export const FileBootstrapPeerStore = {
-	/** Load (or cold-start) the party's retained dial targets from a file in `dir`. */
-	async open(dir: string, partyId: string): Promise<BootstrapPeerStore> {
-		return PersistentBootstrapPeerStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
-	}
-};
+/**
+ * Node-only file-backed {@link BootstrapPeerStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated
+ * cold-start dial targets a seed nominated.
+ *
+ * Nothing but the file itself lives here: the envelope, load policy, per-entry
+ * validation (shape only — never signatures; see the `bootstrap-peer-store.ts`
+ * module comment for why nothing persisted here is trust-bearing) and the
+ * serialised snapshot writes are cross-platform in
+ * `PersistentBootstrapPeerStore` / `node-local-snapshot.ts`, and the file is a
+ * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of
+ * the package's cross-platform default entry (`./index.js`) — import it from the
+ * dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileBootstrapPeerStore } from '@serfab/cadre-core/bootstrap-peer-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the
+ * `node:fs` edge never reaches a bundler that cannot satisfy it (same isolation
+ * pattern as `trusted-owner-store-file.ts` / `key-store-file.ts`).
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentBootstrapPeerStore } from './bootstrap-peer-store.js';
+import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
+
+/** Base name of the store file: `<dir>/bootstrap-peers.<encoded partyId>.json`. */
+const SLOT_NAME = 'bootstrap-peers';
+
+/**
+ * File-backed {@link BootstrapPeerStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it; an absent, corrupt, or wrong-party file is a cold
+ * start (empty store) and structurally junk entries are dropped, while a
+ * present-but-unreadable file throws. Those rules and their reasoning live on
+ * `NodeLocalSnapshot.open` — including the in-process-only write serialisation,
+ * which two nodes sharing one directory for one party would defeat.
+ */
+export const FileBootstrapPeerStore = {
+	/** Load (or cold-start) the party's retained dial targets from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<BootstrapPeerStore> {
+		return PersistentBootstrapPeerStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};