@serfab/cadre-core 0.12.0 → 1.0.0

package/src/types.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
@@ -21,7 +26,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;
 }
@@ -113,12 +118,27 @@ export 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
@@ -128,14 +148,16 @@ export const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts> = {
  * 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
@@ -143,19 +165,24 @@ export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorag
 export interface StorageConfig {
   /**
    * Storage provider - either an IRawStorage instance or a factory function.
-   * See {@link RawStorageProvider} for how often cadre-core calls it.
+   * 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):
@@ -172,13 +199,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
@@ -209,6 +259,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.
@@ -229,8 +281,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`).
    *
@@ -240,11 +293,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
@@ -302,8 +390,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;
   /**
@@ -313,7 +407,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?: {
     /**
@@ -328,12 +423,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,
@@ -388,6 +491,12 @@ 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,
@@ -395,7 +504,10 @@ export {
   CONTROL_CLUSTER_POLICY,
   DEFAULT_STRAND_CLUSTER_SIZE,
   STRAND_CLUSTER_POLICY,
-  resolveStrandClusterSize
+  resolveStrandClusterSize,
+  resolveRepairYardstick,
+  controlClusterPolicy,
+  strandClusterPolicy
 } from '@serfab/quereus-plugin-sereus';
 
 /**
@@ -467,17 +579,76 @@ 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.
+   */
+  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.
    */
-  strandBackfill?: StrandBackfillConfig;
+  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;
@@ -568,6 +739,40 @@ 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
@@ -598,15 +803,23 @@ 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' 
+export type StrandStatus =
+  | 'starting'
+  | 'syncing'
+  | 'active'
+  | 'idle'
+  | 'hibernating'
+  | 'stopping'
+  | 'stopped'
   | 'error';
 
 /**
@@ -627,10 +840,16 @@ export interface StrandInstance {
   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 */
@@ -678,6 +897,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;
 }
 
 /**
@@ -717,10 +947,95 @@ 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;
 }
 
 /**
@@ -775,6 +1090,27 @@ export interface OpenInvitation {
   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
  */
@@ -792,6 +1128,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[];
 }
 
 /**
@@ -834,16 +1194,81 @@ export interface CadreNodeEvents {
   'strand:idle': { strandId: string };
   'strand:hibernating': { strandId: string };
   '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; strand: StrandRow };
   '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; peerId: string };
   /** Emitted when a seed is successfully applied */
@@ -916,6 +1341,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. */
@@ -928,6 +1355,14 @@ export interface RevocationRow {
   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: