@serfab/cadre-core 0.6.0 → 0.8.1

package/dist/types.d.ts

@@ -1,6 +1,16 @@
-import type { Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
+import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
+import type { IRepo } from '@optimystic/db-core';
 import type { StrandDatabase } from './strand-database.js';
+import type { SeedTrustPolicy } from './seed-trust-policy.js';
+import type { KeyStore, KeyId } from './key-store.js';
+/**
+ * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
+ * createLibp2pNode after node creation (not surfaced on the base Libp2p type).
+ */
+export interface Libp2pNodeWithRepo extends Libp2p {
+    coordinatedRepo: IRepo;
+}
 /**
  * Node profile determines storage participation
  */
@@ -31,11 +41,31 @@ export interface HibernationTimeouts {
     idleTimeout: number;
     /** Time before transitioning from idle to hibernating */
     hibernateTimeout: number;
-    /** Interval for check-ins while hibernating */
+    /**
+     * Base interval for the FIRST check-in after hibernating. Successive
+     * no-activity check-ins escalate this delay by {@link checkInBackoffFactor}
+     * (see {@link HibernationManager}'s self-rescheduling check-in chain).
+     */
     checkInInterval: number;
+    /**
+     * Multiplier applied to the check-in delay after each check-in that finds no
+     * pending activity (must be >= 1; 1 disables escalation). Default 2 →
+     * doubling: base, base×2, base×4, … until {@link checkInMaxInterval}.
+     */
+    checkInBackoffFactor: number;
+    /**
+     * Upper bound on the escalating check-in delay — the concrete realization of
+     * the architecture's "minutes → hours → days" ceiling for this hint. Backoff
+     * never schedules a delay longer than this.
+     */
+    checkInMaxInterval: number;
 }
 /**
- * Default hibernation timeouts per latency hint
+ * Default hibernation timeouts per latency hint.
+ *
+ * `checkInInterval` is the BASE delay; `checkInMaxInterval` is the per-hint
+ * ceiling the exponential backoff escalates toward (interactive minutes→~1h,
+ * background minutes→~6h, archive ~1h→~3 days).
  */
 export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts>;
 /**
@@ -101,6 +131,44 @@ export interface NetworkConfig {
      * ```
      */
     transports?: Libp2pTransports;
+    /**
+     * Optional async resolver returning the multiaddrs to embed in invites
+     * (and other authority-address contexts). When unset, `libp2pNode.getMultiaddrs()`
+     * is used. Hosts behind NAT supply this to substitute their DDNS hostname
+     * and externally-mapped port — see `@serfab/cadre-host`'s NatService.
+     */
+    inviteAddressResolver?: () => Promise<string[]>;
+    /**
+     * Optional libp2p connection gater, threaded to both the control node and every
+     * strand's cohort node. libp2p's browser default denies dialing insecure
+     * WebSockets and private/loopback addresses; callers that must dial local or
+     * unsecured peers (the web reference dialing a `127.0.0.1/.../ws` responder,
+     * Playwright e2e, RN simulators) supply a permissive gater here — e.g.
+     * `{ denyDialMultiaddr: () => false }`. See `@optimystic/db-p2p`'s
+     * `libp2p-node-base` for the underlying option.
+     */
+    connectionGater?: ConnectionGater;
+    /**
+     * 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
+     * ({@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE} /
+     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}).
+     */
+    controlCohort?: {
+        /**
+         * Cap on the number of NON-authority siblings dialed per reconcile pass
+         * (backbone/authority members are always dialed and do not count). Defaults
+         * to {@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE}.
+         */
+        targetDegree?: number;
+        /**
+         * Recurring reconcile cadence in ms. Defaults to
+         * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}.
+         */
+        reconcileMs?: number;
+    };
 }
 /**
  * Hibernation configuration
@@ -110,7 +178,19 @@ export interface HibernationConfig {
     defaultLatencyHint?: LatencyHint;
     /** Custom timeouts per latency hint (overrides defaults) */
     customTimeouts?: Partial<Record<LatencyHint, Partial<HibernationTimeouts>>>;
+    /**
+     * How long a hibernating strand stays resumed during a check-in to let its
+     * strand network connect to reachable cohort peers (and the app drive
+     * pull-on-read activity) before re-hibernating if still idle. Defaults to
+     * {@link DEFAULT_CHECKIN_WINDOW_MS}.
+     */
+    checkInWindowMs?: number;
 }
+/**
+ * Default duration of the resume-and-probe window during a strand check-in.
+ * See {@link HibernationConfig.checkInWindowMs}.
+ */
+export declare const DEFAULT_CHECKIN_WINDOW_MS: number;
 /**
  * Control network configuration
  */
@@ -124,8 +204,28 @@ export interface ControlNetworkConfig {
  * Main configuration for a CadreNode
  */
 export interface CadreNodeConfig {
-    /** If provided, use this keypair for the node identity */
+    /**
+     * If provided, use this keypair for the node identity (direct injection).
+     * Mutually exclusive with {@link keyStore} — supplying both is a configuration
+     * error (fail closed) thrown by `start()` before any network bring-up.
+     */
     privateKey?: PrivateKey;
+    /**
+     * Pluggable secure store for node key material. When set, the node loads its
+     * identity from `keyStore` under {@link identityKeyId}, generating + persisting
+     * a fresh Ed25519 key on first run (protobuf bytes are the canonical stored
+     * form). Mutually exclusive with {@link privateKey}. Absent ⇒ legacy behavior
+     * (use `privateKey`, else libp2p generates an ephemeral key).
+     *
+     * In the single-key reference model the authority signing key is *derived from*
+     * the node identity (see {@link CadreNode.getIdentityAuthorityKey}), so
+     * protecting the identity in a secure enclave protects the authority key too.
+     * A future separate-authority slot (`authorityKeyId`) is anticipated but not
+     * built here.
+     */
+    keyStore?: KeyStore;
+    /** Slot id for the node identity in {@link keyStore}. Default: `'cadre/identity'`. */
+    identityKeyId?: KeyId;
     /** Control network connection settings */
     controlNetwork: ControlNetworkConfig;
     /** Node profile: transaction-only or storage */
@@ -140,6 +240,33 @@ export interface CadreNodeConfig {
     hibernation?: HibernationConfig;
     /** Polling interval for strand watcher in ms (default: 5000) */
     strandWatchInterval?: number;
+    /**
+     * Require a valid author signature on every sApp schema before a strand is
+     * formed or joined. Defaults to true (fail closed): an unsigned schema is
+     * rejected before any libp2p node or schema DDL is brought up. Set false ONLY
+     * for dev/test where unsigned demo schemas are used.
+     */
+    requireSignedSchemas?: boolean;
+    /**
+     * Node-wide default trust anchor for INBOUND control-network seeds. Forwarded
+     * into every SeedBootstrapService this node constructs (authority, receive-only
+     * listener, and the temp service used by applySeed when no service exists), and
+     * used as the service-level default the libp2p seed-protocol handler relies on
+     * (that path has no per-call override seam). Defaults to dbAnchoredTrustPolicy()
+     * inside SeedBootstrapService when unset — a cold-start node then rejects every
+     * seed. A per-call `applySeed(seed, { trustPolicy })` override still wins over
+     * this default for callers that hold out-of-band material (e.g. a pinned key
+     * from a CadreInvite).
+     */
+    seedTrustPolicy?: SeedTrustPolicy;
+    /**
+     * Platform push-delivery credentials (FCM and/or APNs). When present, the node
+     * can deliver strand-wake data messages to suspended mobile peers over the
+     * platform push channel — the server fan-out constructs a `PushNotifier` from
+     * this. Absent ⇒ no platform push (control-network push-wake only). Injected
+     * per node by `cadre-host`; `privateKey` fields are secrets and are never logged.
+     */
+    push?: PushCredentials;
 }
 /**
  * Status of a strand instance
@@ -177,6 +304,27 @@ export interface StrandInstance {
     /** Error message if status is 'error' */
     error?: string;
 }
+/**
+ * Outcome of an on-demand {@link CadreNode.serviceWake} — the mobile push-wake
+ * cycle (resume → bounded window → re-hibernate-if-idle) run imperatively for a
+ * single strand.
+ */
+export interface ServiceWakeResult {
+    /** The strand the wake was requested for. */
+    strandId: string;
+    /**
+     * Whether the wake was actually serviced. `false` when the node is not
+     * running, or the strand is unknown to this node (not a member-participated
+     * strand) — never a thrown error, so a background task can branch on it.
+     */
+    serviced: boolean;
+    /**
+     * Whether activity landed during the wake window. `true` leaves the strand
+     * active; `false` re-hibernates it (or the strand was already live, in which
+     * case it reflects current liveness). Always `false` when `serviced` is `false`.
+     */
+    hadActivity: boolean;
+}
 /**
  * Strand row from control network - basic membership info
  */
@@ -196,7 +344,13 @@ export interface SAppConfig {
     version: string;
     /** The declarative schema DDL */
     schema: string;
-    /** Author's signature over the schema for verification (omit to skip verification) */
+    /**
+     * Author's signature over the schema for verification. Required under the
+     * default `requireSignedSchemas` node policy — a config without it is rejected
+     * before strand bring-up. Optional in the type because authoring/serialization
+     * must represent an as-yet-unsigned config; omitting it is honored only when
+     * the node explicitly relaxes the policy (`requireSignedSchemas: false`, dev/test).
+     */
     signature?: string;
     /** Latency hint for hibernation behavior (optional, defaults to config) */
     latencyHint?: LatencyHint;
@@ -224,10 +378,22 @@ export interface StrandConfig {
     /** sApp configuration provided by the hosting application */
     sAppConfig: SAppConfig;
     /**
-     * Lifecycle mode for this strand instance. Defaults to `'networked'` when omitted
-     * to preserve the historical behavior for multi-peer callers.
+     * 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
+     * paths; the same party that calls {@link CadreNode.publishStrand}). The founder
+     * runs the one-time membership bootstrap at bring-up (writes `Strand.Header`, and
+     * for a closed strand the founding `Member`+`Authority`). A joiner leaves this
+     * `false`/unset and writes nothing — it receives those rows via Optimystic sync.
+     * Defaults to `false`.
+     */
+    founder?: boolean;
 }
 /**
  * Result of creating a new cadre peer
@@ -279,6 +445,13 @@ export interface FormStrandResult {
     invitePrivateKey: string;
     /** The strand that was created */
     strandId: string;
+    /**
+     * The strand's membership key (closed-strand read-gating secret), delivered through
+     * the formation protocol after consent (provision-then-record). Present only for a
+     * closed strand the responder returned with its key; undefined otherwise. Distinct
+     * from {@link invitePrivateKey} (the initiator's own generated signing key).
+     */
+    memberPrivateKey?: string;
 }
 /**
  * Result of validating a strand formation request
@@ -340,6 +513,17 @@ export interface CadreNodeEvents {
     'strand:waking': {
         strandId: string;
     };
+    /**
+     * Emitted when the control network advertises a strand this node has no
+     * registered `sAppConfig` for — i.e. a strand created by another member. The
+     * hosting app decides whether to join it (register a config + `addStrand`,
+     * e.g. via a chat `joinChatStrand` helper). Carries the full {@link StrandRow}
+     * so the app can join without re-querying the control DB.
+     */
+    'strand:discovered': {
+        strandId: string;
+        strand: StrandRow;
+    };
     'control:connected': void;
     'control:disconnected': void;
     /** Emitted when a seed is received via the seed protocol */
@@ -358,6 +542,175 @@ export interface CadreNodeEvents {
         error: string;
     };
 }
+/**
+ * A peer's self-published, freshness-stamped, self-signed address record.
+ *
+ * This is the logical shape of a `CadreControl.CadrePeer` row. A node publishes
+ * its own record (signing with the ed25519 key behind its PeerId); any node can
+ * resolve another member's current signaling/relay multiaddrs from only its
+ * PeerId by reading the record, re-verifying the self-signature against
+ * `publicKey`, checking freshness, and applying a trust gate.
+ *
+ * The signature covers `peerId`, the comma-joined `addrs`, and `updatedAt` — see
+ * `peerRecordSignedPayload`. `publicKey` is NOT inside the signed payload: it is
+ * the key the signature is verified *with*, and its libp2p-identity binding to
+ * `peerId` is checked separately at resolve time, so re-signing it would be
+ * redundant.
+ */
+export interface PeerAddressRecord {
+    /** libp2p peer ID (base58btc) — the row key. */
+    peerId: string;
+    /** ed25519 public key (base64url) whose libp2p identity IS `peerId`. */
+    publicKey: string;
+    /** Current dialable multiaddrs, signaling (`/p2p-circuit`) first. */
+    addrs: string[];
+    /** epoch ms — freshness; strictly increasing per peer. */
+    updatedAt: number;
+    /** ed25519 self-signature over the signed payload, base64url. */
+    sig: string;
+}
+/**
+ * Outcome of {@link CadreNode.registerSelf}, surfaced so callers (e.g. the CLI
+ * `--authority` branch) can log what happened:
+ * - `inserted` — the first authority-signed INSERT of this node's `CadrePeer` row.
+ * - `refreshed` — a self-signed UPDATE of an existing row (heartbeat / addr change).
+ * - `skipped` — nothing written (no self-signing key, or not yet a member with no
+ *   authority service to self-insert).
+ */
+export type SelfRegistrationOutcome = 'inserted' | 'refreshed' | 'skipped';
+/**
+ * Options for {@link CadreNode.resolvePeerAddrs}.
+ */
+export interface ResolveOpts {
+    /**
+     * Freshness ceiling in ms. A record older than this is filtered out (a
+     * resolver must never hand back a dead relay reservation). Defaults to
+     * {@link DEFAULT_PEER_RECORD_MAX_AGE_MS}.
+     */
+    maxAgeMs?: number;
+    /** Return only `/p2p-circuit` signaling addrs (the WebRTC dial input). */
+    signalingOnly?: boolean;
+    /**
+     * Pluggable trust gate, evaluated after signature + freshness pass. Defaults
+     * to {@link currentMemberTrustPolicy} (any existing — therefore
+     * authority-vouched — CadrePeer member is trusted). Inject a stricter policy
+     * (e.g. from `seed-signerkey-trust-policy`) to reject otherwise-valid records
+     * before dialing.
+     */
+    trustPolicy?: PeerResolveTrustPolicy;
+}
+/**
+ * Context handed to a {@link PeerResolveTrustPolicy} when gating a resolution.
+ */
+export interface PeerResolveContext {
+    /** The peer being resolved. */
+    peerId: string;
+    /** The record's ed25519 public key (already bound to `peerId` and verified). */
+    publicKey: string;
+    /** The party whose control network produced the record. */
+    partyId: string;
+    /** The full verified, fresh record. */
+    record: PeerAddressRecord;
+}
+/**
+ * Decides whether a signature-verified, fresh peer-address record should be
+ * trusted enough to dial. The seam through which a richer trust model
+ * (trust circle, pinned keys) composes with `resolvePeerAddrs`.
+ */
+export interface PeerResolveTrustPolicy {
+    evaluate(ctx: PeerResolveContext): Promise<boolean> | boolean;
+}
+/** Platform push channel a {@link DeviceTokenRecord} targets. */
+export type PushPlatform = 'fcm' | 'apns';
+/**
+ * A mobile cadre peer's self-published, freshness-stamped, self-signed platform
+ * push token.
+ *
+ * This is the logical shape of a `CadreControl.DeviceToken` row. A phone publishes
+ * its own record (signing with the ed25519 key behind its PeerId); a server peer
+ * resolves it from the phone's PeerId to deliver a push-wake over FCM/APNs when a
+ * control-network dial cannot reach the OS-suspended process. The signature covers
+ * `peerId`, `platform`, `token`, and `updatedAt` — see `deviceTokenSignedPayload`.
+ *
+ * Unlike {@link PeerAddressRecord}, the record carries NO public key: it is verified
+ * against the `CadrePeer.PublicKey` bound to the same `peerId`, so a `DeviceToken`
+ * with no backing `CadrePeer` row can never be resolved.
+ */
+export interface DeviceTokenRecord {
+    /** libp2p peer ID (base58btc) — the row key and the CadrePeer this token belongs to. */
+    peerId: string;
+    /** Push channel: `'fcm'` (Android/Firebase) or `'apns'` (Apple). */
+    platform: PushPlatform;
+    /** Opaque platform device/registration token. */
+    token: string;
+    /** epoch ms — freshness; strictly increasing per self-update (replay guard). */
+    updatedAt: number;
+    /** ed25519 self-signature over the signed payload, base64url. */
+    sig: string;
+}
+/**
+ * Options for {@link CadreNode.resolveDeviceToken}.
+ */
+export interface ResolveDeviceTokenOpts {
+    /**
+     * Optional freshness ceiling in ms. Defaults to NO ceiling (a record is fresh
+     * as long as its `updatedAt` is positive): unlike a relay reservation, a device
+     * push token stays valid until it rotates, so a long-suspended phone must remain
+     * resolvable for push-wake. Set this to bound staleness explicitly.
+     */
+    maxAgeMs?: number;
+}
+/**
+ * Platform push-delivery credentials injected into a participating node's config
+ * (`CadreNodeConfig.push`). Provisioned per spawned node by `cadre-host` and read
+ * by `createPushNotifier` to construct the FCM and/or APNs senders. A platform
+ * whose block is absent is simply not deliverable (the router returns a
+ * best-effort "no credentials" failure rather than throwing).
+ *
+ * Secret hygiene: every `privateKey` field is a secret — never logged (treated
+ * like the node's startup/seed tokens).
+ */
+export interface PushCredentials {
+    /** FCM (Android / Firebase) service-account credentials. */
+    fcm?: FcmCredentials;
+    /** APNs (Apple) auth-key credentials. */
+    apns?: ApnsCredentials;
+    /**
+     * Per-`(peer, strand)` minimum gap between push-wakes the server fan-out emits —
+     * the anti-spam cooldown a chatty strand needs. Default
+     * {@link DEFAULT_PUSH_COOLDOWN_MS} (5 min). In-memory, acceptably lossy across
+     * restarts (`serviceWake` is idempotent, so a duplicate wake is harmless).
+     */
+    cooldownMs?: number;
+    /**
+     * Per-strand burst-coalescing window for the fan-out: a second activity trigger
+     * within this window is dropped (one wake is enough). Default
+     * {@link DEFAULT_PUSH_DEBOUNCE_MS} (10 s).
+     */
+    debounceMs?: number;
+}
+/** Google service-account fields needed for FCM HTTP v1 OAuth2. */
+export interface FcmCredentials {
+    /** GCP project id → `POST https://fcm.googleapis.com/v1/projects/{projectId}/messages:send`. */
+    projectId: string;
+    /** Service-account email (JWT `iss`/`sub`). */
+    clientEmail: string;
+    /** Service-account RSA private key, PEM. Secret — never logged. */
+    privateKey: string;
+}
+/** Apple APNs auth-key (.p8) fields. */
+export interface ApnsCredentials {
+    /** APNs key id (JWT header `kid`). */
+    keyId: string;
+    /** Apple team id (JWT `iss`). */
+    teamId: string;
+    /** App bundle id → `apns-topic` header. */
+    bundleId: string;
+    /** `.p8` ES256 private key, PEM. Secret — never logged. */
+    privateKey: string;
+    /** `true` → `api.push.apple.com`; false/undefined → `api.sandbox.push.apple.com`. */
+    production?: boolean;
+}
 /**
  * A peer entry in a control network seed.
  * Contains connection information for a cadre peer.
@@ -383,25 +736,11 @@ export interface ControlNetworkSeed {
     partyId: string;
     /** Known peers in the cadre */
     peers: SeedPeer[];
