@serfab/cadre-core 0.13.0 → 1.0.0

package/README.md

@@ -65,8 +65,9 @@ const node = new CadreNode({
   },
   profile: 'storage',  // 'storage' for servers, 'transaction' for mobile
   storage: {
-    // Storage provider factory - called with strandId for strand-isolated storage
-    provider: (strandId) => new FileRawStorage(`/data/sereus/${strandId}`),
+    // Storage provider factory - called once per scope (each strand id, plus this
+    // party's control database) for per-scope isolation
+    provider: (scope) => new FileRawStorage(`/data/sereus/${scope}`),
     quotaBytes: 10 * 1024 * 1024 * 1024  // 10 GB
   }
 });
@@ -154,6 +155,10 @@ const { seed, encodedSeed } = await node.addDrone({
 
 // Send to provider for drone initialization
 await provider.initializeNode(droneInfo.containerId, encodedSeed);
+
+// Dial the drone now from the addresses addDrone kept (a drone cannot dial a
+// phone); otherwise the next reconcile pass, about every 15 s, does it
+await node.reconcileControlCohort();
 ```
 
 ## API Reference
@@ -209,8 +214,8 @@ const node = new CadreNode({
   profile: 'transaction',  // Mobile devices typically use transaction profile
   strandFilter: { mode: 'sAppId', sAppId: 'com.example.myapp' },
   storage: {
-    // RN storage provider creates strand-isolated AsyncStorage
-    provider: (strandId) => new RNRawStorage(strandId)
+    // RN storage provider creates per-scope AsyncStorage
+    provider: (scope) => new RNRawStorage(scope)
   },
   network: {
     // TCP doesn't work in React Native — use WebSocket transport instead
@@ -223,8 +228,17 @@ const node = new CadreNode({
 ### Storage Provider Pattern
 
 The `storage.provider` option accepts either:
-- **An `IRawStorage` instance** - Shared storage for all strands
-- **A factory function** `(strandId: string) => IRawStorage` - Creates isolated storage per strand (recommended)
+- **An `IRawStorage` instance** - One store shared by every scope, so it can serve only a single party
+- **A factory function** `(scope: string) => IRawStorage` - Creates isolated storage per scope (recommended)
+
+A **scope key** is what the factory receives. It is the strand id for each strand, and
+`controlStorageScope(partyId)` — `control-<base64url party id>` — for the control database,
+which holds one party's own records and must not be shared between parties. Every key is
+opaque and already safe as a file, directory or database name (always within
+`[A-Za-z0-9._-]`): use it verbatim, do not parse it. `isControlStorageScope(scope)` tells
+the two kinds apart. Caveat, until `bug-strand-scope-key-charset-unenforced` lands: the
+charset is enforced for the control key but only *conventional* for a strand id, which
+reaches the factory verbatim even when the strand row replicated in from another node.
 
 Available storage implementations:
 | Package | Environment | Description |

package/dist/bootstrap-peer-store-file.js

@@ -1,8 +1,8 @@
 /**
  * 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.
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated dial
+ * targets learned out of band (a seed's owner peers, and nodes this node added).
  *
  * Nothing but the file itself lives here: the envelope, load policy, per-entry
  * validation (shape only — never signatures; see the `bootstrap-peer-store.ts`

package/dist/bootstrap-peer-store.d.ts

@@ -1,7 +1,10 @@
 import { type DurableSlot } from './node-local-snapshot.js';
-/** One retained cold-start dial target: an owner peer a seed nominated. */
+/**
+ * One retained dial target learned out of band: an owner peer a seed nominated,
+ * or a node this node added.
+ */
 export interface BootstrapPeerEntry {
-    /** Multiaddr strings exactly as the seed carried them (parsed at dial time). */
+    /** Multiaddr strings exactly as they were handed over (parsed at dial time). */
     addrs: string[];
     /** Wall-clock ms the entry was last recorded (diagnostics / future eviction). */
     recordedAt: number;
@@ -11,9 +14,9 @@ export interface BootstrapPeerStore {
     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.
+     * so the result is a snapshot decoupled from later {@link record} and
+     * {@link forget} 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>;
     /**
@@ -26,15 +29,25 @@ export interface BootstrapPeerStore {
      * `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.
+     * NOTE: entries are never evicted (only a local `removePeer` {@link forget}s
+     * one), 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, a node adds a handful of machines, and entries are keyed by peer id;
+     * if a node ever applies seeds naming many distinct owners or adds many
+     * machines, 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>;
+    /**
+     * Drop a peer's retained dial addresses — for a peer this node removed from the
+     * party, which must not stay a dial target. Forgetting a peer with no entry is a
+     * no-op.
+     *
+     * Same contract as {@link record}: the removal is reflected in {@link all}
+     * SYNCHRONOUSLY, and the returned promise tracks durability only.
+     */
+    forget(peerId: string): Promise<void>;
 }
 /**
  * Ephemeral in-memory store for nodes without durable storage (tests, browser
@@ -47,6 +60,7 @@ export declare class MemoryBootstrapPeerStore implements BootstrapPeerStore {
     constructor(partyId: string);
     all(): ReadonlyMap<string, BootstrapPeerEntry>;
     record(peerId: string, addrs: readonly string[]): Promise<void>;
+    forget(peerId: string): Promise<void>;
 }
 /**
  * Durable {@link BootstrapPeerStore} over an app-supplied {@link DurableSlot} —
@@ -70,4 +84,10 @@ export declare class PersistentBootstrapPeerStore implements BootstrapPeerStore
      * the full snapshot is persisted (see `NodeLocalSnapshot.put`).
      */
     record(peerId: string, addrs: readonly string[]): Promise<void>;
+    /**
+     * Drop a peer's dial addresses: gone from {@link all} synchronously, then the
+     * full snapshot is persisted — unless there was no entry, which writes nothing
+     * (see `NodeLocalSnapshot.remove`).
+     */
+    forget(peerId: string): Promise<void>;
 }

package/dist/bootstrap-peer-store.js

@@ -1,16 +1,25 @@
 /**
- * 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.
+ * Node-local, NON-replicated bootstrap-peer store: dial targets a node learned
+ * out of band, kept so it can dial those peers when nothing better is known.
+ * Two sources feed it:
  *
- * 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.
+ *  - **A seed's owner peers.** 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.
+ *  - **Nodes this node added.** `CadreNode.addDrone` is handed the added node's
+ *    addresses, but that node's `CadrePeer` row stays unsigned, and therefore
+ *    unresolvable, until the node self-publishes — which needs a connection, and
+ *    a node that cannot listen (a phone) is never dialed by it. The steady-state
+ *    reconcile pass falls back to these addresses for a sibling whose signed
+ *    record and address-book entry both yield nothing, including after a
+ *    relaunch that outlived the record's freshness window.
+ *
+ * Held only in memory, either kind dies with the process and the node is left
+ * with no address to dial, 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"
@@ -28,10 +37,11 @@
  *
  * **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
+ * claim. A seed was signature-checked against the node-local trusted-owner
+ * anchor before its addresses were retained, and an added node's addresses were
+ * supplied by the owner that chose to add it. Either way 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.
@@ -57,6 +67,11 @@ export class MemoryBootstrapPeerStore {
         this.peers.set(peerId, { addrs: [...addrs], recordedAt: Date.now() });
         log('bootstrap peer retained (party=%s, peer=%s, addrs=%d)', this.partyId, peerId, addrs.length);
     }
+    async forget(peerId) {
+        if (this.peers.delete(peerId)) {
+            log('bootstrap peer forgotten (party=%s, peer=%s)', this.partyId, peerId);
+        }
+    }
 }
 /**
  * What the store persists: `peers` maps peerId -> {@link BootstrapPeerEntry}.
@@ -124,5 +139,16 @@ export class PersistentBootstrapPeerStore {
         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() });
     }
+    /**
+     * Drop a peer's dial addresses: gone from {@link all} synchronously, then the
+     * full snapshot is persisted — unless there was no entry, which writes nothing
+     * (see `NodeLocalSnapshot.remove`).
+     */
+    forget(peerId) {
+        if (this.snapshot.has(peerId)) {
+            log('bootstrap peer forgotten (party=%s, peer=%s); persisting', this.partyId, peerId);
+        }
+        return this.snapshot.remove(peerId);
+    }
 }
 //# sourceMappingURL=bootstrap-peer-store.js.map

package/dist/bootstrap-peer-store.js.map

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