@serfab/cadre-core 0.12.0 → 1.0.0

package/dist/types.d.ts

@@ -1,14 +1,19 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
 import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
-import type { StrandBackfillConfig } from './strand-backfill.js';
+import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
+import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
+import type { StrandMembershipReconciliationConfig } from './strand-membership-reconciler.js';
+import type { StrandFirstSyncConfig } from './strand-first-sync-gate.js';
 import type { StrandDatabase } from './strand-database.js';
 import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
 import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
 import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
+import type { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { RevocableTable } from './control-authorization.js';
+import type { ControlRetryAbandonment } from './control-retry.js';
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
  * createLibp2pNode after node creation (not surfaced on the base Libp2p type).
@@ -20,7 +25,7 @@ export interface Libp2pNodeWithRepo extends Libp2p {
      * `coordinatedRepo` (`libp2p-node-base.ts`). Optional deliberately: the base
      * factory always assigns it, but it is not part of the upstream node type, so
      * declaring it required would be a claim this repo cannot enforce. The strand
-     * backfill (`strand-backfill.ts`) logs once and stays inert when it is absent.
+     * backfill (`peer-join-backfill.ts`) logs once and stays inert when it is absent.
      */
     keyNetwork?: IPeerNetwork;
 }
@@ -83,12 +88,27 @@ export interface HibernationTimeouts {
 export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts>;
 /**
  * Storage provider - either an `IRawStorage` instance or a factory function.
- * Factory functions are useful for creating strand-specific storage instances.
+ * Factory functions are useful for creating per-scope 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.
+ * **The argument is an opaque scope key.** Use it directly as a file name, directory
+ * name or database name: every key cadre-core mints stays within `[A-Za-z0-9._-]`, so
+ * no escaping is needed and none should be assumed. Do not parse it;
+ * `controlStorageScope` / `isControlStorageScope` (`storage-scope.ts`) are the
+ * supported way to mint and recognize the control key. The strand arm of that charset
+ * rule is intended but not yet checked — a strand id replicated in from another node
+ * in the party reaches this callback verbatim; see
+ * `tickets/backlog/bug-strand-scope-key-charset-unenforced`.
+ *
+ * **Called once per scope per runtime lifetime.** The scopes are the control database
+ * (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.
+ *
+ * **The control scope is party-specific.** It is `controlStorageScope(partyId)`, not a
+ * fixed string, because the control database holds one party's own records — its
+ * strands, owner keys, peers, invitations, revocations. Two parties on one device ask
+ * for two different keys and MUST get two different stores, or a node started for one
+ * party reads the other's rows as its own.
  *
  * 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
@@ -98,33 +118,40 @@ export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeou
  * cadre-core disposes only its own cache wrapper — it never closes the store you
  * returned. Closing the underlying handle stays the embedder's job.
  *
- * Either form is safe with a persistent backend. One instance handed to every scope
+ * **The single-instance form shares data across scopes by construction** — one store
+ * for every strand AND for every party's control database. An embedder that can serve
+ * more than one party must use the factory form. One instance handed to every scope
  * also shares ONE cache wrapper (`wrapStorageWithCache` memoizes per inner instance),
  * which counts its holders: a scope stopping releases only its own claim, and the
- * wrapper is retired when the last scope releases it. The factory form is still the
- * better default for a different reason — it partitions each strand's data, which
+ * wrapper is retired when the last scope releases it. The factory form is the better
+ * default for the further reason that it partitions each strand's data, which
  * simplifies cleanup.
  */
-export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorage);
+export type RawStorageProvider = IRawStorage | ((scope: string) => IRawStorage);
 /**
  * Storage configuration for storage profile nodes
  */
 export interface StorageConfig {
     /**
      * Storage provider - either an IRawStorage instance or a factory function.
-     * See {@link RawStorageProvider} for how often cadre-core calls it.
+     * See {@link RawStorageProvider} for how often cadre-core calls it, and for why
+     * the single-instance form cannot serve more than one party.
+     *
+     * The `scope` a factory receives is an opaque key already safe as a path or
+     * database-name segment (always within `[A-Za-z0-9._-]`), so each example below
+     * interpolates it directly.
      *
      * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
      * ```typescript
      * import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
-     * storage: { provider: (strandId) => new FileRawStorage(`./data/${strandId}`) }
+     * storage: { provider: (scope) => new FileRawStorage(`./data/${scope}`) }
      * ```
      *
      * For React Native, use the appropriate storage from @optimystic/db-p2p-storage-rn:
      * ```typescript
      * import { LevelDBRawStorage } from '@optimystic/db-p2p-storage-rn';
      * // `db` is an open LevelDB handle (see `openOptimysticRNDb` over `rn-leveldb`)
-     * storage: { provider: (strandId) => new LevelDBRawStorage(openDb(`sereus-${strandId}`)) }
+     * storage: { provider: (scope) => new LevelDBRawStorage(openDb(`sereus-${scope}`)) }
      * ```
      *
      * For in-memory storage (testing):
@@ -140,13 +167,36 @@ export interface StorageConfig {
  * Network configuration for libp2p
  */
 export interface NetworkConfig {
+    /**
+     * Addresses this machine's libp2p nodes bind. Omitted, `@optimystic/db-p2p`'s own
+     * default (`/ip4/0.0.0.0/tcp/0`) applies; `[]` means "cannot listen" and is honored
+     * as written (React Native hosts rely on that).
+     *
+     * The machine runs one control node plus one node per strand, so a FIXED port here
+     * can only belong to one of them. The control node binds it as configured; each
+     * strand node binds the same entry with its port rewritten to `0`, keeping the
+     * interface and transport (`/ws`, a specific-interface bind). A
+     * `<relay>/p2p-circuit` entry is untouched — the port inside it is the relay's, not
+     * a local bind. See `strand-network-config.ts`.
+     *
+     * **Only TCP, WebSocket (`/ws`, `/wss`) and circuit-relay addresses are bindable**
+     * unless {@link transports} supplies the factories for something else. A `/ws` entry
+     * switches the WebSocket transport on by itself; anything else — `/quic-v1`,
+     * `/webrtc`, `/webtransport` — refuses node start naming the address and the libp2p
+     * package it would need, rather than being dropped in silence by libp2p's transport
+     * manager. See `relay-addrs.ts` → `resolveTransportOptions`.
+     */
     listenAddrs?: string[];
     /**
      * Addresses to advertise to peers **instead of** `listenAddrs` — for a node behind
      * NAT or a reverse proxy that is reachable at a different address than it binds
      * (e.g. `mynode.example.com:4001` in front of a `0.0.0.0:4001` listener). Reaches
-     * libp2p's `addresses.announce` via `@optimystic/db-p2p`'s `NodeOptions.announceAddrs`,
-     * on this node's control node and on every strand node it runs.
+     * libp2p's `addresses.announce` via `@optimystic/db-p2p`'s `NodeOptions.announceAddrs`.
+     *
+     * **Applies to this machine's CONTROL node only.** Strand nodes drop it: any concrete
+     * entry names a port, and that port is the control node's, so a strand node
+     * advertising it would send peers to the wrong node (`strand-network-config.ts`).
+     * Entries are still validated at node start whichever node ends up using them.
      *
      * **A non-empty value REPLACES the advertised set entirely.** Observed addresses,
      * and the `/p2p-circuit` address earned from a {@link relayAddrs} reservation, are
@@ -177,6 +227,8 @@ export interface NetworkConfig {
      * advertise. Reaches libp2p's `addresses.appendAnnounce` via
      * `@optimystic/db-p2p`'s `NodeOptions.appendAnnounceAddrs`.
      *
+     * **Control node only**, on the same terms as {@link announceAddrs}.
+     *
      * **Ignored while {@link announceAddrs} is non-empty** — that is libp2p's own
      * precedence, applied upstream; this repo does not merge the two locally. Set one
      * or the other, not both.
@@ -197,8 +249,9 @@ export interface NetworkConfig {
      * because a listener that dials its relay from inside `libp2p.start()` put a
      * sibling in this node's cohort before its own database existed, and a sibling
      * that had not yet replicated this node's membership row refused the bring-up.
-     * STRAND nodes inherit the older per-relay `<relay>/p2p-circuit` listener, which
-     * has no such ordering hazard. A relay named here also becomes a
+     * STRAND nodes take the same search shape, one bare listener plus one reservation
+     * supervisor PER relay, fail-soft (`strand-network-config.ts`,
+     * `strand-instance-manager.ts`). A relay named here also becomes a
      * delegate-announce target, so this node's strand nodes may reserve on it too
      * (see `delegate-admission.ts`).
      *
@@ -208,11 +261,46 @@ export interface NetworkConfig {
      * must not acquire a listener by accident.
      *
      * FAIL-FAST both ways: a malformed entry throws at node start rather than being
-     * silently dropped, and a first reservation attempt that lands no
-     * `/p2p-circuit` address throws `RelayReservationFailedError` out of `start()`.
-     * The fail-soft posture over the same machinery is `CadreNode.reserveRelays()`.
+     * silently dropped, and — while {@link requireRelay} stays at its default —
+     * a first reservation attempt that lands no `/p2p-circuit` address throws
+     * `RelayReservationFailedError` out of `start()`. The fail-soft posture over
+     * the same machinery is `CadreNode.reserveRelays()`.
      */
     relayAddrs?: string[];
+    /**
+     * Must a relay named in {@link relayAddrs} have granted a reservation before
+     * `start()` is allowed to succeed? Default `true`: an operator who names a
+     * relay is telling this machine it has no other reachability, so a relay
+     * that will not have us on the first attempt should stop the boot loudly
+     * rather than leave a node nobody can reach.
+     *
+     * Set `false` for a node that must still boot with no network — a phone or a
+     * browser tab. The first attempt is still driven at the same point in
+     * `start()`; a lost reservation just logs instead of throwing, and the
+     * retry supervisor keeps trying in the background exactly as it does after a
+     * `CadreNode.reserveRelays()` call. A caller on this posture cannot infer
+     * dialability from `start()` resolving — read
+     * {@link CadreNode.getRelayReservationState} to find out.
+     *
+     * It buys a node that BOOTS, not a node that boots fast: `start()` still waits
+     * out that first attempt, which costs the drive's whole timeout
+     * (`DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, 10 s) against a relay that is unreachable
+     * rather than merely refusing (`relay-reservation.ts` polls to the deadline, in
+     * case libp2p's own discovery lands a reservation independently).
+     *
+     * Softens only the RESERVATION half of {@link relayAddrs}'s fail-fast
+     * contract. A malformed `relayAddrs` entry still throws at config
+     * resolution regardless of this setting — a typo is an operator error
+     * whatever the posture — and a hand-written `<relay>/p2p-circuit` entry in
+     * {@link listenAddrs} is still rejected on the control node, since that
+     * rejection is about the listener shape, not about whether reachability is
+     * required.
+     *
+     * Has no effect on STRAND nodes, which are already fail-soft over
+     * `relayAddrs` regardless of this field (`strand-network-config.ts`,
+     * `strand-instance-manager.ts`).
+     */
+    requireRelay?: boolean;
     /**
      * Enable circuit relay server - allows this node to relay connections for other peers.
      * When undefined, defaults to true for storage profile nodes (they typically have
@@ -270,8 +358,14 @@ export interface NetworkConfig {
      * On the CONTROL node this gater is composed with the built-in membership
      * admission gate (`membership-connection-gater.ts`): every hook supplied here
      * is honored unchanged, and on inbound encrypted connections a deny from
-     * either this gater or the membership policy denies. Strand cohort nodes
-     * receive this gater as-is (their peers are legitimately cross-party).
+     * either this gater or the membership policy denies.
+     *
+     * Strand cohort nodes: an OPEN strand's node receives this gater as-is (its
+     * peers are legitimately cross-party). A CLOSED strand's node composes
+     * revoked-peer denial onto it (`strand-revocation-enforcer.ts`) — every hook
+     * supplied here is still honored unchanged, and on the composed hooks
+     * (inbound encrypted connection, outbound peer dial, relay reservation) a
+     * deny from either this gater or the revocation check denies.
      */
     connectionGater?: ConnectionGater;
     /**
@@ -281,7 +375,8 @@ export interface NetworkConfig {
      * Every field is optional; omit for the defaults
      * ({@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE} /
      * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS} /
-     * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} / `STRAND_PEER_ADDR_REFRESH_MS`).
+     * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} /
+     * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS} / `STRAND_PEER_ADDR_REFRESH_MS`).
      */
     controlCohort?: {
         /**
@@ -296,12 +391,20 @@ export interface NetworkConfig {
          */
         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}.
+         * Limit on dialing ONE peer — all of its candidate addresses together — in
+         * ms. Bounds a reconcile pass at (dialed siblings) × this. The same limit
+         * applies to the owner dials of `applySeed` and to `dialInvite`. Defaults to
+         * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}.
          */
         dialTimeoutMs?: number;
+        /**
+         * Limit on ONE candidate address's dial attempt, in ms, inside
+         * {@link dialTimeoutMs}. Each address is dialed on its own under this limit,
+         * so an address that never answers cannot use up the time the peer's other
+         * addresses needed. Defaults to
+         * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}.
+         */
+        perAddressDialTimeoutMs?: 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,
@@ -352,8 +455,14 @@ export interface ControlNetworkConfig {
  * by omission); the strand breadth defaults to
  * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
  * {@link STRAND_CLUSTER_POLICY}.
+ *
+ * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
+ * corroboration yardstick declared from the machines enrolled in this party
+ * ({@link resolveRepairYardstick}); handed no count, each returns its frozen base
+ * constant unchanged. A network picks the derived number up when its libp2p node is
+ * built, which for a strand is every wake from hibernation.
  */
-export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize } from '@serfab/quereus-plugin-sereus';
+export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } from '@serfab/quereus-plugin-sereus';
 /**
  * Main configuration for a CadreNode
  */
