@serfab/cadre-core 0.9.0 → 0.10.0

package/src/trusted-owner-store-file.ts

@@ -0,0 +1,41 @@
+/**
+ * Node-only file-backed {@link TrustedOwnerStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated
+ * trusted-owner anchor.
+ *
+ * Nothing but the file itself lives here: the anchor's envelope, load policy,
+ * per-entry validation and serialised snapshot writes are cross-platform in
+ * `PersistentTrustedOwnerStore` / `node-local-snapshot.ts`, and the file is a
+ * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of
+ * the package's cross-platform default entry (`./index.js`) — import it from
+ * the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileTrustedOwnerStore } from '@serfab/cadre-core/trusted-owner-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the
+ * `node:fs` edge never reaches a bundler that cannot satisfy it (same
+ * isolation pattern as `key-store-file.ts`).
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentTrustedOwnerStore } from './trusted-owner-store.js';
+import type { TrustedOwnerStore } from './trusted-owner-store.js';
+
+/** Base name of the anchor file: `<dir>/trusted-owners.<encoded partyId>.json`. */
+const SLOT_NAME = 'trusted-owners';
+
+/**
+ * File-backed {@link TrustedOwnerStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it; an absent, corrupt, or wrong-party file is a cold
+ * start (empty anchor), while a present-but-unreadable file throws. Those rules
+ * and their reasoning live on `NodeLocalSnapshot.open` — they are properties of
+ * every persistent backend, not of this one.
+ */
+export const FileTrustedOwnerStore = {
+	/** Load (or cold-start) the party's anchor from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<TrustedOwnerStore> {
+		return PersistentTrustedOwnerStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};

package/src/trusted-owner-store.ts

@@ -0,0 +1,171 @@
+/**
+ * Node-local, NON-replicated trusted-owner anchor.
+ *
+ * The replicated `CadreControl.OwnerKey` table cannot anchor trust: any
+ * connecting node can genesis-insert its own key into its local table and that
+ * row replicates into every peer's copy, so "is this key in `OwnerKey`?" can be
+ * made true by a stranger. This store is the anchor that CAN be trusted — a
+ * per-party, on-device record of owner keys established OUT OF BAND: founding
+ * the party (genesis self-trust), the pinned keys carried by the `CadreInvite`
+ * that enrolled this node, or an explicit operator pin. It is never written
+ * from replicated control state; that is the whole point.
+ *
+ * Three implementations:
+ *  - {@link MemoryTrustedOwnerStore} (this module, cross-platform) — ephemeral;
+ *    the default when no store is injected via `CadreNodeConfig.trustedOwners`.
+ *  - {@link PersistentTrustedOwnerStore} (this module, cross-platform) — durable
+ *    over any `DurableSlot` the embedding app supplies (IndexedDB, SecureStore,
+ *    SQLite, …). The load/persist policy lives in `node-local-snapshot.ts`; read
+ *    {@link NodeLocalSnapshot.open} for what an absent, corrupt, foreign-party
+ *    or unreadable slot does.
+ *  - `FileTrustedOwnerStore` — the above over a Node file in the node's state
+ *    directory; Node-only, behind the subpath
+ *    `@serfab/cadre-core/trusted-owner-store-file` (same isolation pattern as
+ *    `key-store-file`) so `node:fs` never lands in the RN/browser entry graph.
+ *
+ * Keys are additive: nothing in this interface removes a key (owner revocation
+ * is out of scope here and tracked with the broader control-sync design).
+ */
+import debug from 'debug';
+import { NodeLocalSnapshot, type DurableSlot, type NodeLocalSnapshotSpec } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:trusted-owner-store');
+
+/** How an owner key entered the anchor (out-of-band provenance). */
+export type TrustSource = 'genesis' | 'invite' | 'operator';
+
+export interface TrustedOwnerStore {
+	/** Party this anchor is scoped to. */
+	readonly partyId: string;
+
+	/** Is this ed25519 (base64url) key one of my party's out-of-band-trusted owners? */
+	has(ownerKey: string): boolean;
+
+	/**
+	 * All anchored owner keys (e.g. for seed-trust `knownOwnerKeys`).
+	 *
+	 * NOTE: every backend copies into a fresh Set per call (so the result is a
+	 * snapshot decoupled from later `trust()` calls). Anchors hold a handful of
+	 * keys and callers are per-seed, so the copy is free today; if a hot path
+	 * ever calls this per message, prefer `has()` or cache the snapshot.
+	 */
+	all(): ReadonlySet<string>;
+
+	/**
+	 * Add a key established out of band (genesis self-trust / invite pin /
+	 * operator pin). Idempotent: re-trusting a known key is a no-op that keeps
+	 * the original source. Implementations MUST reflect the key in {@link has} /
+	 * {@link all} synchronously; the returned promise tracks durability only
+	 * (a persistent backend's write), so a synchronous caller may safely consult
+	 * the store right after invoking this.
+	 */
+	trust(ownerKey: string, source: TrustSource): Promise<void>;
+}
+
+/**
+ * Ephemeral in-memory anchor for nodes without durable storage (tests, browser
+ * demos, not-yet-persisted mobile). Same contract, no disk: trust established
+ * here must be re-supplied (invite / operator pin) on the next process.
+ */
+export class MemoryTrustedOwnerStore implements TrustedOwnerStore {
+	private readonly keys = new Map<string, TrustSource>();
+
+	constructor(readonly partyId: string) {}
+
+	has(ownerKey: string): boolean {
+		return this.keys.has(ownerKey);
+	}
+
+	all(): ReadonlySet<string> {
+		return new Set(this.keys.keys());
+	}
+
+	async trust(ownerKey: string, source: TrustSource): Promise<void> {
+		if (this.keys.has(ownerKey)) {
+			return;
+		}
+		this.keys.set(ownerKey, source);
+		log('trusted owner key anchored (party=%s, source=%s)', this.partyId, source);
+	}
+}
+
+/** One anchored key as persisted: provenance + wall-clock trust time (ms). */
+interface TrustedOwnerEntry {
+	source: TrustSource;
+	trustedAt: number;
+}
+
+const KNOWN_SOURCES: ReadonlySet<string> = new Set<TrustSource>(['genesis', 'invite', 'operator']);
+
+/**
+ * What the anchor persists: `owners` maps ownerKey (base64url) -> provenance.
+ *
+ * One unusable entry discards the WHOLE record: trusting a subset of the keys a
+ * record claims is a silent, security-relevant downgrade, so a record that
+ * cannot be read in full is treated as no anchor at all (see
+ * `UnusableEntryPolicy` in `node-local-snapshot.ts`).
+ */
+const TRUSTED_OWNER_SNAPSHOT: NodeLocalSnapshotSpec<TrustedOwnerEntry> = {
+	label: 'trusted-owner anchor',
+	payloadKey: 'owners',
+	unusableEntry: 'discard-all',
+	acceptEntry: (_ownerKey, entry) => {
+		if (typeof entry !== 'object' || entry === null) return undefined;
+		const { source, trustedAt } = entry as { source?: unknown; trustedAt?: unknown };
+		if (typeof source !== 'string' || !KNOWN_SOURCES.has(source)) return undefined;
+		if (typeof trustedAt !== 'number') return undefined;
+		return { source: source as TrustSource, trustedAt };
+	}
+};
+
+/**
+ * Durable {@link TrustedOwnerStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileTrustedOwnerStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load and persist policy — what an absent,
+ * corrupt, foreign-party or unreadable slot does, and what a failed persist
+ * does — is documented once on `NodeLocalSnapshot`; this class only supplies
+ * the payload shape and the anchor's whole-record-on-bad-entry policy.
+ */
+export class PersistentTrustedOwnerStore implements TrustedOwnerStore {
+	private constructor(private readonly snapshot: NodeLocalSnapshot<TrustedOwnerEntry>) {}
+
+	/** Load (or cold-start) the party's anchor from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentTrustedOwnerStore> {
+		return new PersistentTrustedOwnerStore(
+			await NodeLocalSnapshot.open(slot, partyId, TRUSTED_OWNER_SNAPSHOT)
+		);
+	}
+
+	get partyId(): string {
+		return this.snapshot.partyId;
+	}
+
+	has(ownerKey: string): boolean {
+		return this.snapshot.has(ownerKey);
+	}
+
+	all(): ReadonlySet<string> {
+		return this.snapshot.keySnapshot();
+	}
+
+	/**
+	 * Anchor a key: visible via {@link has} / {@link all} synchronously, then the
+	 * full snapshot is persisted (see `NodeLocalSnapshot.put`).
+	 */
+	trust(ownerKey: string, source: TrustSource): Promise<void> {
+		if (this.snapshot.has(ownerKey)) {
+			// Idempotent: re-enrollment / restart re-seeding keeps the original
+			// provenance and skips the write entirely.
+			// NOTE: this resolves immediately rather than joining the write chain, so
+			// re-trusting a key whose first persist is still in flight does not await
+			// that persist. Harmless for the seeding callers (they re-trust only after
+			// the original settled, or do not await at all); chain it if a caller ever
+			// needs "durable by the time trust() resolves" for a repeat key.
+			return Promise.resolve();
+		}
+		log('trusted owner key anchored (party=%s, source=%s); persisting', this.partyId, source);
+		return this.snapshot.put(ownerKey, { source, trustedAt: Date.now() });
+	}
+}

package/src/types.ts

@@ -1,10 +1,14 @@
 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 { IPeerNetwork, IRepo } from '@optimystic/db-core';
+import type { StrandBackfillConfig } from './strand-backfill.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 { PushNotifier } from './push-notifier.js';
+import type { RevocableTable } from './control-authorization.js';
 
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
@@ -12,6 +16,14 @@ import type { PushNotifier } from './push-notifier.js';
  */
 export interface Libp2pNodeWithRepo extends Libp2p {
   coordinatedRepo: IRepo;
+  /**
+   * The node's key-addressed peer network, attached by db-p2p's factory alongside
+   * `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.
+   */
+  keyNetwork?: IPeerNetwork;
 }
 
 /**
@@ -120,8 +132,9 @@ export interface StorageConfig {
    *
    * For React Native, use the appropriate storage from @optimystic/db-p2p-storage-rn:
    * ```typescript
-   * import { RNRawStorage } from '@optimystic/db-p2p-storage-rn';
-   * storage: { provider: (strandId) => new RNRawStorage(strandId) }
+   * 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}`)) }
    * ```
    *
    * For in-memory storage (testing):
@@ -139,7 +152,47 @@ export interface StorageConfig {
  */
 export interface NetworkConfig {
   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).
+   *
+   * Accepted (settable in `cadre.yaml`, via `CADRE_ANNOUNCE_ADDRS`, and through the
+   * Docker entrypoint) but **not yet applied**: libp2p only takes announce addresses
+   * at construction (`addresses.announce` / `addresses.appendAnnounce`), and
+   * `@optimystic/db-p2p`'s `NodeOptions` has no field for either — there is nothing
+   * in this repo to wire this into. `CadreNode.start()` warns when this is set,
+   * rather than pretending it works. Unblocked by the `announce-addrs-option`
+   * request filed against `@optimystic/db-p2p`; wiring lands here once this repo's
+   * dependency range moves to a version carrying it.
+   *
+   * Use {@link relayAddrs} for reachability behind NAT today (a reserved relay slot
+   * gives the node a real dialable circuit address), or `inviteAddressResolver` to
+   * substitute a reachable address into invite payloads specifically — neither
+   * changes what this node advertises on the wire, but both cover the operator need
+   * this field cannot yet.
+   */
   announceAddrs?: string[];
+  /**
+   * Circuit-relay servers this node reserves a slot on, so peers can reach it
+   * from behind NAT. Each entry is the relay's DIRECT dial multiaddr ending in
+   * its peerId — `/dns4/relay.example.com/tcp/4001/p2p/12D3KooW…` — with no
+   * `/p2p-circuit` suffix (one is appended for you; an entry that already has
+   * one is passed through unchanged).
+   *
+   * This is sugar for a circuit entry in {@link listenAddrs}: `relay-addrs.ts`
+   * resolves the two into one listen list, and listening on a relay's circuit
+   * addr is what makes libp2p dial it and hold the reservation. A relay named
+   * here therefore also becomes a delegate-announce target, so this node's
+   * strand nodes may reserve on it too (see `delegate-admission.ts`).
+   *
+   * Setting this gives the node a listener even when `listenAddrs` is `[]` —
+   * that is the point of naming a relay, but note that React Native hosts
+   * (`reference-app-rn`'s `cadre-phone.ts`) deliberately do NOT listen, and
+   * must not acquire a listener by accident.
+   *
+   * A malformed entry throws at node start rather than being silently dropped.
+   */
   relayAddrs?: string[];
   /**
    * Enable circuit relay server - allows this node to relay connections for other peers.
@@ -179,6 +232,12 @@ export interface NetworkConfig {
    * 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.
+   *
+   * 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).
    */
   connectionGater?: ConnectionGater;
   /**
@@ -237,6 +296,27 @@ export interface ControlNetworkConfig {
   schemaPath?: string;
 }
 
+/**
+ * Replication-breadth constants, both networks' cluster policies, and the strand
+ * resolver, re-exported so cadre embedders, the SQL plugin and the integration
+ * harness share one definition. Defined in `@serfab/quereus-plugin-sereus`
+ * because that package also creates libp2p nodes and cannot depend on this one.
+ * The control network's breadth is fixed ({@link CONTROL_REPLICATION_BREADTH},
+ * not configurable) and so is its consensus policy ({@link CONTROL_CLUSTER_POLICY}
+ * — notably the super-majority threshold, which it leaves at Optimystic's default
+ * by omission); the strand breadth defaults to
+ * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
+ * {@link STRAND_CLUSTER_POLICY}.
+ */
+export {
+  MIN_CLUSTER_SIZE,
+  CONTROL_REPLICATION_BREADTH,
+  CONTROL_CLUSTER_POLICY,
+  DEFAULT_STRAND_CLUSTER_SIZE,
+  STRAND_CLUSTER_POLICY,
+  resolveStrandClusterSize
+} from '@serfab/quereus-plugin-sereus';
+
 /**
  * Main configuration for a CadreNode
  */
@@ -281,6 +361,43 @@ export interface CadreNodeConfig {
   /** Network configuration */
   network?: NetworkConfig;
 
+  /**
+   * Number of nodes Optimystic is told a **strand** network's replication cluster
+   * should have, for every strand this node starts. The control network is not
+   * configurable — it always replicates to {@link CONTROL_REPLICATION_BREADTH}
+   * nodes, which is above any party's node count, because every member reads the
+   * whole control database and a member that misses a write may never learn the
+   * fact (see that constant for the full reasoning).
+   *
+   * Every node on the same strand should use the same value: the number bounds the
+   * cohort a member independently derives, and Optimystic's cluster-membership gate
+   * can reject a coordinator's smaller declared set as a downsize against a larger
+   * derived view.
+   *
+   * Frozen when the strand's libp2p node is created; a change takes effect on
+   * restart, not when cadre membership grows. Defaults to
+   * {@link DEFAULT_STRAND_CLUSTER_SIZE} (4 — the smallest breadth whose 0.75
+   * super-majority still commits with one holder offline); anything below
+   * {@link MIN_CLUSTER_SIZE} is rejected before a node is created. The cost of a
+   * small value is replication breadth and reliance on read repair, not commit
+   * correctness — but at 2 that read repair cannot converge, because a lone
+   * corroborator's stale answer is accepted as the cluster's truth.
+   */
+  strandClusterSize?: number;
+
+  /**
+   * Tuning for the strand peer-join block catch-up (see `strand-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.
+   */
+  strandBackfill?: StrandBackfillConfig;
+
   /** Hibernation configuration */
   hibernation?: HibernationConfig;
 
@@ -300,14 +417,76 @@ export interface CadreNodeConfig {
    * into every SeedBootstrapService this node constructs (owner, 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).
+   * (that path has no per-call override seam). Defaults to anchoredTrustPolicy()
+   * inside SeedBootstrapService when unset — a node whose node-local trusted-owner
+   * anchor was never seeded 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;
 
+  /**
+   * Node-local trusted-owner anchor (see `trusted-owner-store.ts`): the
+   * NON-replicated, per-party record of owner keys established out of band —
+   * the anchor membership/seed trust can rest on, since the replicated
+   * `OwnerKey` table can be polluted by a stranger's self-genesis. Absent ⇒ an
+   * in-memory store is created at start() (ephemeral: anchored trust does not
+   * survive the process).
+   */
+  trustedOwners?: {
+    /**
+     * Injected store instance — e.g. a `FileTrustedOwnerStore` from the
+     * Node-only subpath `@serfab/cadre-core/trusted-owner-store-file`,
+     * persisted in the node's state directory (same injection/isolation pattern
+     * as {@link keyStore}). Its `partyId` must match `controlNetwork.partyId`;
+     * start() fails closed on a mismatch.
+     */
+    store?: TrustedOwnerStore;
+    /**
+     * Owner keys (base64url ed25519) established out of band and seeded into
+     * the store during start(): operator pins (e.g. cadre-cli
+     * `--pin-owner-key` / `CADRE_OWNER_KEYS`) or a `CadreInvite.ownerKeys`
+     * already known at config time. Seeding is idempotent across restarts.
+     */
+    pinnedKeys?: string[];
+    /**
+     * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
+     * ('genesis' is reserved for the node's own founding key, seeded
+     * internally by `initializeSeedBootstrap`.)
+     */
+    pinnedSource?: Exclude<TrustSource, 'genesis'>;
+  };
+
+  /**
+   * Node-local cold-start bootstrap-peer store (see `bootstrap-peer-store.ts`):
+   * the owner addresses an applied seed nominated, kept so
+   * `reconcileControlCohort`'s cold-start branch can keep retrying a node that
+   * was seeded but never managed to connect. Sibling of {@link trustedOwners} —
+   * same NON-replicated, per-party, injected-backend shape — but nothing here is
+   * trust-bearing: these are dial hints only, and every address is re-bound to
+   * its peer id before the dial. Absent ⇒ an in-memory store is created at
+   * start() (ephemeral: the retry set does not survive the process, and such a
+   * node is stranded permanently if it restarts before connecting).
+   *
+   * The Node CLI, the browser, and React Native all inject a durable backend
+   * today; only NativeScript stays ephemeral, tracked by the
+   * `ns-durable-node-local-stores` ticket (which covers the same gap for
+   * {@link trustedOwners}). A new platform needs no new store class: supply a
+   * `DurableSlot` for the platform's storage and inject
+   * `PersistentBootstrapPeerStore.open(slot, partyId)` /
+   * `PersistentTrustedOwnerStore.open(slot, partyId)`.
+   */
+  bootstrapPeers?: {
+    /**
+     * Injected store instance — e.g. a `FileBootstrapPeerStore` from the
+     * Node-only subpath `@serfab/cadre-core/bootstrap-peer-store-file`, persisted
+     * in the node's state directory (same injection/isolation pattern as
+     * {@link keyStore} / {@link trustedOwners}). Its `partyId` must match
+     * `controlNetwork.partyId`; start() fails closed on a mismatch.
+     */
+    store?: BootstrapPeerStore;
+  };
+
   /**
    * 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
@@ -367,6 +546,14 @@ export interface StrandInstance {
   status: StrandStatus;
   sAppInfo?: SAppInfo;
 
+  /**
+   * The lifecycle mode this instance's runtime was built with — `bootstrap`
+   * (purely local transactor) or `networked` (cluster transactor). Refreshed on
+   * every runtime (re)build, so a resume that shifts `bootstrap → networked`
+   * updates it. Read-only reporting; drives no behavior.
+   */
+  mode: StrandMode;
+
   /** The libp2p node for this strand (only when active/idle) */
   libp2pNode?: Libp2p;
 
@@ -556,16 +743,6 @@ export interface FormStrandResult {
   memberPrivateKey?: string;
 }
 
-/**
- * Result of validating a strand formation request
- */
-export interface ValidateFormationResult {
-  /** Public key for validating this formation */
-  validationKey: string;
-  /** Signature over the formation approval */
-  validationSignature: string;
-}
-
 /**
  * Disclosure object provided during strand formation.
  * Contains identity and context information from the initiator.
@@ -656,13 +833,60 @@ export interface PeerAddressRecord {
   sig: string;
 }
 
+/**
+ * One `CadreControl.CadrePeer` row as read by `ControlDatabase.queryCadrePeers`:
+ * the addressing columns plus the persisted membership voucher.
+ *
+ * The voucher triple (`stampId`, `vouchOwner`, `vouchSig`) is what
+ * {@link CadreNode.listAuthorizedMembers} re-checks against the node-local
+ * trusted-owner anchor — it is null on a row written before the voucher columns
+ * existed, and all three must be present for the row to be authorizable. Named
+ * (rather than restated inline at each read site) so a future column addition
+ * cannot reach the query without the predicate seeing it.
+ */
+export interface CadrePeerRow {
+  /** libp2p peer ID (base58btc) — the row key. */
+  peerId: string;
+  /** Comma-joined dialable multiaddrs as stored, or null when unpublished. */
+  multiaddr: string | null;
+  /** Single-use anti-replay nonce the voucher signature is bound to. */
+  stampId: string | null;
+  /** ed25519 public key (base64url) of the owner that vouched this row. */
+  vouchOwner: string | null;
+  /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', peerId, stampId)`, base64url. */
+  vouchSig: string | null;
+}
+
+/** The voucher-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
+export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig'>;
+
+/**
+ * One `CadreControl.Revocation` tombstone as read by
+ * `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.
+ */
+export interface RevocationRow {
+  /** Which guarded table's stamp was retired. */
+  tableName: RevocableTable;
+  /** Primary key of the removed row (peer id / key / strand id). */
+  rowKey: string;
+  /** The retired single-use nonce — the tombstone's identity. */
+  stampId: string;
+  /** Monotonic re-issue counter; carries no semantics (see the schema comment). */
+  reissuedAt: number;
+}
+
 /**
  * Outcome of {@link CadreNode.registerSelf}, surfaced so callers (e.g. the CLI
  * `--owner` branch) can log what happened:
  * - `inserted` — the first owner-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
- *   owner service to self-insert).
+ *   Also reported when a first publish found its row seated by a concurrent
+ *   `authorizePeer` of this node's own id and fell through to the UPDATE — the write
+ *   really was an UPDATE, even though the caller's intent was a first publish.
+ * - `skipped` — nothing written (no self-signing key, not yet a member with no
+ *   owner service to self-insert, or the row was removed mid-publish).
  */
 export type SelfRegistrationOutcome = 'inserted' | 'refreshed' | 'skipped';
 
@@ -745,6 +969,21 @@ export interface DeviceTokenRecord {
   sig: string;
 }
 
+/**
+ * A stored `CadreControl.DeviceToken` row: the self-signed
+ * {@link DeviceTokenRecord} plus the row's single-use `StampId` nonce.
+ *
+ * The stamp is deliberately OUTSIDE `DeviceTokenRecord`: the peer's own `Sig`
+ * covers only (peerId, platform, token, updatedAt), while the stamp is bound by
+ * the OWNER's insert/delete approvals. Readers need it to drop a row whose stamp
+ * has been retired into `CadreControl.Revocation` (a token resurrected by an
+ * approval replay on a node that had not yet converged on the tombstone).
+ */
+export interface DeviceTokenRow extends DeviceTokenRecord {
+  /** Single-use authorization nonce; rotates on every (re)insert. */
+  stampId: string;
+}
+
 /**
  * Options for {@link CadreNode.resolveDeviceToken}.
  */
@@ -918,6 +1157,14 @@ export interface WakeAck {
 export interface StrandAddrRequest {
   /** The strand whose strand-network address the requester wants to seed from. */
   strandId: string;
+  /**
+   * The derived transport peerId the requester's own strand-`strandId` node
+   * runs as (see `strand-transport-key.ts`). Present → the responder records a
+   * delegate admission grant for it, so its own connection gate (and thus its
+   * circuit-relay server, when it runs one) admits that peerId; absent →
+   * today's behavior exactly. See `delegate-admission.ts` for the trust model.
+   */
+  delegatePeerId?: string;
 }
 
 /**
@@ -955,6 +1202,27 @@ export interface ApplySeedResult {
   peersAdded: number;
   /** Error message if not successful */
   error?: string;
+  /**
+   * Owner-flagged seed peers this apply attempted to dial. Zero when the seed
+   * carried no owner peer with an address, or when the seed was rejected before
+   * the dial loop ran.
+   */
+  ownerDialsAttempted: number;
+  /**
+   * How many of those dials threw. `ownerDialsAttempted > 0 && ownerDialsFailed
+   * === ownerDialsAttempted` means "seeded but stranded": the seed itself was
+   * accepted (`success: true`) but no owner could be reached, so this node has
+   * no connection to bootstrap its control database from. The node retries those
+   * addresses on every control-cohort reconcile pass (see
+   * `CadreNode.dialColdStartBootstrap`), so this is a signal, not a fatal error.
+   *
+   * Zero failures is NOT proof of a live connection: the receiving node's
+   * membership gate denies AFTER the dialer's upgrade completes (see
+   * `createMembershipConnectionGater`), so a dial can resolve and then be torn
+   * down. Treat a non-zero value as certain failure and zero as "no failure
+   * observed".
+   */
+  ownerDialsFailed: number;
 }
 
 // ============================================================================
@@ -979,7 +1247,10 @@ export interface CadreInvite {
    * Owner ed25519 public keys (base64url) of the cadre, carried out-of-band
    * so a cold-start invitee can pin the trusted owner set before applying
    * any seed (the seed itself cannot vouch for its own signer). Populated by
-   * `createInvite` from the issuer's `OwnerKey` table.
+   * `createInvite` from the issuer's OWN node-local trusted-owner anchor —
+   * not its replicated `OwnerKey` table, because the invitee anchors whatever
+   * arrives here and a stranger's genesis-inserted key must not ride an
+   * otherwise-legitimate invite into a fresh node's anchor.
    */
   ownerKeys?: string[];
   /** Optional invite token for validation */