-    /** Optional signed transactions to pre-populate the cache */
-    transactions?: SignedTransaction[];
     /** Signature over the seed by an authority key */
     signature: string;
     /** The authority key that signed this seed */
     signerKey: string;
 }
-/**
- * A signed transaction for inclusion in seeds.
- * Allows pre-populating the control network cache.
- */
-export interface SignedTransaction {
-    /** Transaction ID */
-    id: string;
-    /** Serialized transaction data */
-    data: string;
-    /** Signature over the transaction */
-    signature: string;
-}
 /**
  * Message sent from instigator to new node during seed delivery.
  * Delivered via /sereus/seed/1.0.0 libp2p protocol.
@@ -411,8 +750,6 @@ export interface SeedMessage {
     partyId: string;
     /** Known peers in the cadre */
     peers: SeedPeer[];
-    /** Optional transactions to pre-populate cache */
-    transactions?: SignedTransaction[];
     /** Signature by an authority key */
     signature: string;
     /** The authority key that signed this message */
@@ -427,6 +764,52 @@ export interface SeedAckMessage {
     /** Reason for rejection (if not accepted) */
     reason?: string;
 }
+/**
+ * Request sent over the control network's `WAKE_PROTOCOL` from a same-cadre peer
+ * to a hibernating peer, asking it to bring a strand online and pull pending
+ * activity. The receiver gates this on cadre membership before honoring it.
+ */
+export interface WakeRequest {
+    /** The strand the sender knows has pending activity. */
+    strandId: string;
+    /** Optional cause hint, e.g. `"activity"` (a server saw new traffic) or `"manual"`. */
+    reason?: string;
+}
+/**
+ * Acknowledgment of a {@link WakeRequest}, returned on the same stream.
+ */
+export interface WakeAck {
+    /** Whether the receiver honored the wake (member + participated strand). */
+    accepted: boolean;
+    /** The strand's status after the wake (present when `accepted`). */
+    status?: StrandStatus;
+    /** Reason for rejection (non-member, unknown strand, malformed frame). */
+    reason?: string;
+}
+/**
+ * Control-network request from one of a party's own cadre nodes to a sibling,
+ * asking "what are your live multiaddrs for this strand's separate network?".
+ * Used to seed a strand mesh from co-cadre nodes that already run that strand.
+ * The receiver gates this on cadre membership before answering.
+ */
+export interface StrandAddrRequest {
+    /** The strand whose strand-network address the requester wants to seed from. */
+    strandId: string;
+}
+/**
+ * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
+ * multiaddrs, returned on the same stream.
+ */
+export interface StrandAddrResponse {
+    /** Echoes the requested strand id (empty on a reject/error reply). */
+    strandId: string;
+    /**
+     * Dialable strand-network multiaddr strings (signaling/`p2p-circuit` first);
+     * empty when the responder is a non-member, or does not currently run that
+     * strand, or the exchange failed.
+     */
+    multiaddrs: string[];
+}
 /**
  * Options for authorizing a new peer in the cadre.
  */