@@ -414,17 +523,72 @@ export interface CadreNodeConfig {
      */
     strandClusterSize?: number;
     /**
-     * Tuning for the strand peer-join block catch-up (see `strand-backfill.ts`):
+     * Tuning for the strand peer-join block catch-up (see `peer-join-backfill.ts`):
      * when a strand's libp2p node connects to a peer this runtime has not yet
      * caught up, every block in the strand's own raw store is pushed to that peer,
      * so a machine that joined the strand after blocks were committed still ends
-     * up physically holding them. Applies to every strand this node starts;
-     * strand-only — the control network has its own row-level re-issue queue
-     * (`drainPendingControlReplication`). Omit for the defaults
-     * (`DEFAULT_STRAND_BACKFILL`); `{ enabled: false }` restores the
-     * no-backfill behaviour.
+     * up physically holding them. Applies to every strand this node starts.
+     * Omit for the defaults (`DEFAULT_PEER_JOIN_BACKFILL`); `{ enabled: false }`
+     * restores the no-backfill behaviour. The control network runs its own,
+     * separately tuned catch-up — see {@link controlBackfill}.
+     */
+    strandBackfill?: PeerJoinBackfillConfig;
+    /**
+     * Tuning for the CONTROL network's peer-join block catch-up (same module,
+     * `peer-join-backfill.ts`, wired in `CadreNode.start`): when the control
+     * libp2p node connects to an AUTHORIZED party member this runtime has not yet
+     * caught up, every block in the control database's own raw store is pushed to
+     * it. This is what makes a control block committed while the writer was alone
+     * (collection headers written at genesis above all) physically reach members
+     * that joined later — without it, such a member that restarts offline reads
+     * the affected tables as empty. Pushes are gated on
+     * `CadreNode.isAuthorizedMember`, checked at push time, because the control
+     * network's inbound gate deliberately admits non-members in several states
+     * (seed delivery, enrollment, bootstrap/relay peers). Omit for the defaults
+     * (`DEFAULT_PEER_JOIN_BACKFILL`); `{ enabled: false }` disables it.
      */
-    strandBackfill?: StrandBackfillConfig;
+    controlBackfill?: PeerJoinBackfillConfig;
+    /**
+     * Tuning for the CLOSED-strand revoked-peer gate
+     * (`strand-revocation-enforcer.ts`), applied to every closed strand this node
+     * starts: each strand node materializes the peer ids bound to REMOVED members
+     * (orphaned `Strand.MemberPeer` rows) and refuses them at the stream and
+     * connection layers, so removing a party cuts the network to its machines
+     * rather than only deleting its row. Open strands never arm it. Omit for the
+     * defaults (`DEFAULT_REVOCATION_POLL_INTERVAL_MS` refresh cadence);
+     * `{ enabled: false }` restores the pre-existing behaviour.
+     */
+    strandRevocationEnforcement?: StrandRevocationEnforcementConfig;
+    /**
+     * Tuning for the CLOSED-strand membership reconciler
+     * (`strand-membership-reconciler.ts`), applied to every closed strand this
+     * node launches with a party identity key: at bring-up each machine redeems a
+     * pending formation invitation (seating the party's `Strand.Member` row) and
+     * writes its own machine→party `Strand.MemberPeer` binding, retrying in the
+     * background without blocking bring-up. `pollIntervalMs` is the IDLE cadence
+     * (how often a machine nobody has admitted re-checks) and the cap of the
+     * unfinished-join retry ladder, NOT the retry cadence itself — an unfinished
+     * join retries from 1 s, doubling. Omit for the defaults (it mirrors
+     * {@link strandRevocationEnforcement}'s `pollIntervalMs`);
+     * `{ enabled: false }` disarms the loop — for test fixtures that hand-drive
+     * the membership writers and assert exact row sets.
+     */
+    strandMembershipReconciliation?: StrandMembershipReconciliationConfig;
+    /**
+     * Tuning for the JOINING machine's first-sync write gate
+     * (`strand-first-sync-gate.ts`), applied to every strand this node launches as a
+     * non-founder: the strand's database is withheld from the app (`StrandInstance.database`
+     * unset, status `'syncing'`) until the strand's `Strand.Header` has been received from
+     * another member and every `App` table has been read once, because a machine that writes
+     * to a table it has never fetched creates a private copy of it that never merges.
+     * `timeoutMs` bounds how long {@link CadreNode.addStrand} waits before rejecting with
+     * `StrandAwaitingFirstSyncError` (retryable — the launch stays up and keeps probing);
+     * `pollIntervalMs` is the probe cadence. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`, 30 s;
+     * `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`, 500 ms). There is deliberately no way to disable
+     * the gate: a machine that already holds the Header is never gated, so nothing that works
+     * today is blocked by it.
+     */
+    strandFirstSync?: StrandFirstSyncConfig;
     /** Hibernation configuration */
     hibernation?: HibernationConfig;
     /** Polling interval for strand watcher in ms (default: 5000) */
@@ -508,6 +672,39 @@ export interface CadreNodeConfig {
          */
         store?: BootstrapPeerStore;
     };
+    /**
+     * Node-local record of how many machines this party had enrolled the last time
+     * this node looked (see `enrolled-machine-store.ts`): the block-repair
+     * corroboration yardstick the CONTROL node declares when its libp2p node is
+     * built. Sibling of {@link trustedOwners} / {@link bootstrapPeers} — same
+     * NON-replicated, per-party, injected-backend shape — and, like
+     * {@link bootstrapPeers}, nothing here is trust-bearing: it is a repair hint,
+     * recomputed from `CadrePeer` rows the moment the control database is up.
+     *
+     * It exists only because the control node is created BEFORE that database, so
+     * the live count is unreadable at the one moment it is needed; remembering it
+     * across the restart is what breaks that deadlock. Absent ⇒ an in-memory store
+     * is created at start(), which cold-starts on every launch and therefore
+     * declares nothing — byte-for-byte the behaviour before this record existed.
+     * No embedder is forced to change.
+     *
+     * A party that grows applies the larger number on each node's NEXT launch,
+     * deliberately: Optimystic freezes the policy at node construction and offers
+     * no runtime setter, and a node still holding the old value runs at exactly
+     * today's behaviour, so there is no forced rebuild.
+     *
+     * A new platform needs no new store class: supply a `DurableSlot` for the
+     * platform's storage and inject `PersistentEnrolledMachineStore.open(slot, partyId)`.
+     */
+    enrolledMachines?: {
+        /**
+         * Injected store instance — e.g. a `FileEnrolledMachineStore` from the
+         * Node-only subpath `@serfab/cadre-core/enrolled-machine-store-file`,
+         * persisted in the node's state directory. Its `partyId` must match
+         * `controlNetwork.partyId`; start() fails closed on a mismatch.
+         */
+        store?: EnrolledMachineStore;
+    };
     /**
      * Platform push-delivery for suspended mobile peers. When present, the node's
      * server fan-out can deliver strand-wake data messages over the platform push
@@ -537,9 +734,16 @@ export interface CadreNodeConfig {
     };
 }
 /**
- * Status of a strand instance
+ * Status of a strand instance.
+ *
+ * `'syncing'` is a JOINING machine whose runtime is up (strand libp2p node, background
+ * loops) but whose database is held back from the app until the strand's `Strand.Header`
+ * has been received from another member — see `strand-first-sync-gate.ts`. In that state
+ * `StrandInstance.database` is unset; the instance goes `'active'` (and `CadreNode` emits
+ * `strand:writable`) the moment the Header is readable. A founder, or a machine that has
+ * synced this strand before (restart, hibernation resume), never passes through it.
  */
-export type StrandStatus = 'starting' | 'active' | 'idle' | 'hibernating' | 'stopping' | 'stopped' | 'error';
+export type StrandStatus = 'starting' | 'syncing' | 'active' | 'idle' | 'hibernating' | 'stopping' | 'stopped' | 'error';
 /**
  * App information from strand header
  */
@@ -556,9 +760,15 @@ export interface StrandInstance {
     strandId: string;
     status: StrandStatus;
     sAppInfo?: SAppInfo;
-    /** The libp2p node for this strand (only when active/idle) */
+    /** The libp2p node for this strand (only when live: syncing/active/idle) */
     libp2pNode?: Libp2p;
-    /** The Quereus database for this strand (only when active/idle) */
+    /**
+     * The Quereus database for this strand — set only while the strand is live AND
+     * this machine may write to it. A joining machine that has not yet received the
+     * strand's `Strand.Header` from another member runs with `libp2pNode` set and this
+     * unset (status `'syncing'`); it is published when the Header arrives
+     * (`strand:writable`). Unset while hibernating.
+     */
     database?: StrandDatabase;
     /** Membership info for closed strands */
     memberKey?: string;
@@ -600,6 +810,17 @@ export interface StrandRow {
     Id: string;
     MemberPrivateKey: string | null;
     Type: 'o' | 'c';
+    /**
+     * ed25519 (base64url) owner key of the MACHINE that published this row — the
+     * signer of the owner-signed `Strand` insert (`== context.OwnerKey`, pinned by
+     * the schema's `AuthorizedInsert`). Identifies the founding machine, so a
+     * launch with no explicit `founder` flag derives "am I the founder?" by
+     * comparing it to the node's own owner key (see `CadreNode.launchStrand`).
+     * `null` on a consent-seated strand (the unsigned `FormationUsage` branch
+     * records no trustworthy signer). Provenance, not content —
+     * `strandRowMismatches` excludes it from the identical-content comparison.
+     */
+    FounderOwnerKey: string | null;
 }
 /**
  * sApp configuration provided by the hosting application when creating a strand.
@@ -637,10 +858,93 @@ export interface StrandConfig {
      * 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`+`Manager`). A joiner leaves this
-     * `false`/unset and writes nothing — it receives those rows via Optimystic sync.
-     * Defaults to `false`.
+     * unset and writes nothing — it receives those rows via Optimystic sync.
+     *
+     * When unset, founder-ness is DERIVED from the row: this node founds iff
+     * {@link StrandRow.FounderOwnerKey} equals its own owner key. An explicit
+     * `true`/`false` wins over the derivation — the formation/responder flows pass
+     * it deliberately, since a consent-seated row carries a null column.
      */
     founder?: boolean;
+    /**
+     * THIS party's own strand membership private key (base64 protobuf, as
+     * `generateStrandMemberKey` mints) for a CLOSED strand — the identity whose public
+     * key seats the founding `Member`/`Manager`. The explicit sibling of
+     * {@link founder}: normally the launch reads it from the party's control-layer
+     * `StrandPartyKey` row (minting one on the founding machine when absent), and an
+     * explicit value here WINS over that read — for callers whose row carries no
+     * founder provenance to heal against (an explicit `founder: true` over a hand-built
+     * row, as the test harness does). Deliberately NOT
+     * {@link StrandRow.MemberPrivateKey}, the strand-wide read secret every joining
+     * party receives — that key derives nobody's identity.
+     */
+    partyMemberPrivateKey?: string;
+    /**
+     * Whether {@link CadreNode.addStrand} waits for a JOINING machine's first sync before it
+     * resolves. Default `true`: the returned instance is writable (`database` set, status
+     * `'active'`), or the call rejects with `StrandAwaitingFirstSyncError` after
+     * `CadreNodeConfig.strandFirstSync.timeoutMs` — retryable, the launch stays up. `false`
+     * returns as soon as the runtime is launched, possibly `'syncing'` with no `database`;
+     * the caller then wires its own peers (a hand-dialed test fixture) and awaits
+     * {@link CadreNode.whenStrandWritable} or the `strand:writable` event. A founder, or a
+     * machine that already holds the strand's `Strand.Header`, is never gated either way.
+     */
+    awaitFirstSync?: boolean;
+}
+/**
+ * What {@link CadreNode.foundStrand} needs to publish a strand's control row AND start it
+ * locally as its founder — the resumable one-call form of `publishStrand` + `addStrand`.
+ *
+ * No `strandRow`: the row is the OUTPUT of founding, either freshly published or read back
+ * from an interrupted earlier attempt. `StrandConfig` (the join/attach shape) takes one
+ * because there the row already exists and came from the control network.
+ */
+export interface FoundStrandConfig {
+    /** Unique strand identifier. Trimmed; blank is rejected. */
+    strandId: string;
+    /** `'o'` for open (default) or `'c'` for closed. */
+    type?: 'o' | 'c';
+    /**
+     * Membership key gating a closed strand. Required in practice for `type: 'c'` (the
+     * founder bootstrap rejects a null key), and IGNORED when the strand is already
+     * published — the stored key wins, so read the resolved key back off the returned
+     * instance rather than trusting a freshly minted one.
+     */
+    memberPrivateKey?: string;
+    /** sApp configuration the hosting application provides, as for {@link StrandConfig}. */
+    sAppConfig: SAppConfig;
+    /**
+     * Forwarded to the attach ({@link StrandConfig.awaitFirstSync}). Matters only when the
+     * call ATTACHES rather than founds — the stored row was published by a sibling machine
+     * that won the founding race — in which case this machine is a joiner whose database
+     * is withheld until that sibling's `Strand.Header` reaches it; default `true` waits
+     * for that inside the call. A founding launch is never gated.
+     */
+    awaitFirstSync?: boolean;
+}
+/**
+ * What {@link CadreNode.foundStrand} hands back: the running instance PLUS the `Strand` row
+ * the strand actually runs under.
+ *
+ * The row is returned separately rather than left for the caller to read off the instance
+ * because on a resumed founding it is NOT the caller's input — a closed strand adopts the
+ * stored `MemberPrivateKey`, discarding a freshly minted one. A caller that must carry the
+ * membership key onward (to mint an invitation, say) reads it from HERE.
+ */
+export interface FoundStrandResult {
+    /** The active local instance, as {@link CadreNode.addStrand} would have returned. */
+    instance: StrandInstance;
+    /** The live control-plane row: freshly published, or the one already there. */
+    strandRow: StrandRow;
+    /**
+     * Whether THIS machine actually founded (ran / will have run the one-time
+     * founder bootstrap). `false` when the resolved row was published by a
+     * DIFFERENT machine's owner key — e.g. a sibling won a concurrent founding
+     * race — in which case the call attached as a joiner instead, which is the
+     * correct outcome (two machines bootstrapping one strand on separate replicas
+     * is the double-`Header` hazard).
+     */
+    founded: boolean;
 }
 /**
  * Result of creating a new cadre peer
@@ -682,6 +986,26 @@ export interface OpenInvitation {
     /** Bootstrap addresses to contact the inviter's cadre */
     bootstrap: string[];
 }
