@serfab/cadre-core 0.9.0 → 0.11.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

@@ -0,0 +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);
+	}
+};

package/src/bootstrap-peer-store.ts

@@ -0,0 +1,172 @@
+/**
+ * Node-local, NON-replicated cold-start bootstrap-peer store: the dial targets a
+ * node keeps so it can retry its way back into a party it has been seeded into
+ * but never managed to connect to.
+ *
+ * A newcomer applies a signed seed nominating the party's owner machines and the
+ * addresses they answer on. `SeedBootstrapService.applySeed` dials those owners
+ * exactly once, best-effort; when that dial fails (owner briefly down, relay
+ * reservation not up, not yet vouched) the node has an empty `CadrePeer` table
+ * and no connection, and `CadreNode.reconcileControlCohort`'s cold-start branch
+ * is the only way back — it re-dials these retained addresses every pass. Held
+ * only in memory, they die with the process and the node is stranded for good,
+ * which is what this store exists to prevent.
+ *
+ * Three implementations, mirroring `trusted-owner-store.ts` (read that first —
+ * it solves the same "must outlive the process, storage differs per platform"
+ * problem, the two stores are deliberately symmetrical, and both persistent
+ * forms share `node-local-snapshot.ts`):
+ *  - {@link MemoryBootstrapPeerStore} (this module, cross-platform) — ephemeral;
+ *    the default when no store is injected via `CadreNodeConfig.bootstrapPeers`.
+ *  - {@link PersistentBootstrapPeerStore} (this module, cross-platform) — durable
+ *    over any `DurableSlot` the embedding app supplies (IndexedDB, a LevelDB KV,
+ *    SQLite, …).
+ *  - `FileBootstrapPeerStore` — the above over a Node file in the node's state
+ *    directory; Node-only, behind the subpath
+ *    `@serfab/cadre-core/bootstrap-peer-store-file` (same isolation pattern as
+ *    `key-store-file`) so `node:fs` never lands in the RN/browser entry graph.
+ *
+ * **Nothing here is trust-bearing, and a loader must not try to re-verify it.**
+ * Only *dial targets* are retained — never a seed, a signature, or an authority
+ * claim. The seed was signature-checked against the node-local trusted-owner
+ * anchor before its addresses were retained, and a dial grants no authority:
+ * `CadreNode.bootstrapDialAddrs` binds every address to the peer id it was
+ * retained under, so a dial cannot be redirected to whoever answers. What a
+ * persistent backend's loader DOES owe is dropping structurally junk entries
+ * (unparseable peer id, empty address list, non-string address) rather than
+ * carrying them into the dial loop.
+ */
+import debug from 'debug';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { NodeLocalSnapshot, type DurableSlot, type NodeLocalSnapshotSpec } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:bootstrap-peer-store');
+
+/** One retained cold-start dial target: an owner peer a seed nominated. */
+export interface BootstrapPeerEntry {
+	/** Multiaddr strings exactly as the seed carried them (parsed at dial time). */
+	addrs: string[];
+	/** Wall-clock ms the entry was last recorded (diagnostics / future eviction). */
+	recordedAt: number;
+}
+
+export interface BootstrapPeerStore {
+	/** Party this store is scoped to. */
+	readonly partyId: string;
+
+	/**
+	 * Every retained target, peerId -> entry. Every backend copies the map per call,
+	 * so the result is a snapshot decoupled from later {@link record} calls and is
+	 * safe to iterate while recording. The entry objects need no copy: `record`
+	 * REPLACES an entry rather than mutating it in place.
+	 */
+	all(): ReadonlyMap<string, BootstrapPeerEntry>;
+
+	/**
+	 * Retain (or REPLACE) a peer's dial addresses. Replace, not merge, so a
+	 * re-seed after an owner's address changed drops the stale address instead of
+	 * accumulating dead ones.
+	 *
+	 * Implementations MUST reflect the entry in {@link all} SYNCHRONOUSLY; the
+	 * returned promise tracks durability only. That is what lets the synchronous
+	 * `CadreNode.recordSeedBootstrapPeers` keep its signature while a file
+	 * backend persists in the background.
+	 *
+	 * NOTE: entries are never evicted, and a persistent backend's file therefore
+	 * grows across the node's whole lifetime rather than one process. Fine while a
+	 * seed nominates one or a few owners and entries are keyed by peer id; if a
+	 * node ever applies seeds naming many distinct owners, add eviction (oldest
+	 * {@link BootstrapPeerEntry.recordedAt} first, or a cap) rather than letting
+	 * the file grow unbounded — `recordedAt` exists so eviction has something to
+	 * sort by.
+	 */
+	record(peerId: string, addrs: readonly string[]): Promise<void>;
+}
+
+/**
+ * Ephemeral in-memory store for nodes without durable storage (tests, browser
+ * demos, not-yet-persisted mobile). Same contract, no disk: a node using this
+ * loses its retry targets on restart and must be re-seeded to rejoin.
+ */
+export class MemoryBootstrapPeerStore implements BootstrapPeerStore {
+	private readonly peers = new Map<string, BootstrapPeerEntry>();
+
+	constructor(readonly partyId: string) {}
+
+	all(): ReadonlyMap<string, BootstrapPeerEntry> {
+		return new Map(this.peers);
+	}
+
+	async record(peerId: string, addrs: readonly string[]): Promise<void> {
+		this.peers.set(peerId, { addrs: [...addrs], recordedAt: Date.now() });
+		log('bootstrap peer retained (party=%s, peer=%s, addrs=%d)', this.partyId, peerId, addrs.length);
+	}
+}
+
+/**
+ * What the store persists: `peers` maps peerId -> {@link BootstrapPeerEntry}.
+ *
+ * A structurally junk entry is DROPPED and its siblings retained — nothing here
+ * is trust-bearing (see the module comment) and the record is a stranded node's
+ * only way back into its party, so discarding the whole set over one bad entry
+ * would be strictly worse. What "junk" means: an unparseable peer id (the dial
+ * path binds every address to this id, so an id that cannot parse is not a dial
+ * target at all), an empty address list, or a non-string address — each would
+ * otherwise log a parse failure once per reconcile pass forever.
+ */
+const BOOTSTRAP_PEER_SNAPSHOT: NodeLocalSnapshotSpec<BootstrapPeerEntry> = {
+	label: 'bootstrap-peer store',
+	payloadKey: 'peers',
+	unusableEntry: 'drop-entry',
+	acceptEntry: (peerId, entry) => {
+		if (typeof entry !== 'object' || entry === null) return undefined;
+		const { addrs, recordedAt } = entry as { addrs?: unknown; recordedAt?: unknown };
+		if (!Array.isArray(addrs) || addrs.length === 0) return undefined;
+		if (addrs.some((addr) => typeof addr !== 'string' || addr.length === 0)) return undefined;
+		if (typeof recordedAt !== 'number') return undefined;
+		try {
+			peerIdFromString(peerId);
+		} catch {
+			return undefined;
+		}
+		return { addrs: [...(addrs as string[])], recordedAt };
+	}
+};
+
+/**
+ * Durable {@link BootstrapPeerStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileBootstrapPeerStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load and persist policy — what an absent, corrupt,
+ * foreign-party or unreadable slot does, and what a failed persist does — is
+ * documented once on `NodeLocalSnapshot`; this class only supplies the payload
+ * shape and the drop-the-bad-entry policy above.
+ */
+export class PersistentBootstrapPeerStore implements BootstrapPeerStore {
+	private constructor(private readonly snapshot: NodeLocalSnapshot<BootstrapPeerEntry>) {}
+
+	/** Load (or cold-start) the party's retained dial targets from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentBootstrapPeerStore> {
+		return new PersistentBootstrapPeerStore(
+			await NodeLocalSnapshot.open(slot, partyId, BOOTSTRAP_PEER_SNAPSHOT)
+		);
+	}
+
+	get partyId(): string {
+		return this.snapshot.partyId;
+	}
+
+	all(): ReadonlyMap<string, BootstrapPeerEntry> {
+		return this.snapshot.entrySnapshot();
+	}
+
+	/**
+	 * Retain a peer's dial addresses: visible via {@link all} synchronously, then
+	 * the full snapshot is persisted (see `NodeLocalSnapshot.put`).
+	 */
+	record(peerId: string, addrs: readonly string[]): Promise<void> {
+		log('bootstrap peer retained (party=%s, peer=%s, addrs=%d); persisting', this.partyId, peerId, addrs.length);
+		return this.snapshot.put(peerId, { addrs: [...addrs], recordedAt: Date.now() });
+	}
+}