@@ -460,6 +843,13 @@ export interface CadreInvite {
     partyId: string;
     /** Multiaddrs to dial the authority */
     authorityAddrs: string[];
+    /**
+     * Authority ed25519 public keys (base64url) of the cadre, carried out-of-band
+     * so a cold-start invitee can pin the trusted authority set before applying
+     * any seed (the seed itself cannot vouch for its own signer). Populated by
+     * `createInvite` from the issuer's `AuthorityKey` table.
+     */
+    authorityKeys?: string[];
     /** Optional invite token for validation */
     token?: string;
     /** Timestamp when invite was created */

package/dist/types.js

@@ -1,26 +1,43 @@
 /**
- * Default hibernation timeouts per latency hint
+ * Default hibernation timeouts per latency hint.
+ *
+ * `checkInInterval` is the BASE delay; `checkInMaxInterval` is the per-hint
+ * ceiling the exponential backoff escalates toward (interactive minutes→~1h,
+ * background minutes→~6h, archive ~1h→~3 days).
  */
 export const HIBERNATION_TIMEOUTS = {
     realtime: {
         idleTimeout: Infinity, // Never idle
         hibernateTimeout: Infinity, // Never hibernate
-        checkInInterval: Infinity // N/A
+        checkInInterval: Infinity, // N/A
+        checkInBackoffFactor: 2,
+        checkInMaxInterval: Infinity // N/A
     },
     interactive: {
         idleTimeout: 5 * 60 * 1000, // 5 minutes
         hibernateTimeout: 15 * 60 * 1000, // 15 minutes after idle
-        checkInInterval: 30 * 1000 // 30 seconds
+        checkInInterval: 30 * 1000, // base: 30 seconds
+        checkInBackoffFactor: 2,
+        checkInMaxInterval: 60 * 60 * 1000 // cap: ~1 hour
     },
     background: {
         idleTimeout: 1 * 60 * 1000, // 1 minute
         hibernateTimeout: 5 * 60 * 1000, // 5 minutes after idle
-        checkInInterval: 5 * 60 * 1000 // 5 minutes
+        checkInInterval: 5 * 60 * 1000, // base: 5 minutes
+        checkInBackoffFactor: 2,
+        checkInMaxInterval: 6 * 60 * 60 * 1000 // cap: ~6 hours
     },
     archive: {
         idleTimeout: 10 * 1000, // 10 seconds
         hibernateTimeout: 30 * 1000, // 30 seconds after idle
-        checkInInterval: 60 * 60 * 1000 // 1 hour
+        checkInInterval: 60 * 60 * 1000, // base: 1 hour
+        checkInBackoffFactor: 2,
+        checkInMaxInterval: 3 * 24 * 60 * 60 * 1000 // cap: ~3 days
     }
 };
+/**
+ * Default duration of the resume-and-probe window during a strand check-in.
+ * See {@link HibernationConfig.checkInWindowMs}.
+ */
+export const DEFAULT_CHECKIN_WINDOW_MS = 15 * 1000;
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAmCA;;GAEG;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,CAAK,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,CAAI,aAAa;KAC5C;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,CAAI,YAAY;KAC/C;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,CAAG,SAAS;KAC5C;CACF,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8DA;;;;;;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;AA4HF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -19,6 +19,10 @@
       },
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./key-store-file": {
+      "types": "./dist/key-store-file.d.ts",
+      "import": "./dist/key-store-file.js"
     }
   },
   "repository": {
@@ -39,6 +43,7 @@
   "scripts": {
     "clean": "rimraf dist",
     "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run",
     "dev:test": "vitest"
   },
@@ -49,7 +54,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
-    "aegir": "^45.2.1",
+    "@vitest/coverage-v8": "^4.0.17",
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
@@ -58,12 +63,13 @@
     "@libp2p/crypto": "^5.1.13",
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
-    "@optimystic/db-core": "^0.13.0",
-    "@optimystic/db-p2p": "^0.13.0",
-    "@optimystic/quereus-plugin-crypto": "^0.13.0",
-    "@optimystic/quereus-plugin-optimystic": "^0.13.0",
-    "@quereus/quereus": "^2.8.0",
-    "@serfab/strand-proto": "^0.6.0",
+    "@multiformats/multiaddr": "^12.5.1",
+    "@optimystic/db-core": "^0.14.1",
+    "@optimystic/db-p2p": "^0.14.1",
+    "@optimystic/quereus-plugin-crypto": "^0.14.1",
+    "@optimystic/quereus-plugin-optimystic": "^0.14.1",
+    "@quereus/quereus": "^4.2.1",
+    "@serfab/quereus-plugin-sereus": "^0.8.1",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"