+/**
+ * A single-use strand membership invitation carried on a closed-strand formation
+ * result: the `Strand.Invite` keypair the responder (the host strand's founder party)
+ * issued for this redemption. The joiner spends it — `consumeInvite` on its own strand
+ * replica — to seat a `Strand.Member` row under its OWN party key, so joining no longer
+ * hands out the founder's identity. Structurally identical to
+ * `strand-membership-writer`'s `IssuedInvite`; declared here so the wire/type layer does
+ * not import the writer.
+ */
+export interface StrandMembershipInvite {
+    /** The invite ed25519 PUBLIC key (base64url) — the `Strand.Invite.Key` row. */
+    inviteKey: string;
+    /**
+     * The invite ed25519 PRIVATE seed (base64url). A single-use bearer credential:
+     * whoever holds it can `consumeInvite` exactly once. Same sensitivity class and
+     * handling as `memberPrivateKey` — delivered only inside the validated,
+     * post-approval formation result, never written to either side's control DB.
+     */
+    invitePrivateKey: string;
+}
 /**
  * Result of forming a strand via open invitation
  */
@@ -699,6 +1023,30 @@ export interface FormStrandResult {
      * from {@link invitePrivateKey} (the initiator's own generated signing key).
      */
     memberPrivateKey?: string;
+    /**
+     * The joiner's own single-use membership invitation into the (closed, bound) host
+     * strand — see {@link StrandMembershipInvite}. Present only when the responder's
+     * host strand is closed and its runtime issued one; absent for open strands and the
+     * responder-provisions (unbound) path. `CadreNode.formStrand` itself persists the
+     * joiner's party key and caches this invitation for the strand bring-up to redeem,
+     * so an embedding app normally never touches it.
+     */
+    membershipInvite?: StrandMembershipInvite;
+    /**
+     * The responder's live STRAND-network multiaddrs for the formed strand — the only
+     * cross-party discovery seed there is, since the strand-addr RPC that resolves a
+     * sibling's strand addresses answers own-party callers only.
+     *
+     * Always an array, frequently EMPTY: the responder discloses none when it holds no
+     * live strand node for the strand it just provisioned (the responder-provisions path
+     * mints a strand that has not launched yet). `CadreNode.formStrand` records these
+     * itself, so an embedding app only needs them to seed a strand it launches OUTSIDE
+     * that node.
+     *
+     * One-shot and in-memory: they are the responder's addresses at the moment of
+     * formation and are never re-resolved — see `docs/strands.md`.
+     */
+    strandAddrs: string[];
 }
 /**
  * Disclosure object provided during strand formation.
@@ -751,12 +1099,62 @@ export interface CadreNodeEvents {
     'strand:waking': {
         strandId: string;
     };
+    /**
+     * Emitted when a strand that came up `'syncing'` — a joining machine whose database was
+     * withheld until it received the strand's `Strand.Header` from another member — becomes
+     * writable: `StrandInstance.database` is now set and the status is `'active'`. A strand
+     * whose `strand:started` already reported `'active'` (a founder, or a machine that had
+     * synced before) never emits this. The event form of what {@link CadreNode.addStrand}
+     * awaits; an app that attaches without waiting (`awaitFirstSync: false`, or a strand the
+     * watcher auto-launched) hangs its "waiting for the other member" screen on the pair.
+     */
+    'strand:writable': {
+        strandId: string;
+    };
+    /**
+     * Emitted when this node discovers it is no longer a member of a CLOSED
+     * strand — its party was removed by a manager, or it left. Detected by the
+     * strand's revoked-peer gate (`strand-revocation-enforcer.ts`) seeing this
+     * node's own peer id in the revoked set, so it is BEST-EFFORT: it fires only
+     * if the removal replicated here before the rest of the strand cut us off,
+     * and a node that was already offline may never see it at all.
+     *
+     * Nothing is stopped or torn down for you. Treat it as "this strand will no
+     * longer sync": remaining members refuse this node's streams, dials, and
+     * connections, so reads keep working against whatever is stored locally while
+     * writes stop propagating. Stopping the strand (`stopStrand`) or deleting its
+     * data is the app's decision. Emitted once per removal — re-armed if a manager
+     * re-admits this party, so a second removal is reported again — and a
+     * hibernation wake rebuilds the gate, which may re-emit for a strand still
+     * revoked.
+     */
+    'strand:revoked': {
+        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.
+     * registered `sAppConfig` for — i.e. a strand created by another member, or
+     * one this node ran in a previous session (sApp configs are in-memory only and
+     * do not survive `stop()`). 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.
+     *
+     * **Fired exactly ONCE per strand per session, and it can fire before your
+     * listener is attached.** The strand watcher's first poll runs inside
+     * `CadreNode.start()` (100 ms after the watcher starts), so every strand
+     * already stored for this party is normally offered while the embedding app is
+     * still inside its own `start()` await. The watcher then records the strand as
+     * seen and no later poll re-offers it, so a listener attached a moment late
+     * misses those strands for the life of the process.
+     *
+     * So an app that auto-joins discovered strands must **subscribe first, then
+     * drain `CadreNode.getDiscoveredStrands()`** — the map of strands no local
+     * config claims. In that order a strand discovered between the two steps is
+     * handled twice rather than not at all, which is why the join handler needs to
+     * be idempotent (guard on an in-flight set, not only on
+     * `getStrands().has(id)` — the strand manager tracks an instance only once
+     * `addStrand` has resolved).
      */
     'strand:discovered': {
         strandId: string;
@@ -764,6 +1162,25 @@ export interface CadreNodeEvents {
     };
     'control:connected': void;
     'control:disconnected': void;
+    /**
+     * Emitted when the control-write retry funnel GAVE UP on a local control write — the
+     * classifier declined the failure as non-transient, or every attempt (or the elapsed
+     * budget) ran out. One event per abandoned write, carrying the operation label, how far
+     * it got, why it stopped and the error.
+     *
+     * Exists because an abandoned BACKGROUND write is otherwise invisible: the node's own
+     * self-address republish, the post-connect drain and the replication drain all fire
+     * their writes unawaited with a `debug`-only catch, and that namespace is off unless
+     * something enabled it — so the write is lost and nobody is told. A FOREGROUND write's
+     * caller sees the rethrown error as well as this event.
+     *
+     * What an app does with it is its own call; the node itself only escalates ONE case to
+     * the operator (a self-address republish that has been failing longer than a peer
+     * record stays fresh, at which point other machines are already discarding this node's
+     * address). Treat the rest as telemetry — a control write that was lost, not a strand
+     * or connection state change.
+     */
+    'control:write-abandoned': ControlRetryAbandonment;
     /** Emitted when a seed is received via the seed protocol */
     'seed:received': {
         partyId: string;
@@ -837,6 +1254,8 @@ export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | '
  * `ControlDatabase.queryRevocations`: the identity triple plus the `ReissuedAt`
  * counter an owner bumps (`ControlDatabase.reissueRevocations`) to re-write — and
  * therefore re-broadcast — a tombstone that committed while the node was alone.
+ * Never the ledger marker: that row names no guarded table, and `queryRevocations`
+ * skips it, which is what keeps `tableName` a {@link RevocableTable}.
  */
 export interface RevocationRow {
     /** Which guarded table's stamp was retired. */
@@ -848,6 +1267,13 @@ export interface RevocationRow {
     /** Monotonic re-issue counter; carries no semantics (see the schema comment). */
     reissuedAt: number;
 }
+/**
+ * Outcome of `ControlDatabase.openRevocationLedger`: `'opened'` when this call filed the
+ * singleton `Revocation` ledger marker, `'already-open'` when it was already filed (seen
+ * by the in-lock guard, or filed first by another owner and refused on the primary key).
+ * Either way the marker exists afterwards.
+ */
+export type RevocationLedgerOpenResult = 'opened' | 'already-open';
 /**
  * Outcome of {@link CadreNode.registerSelf}, surfaced so callers (e.g. the CLI
  * `--owner` branch) can log what happened: