@serfab/cadre-core 1.16.0 → 1.18.0

package/src/types.ts

@@ -1,7 +1,7 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { CircuitRelayServerInit } from '@libp2p/circuit-relay-v2';
 import type { IRawStorage, Libp2pConnectionMonitorInit, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
-import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
+import type { CollectionChangeListener, IPeerNetwork, IRepo } from '@optimystic/db-core';
 import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
 import type { StrandReactivityConfig } from './strand-reactivity.js';
 import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
@@ -17,8 +17,11 @@ import type { StrandNetworkStateStore } from './strand-network-state.js';
 import type { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
-import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
-import type { CadreInvitation, CadreInviteAddressOutcome } from './cadre-invite-protocol.js';
+import type { CadreInviteSignedFields, OwnerGrantSignedFields, RevocableTable } from './control-authorization.js';
+import type { FoundingInvite } from './control-database.js';
+import type { CadreInvitation } from './cadre-invite-protocol.js';
+import type { OwnerGrantBundle } from './owner-grant-protocol.js';
+import type { RedemptionAddressOutcome } from './member-redemption.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 import type { FormationRejectionCode } from './strand-formation-rejection.js';
 import type { ListenTransportOptions } from './relay-addrs.js';
@@ -37,6 +40,21 @@ export interface Libp2pNodeWithRepo extends Libp2p {
    * backfill (`peer-join-backfill.ts`) logs once and stays inert when it is absent.
    */
   keyNetwork?: IPeerNetwork;
+  /**
+   * The node's block store, attached by the same factory (Optimystic's
+   * `OptimysticNodeAttachments.storageRepo`), narrowed to the storage-wide change feed: it
+   * fires for every block that lands in this node's store, a push or a commit. Optional for
+   * the same reason as `keyNetwork`; the first-sync gate (`strand-first-sync-gate.ts`) wakes
+   * on it, and logs once and probes on its backstop alone when it is absent.
+   */
+  storageRepo?: { onAnyCollectionChange(listener: CollectionChangeListener): () => void };
+  /**
+   * Tells the node a peer holds a block at a revision or later (Optimystic's
+   * `OptimysticNodeAttachments.reportBlockHeld`), so its under-replication drain and rebalance
+   * monitor do not push that peer the same block again. Optional for the same reason as
+   * `keyNetwork`; the join catch-up (`peer-join-backfill.ts`) reports each block a peer accepted.
+   */
+  reportBlockHeld?: (blockId: string, rev: number, peerId: string) => Promise<void>;
 }
 
 /**
@@ -576,8 +594,13 @@ export interface NetworkConfig {
      */
     targetDegree?: number;
     /**
-     * Recurring reconcile cadence in ms. Defaults to
-     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}.
+     * The reconcile pass's backstop in ms: a pass runs this long after the last one
+     * settled when nothing has started one sooner (a membership table change, a sibling
+     * connecting or disconnecting, an address change, a redial or strand-address wake).
+     * It also caps the redial ladder. Defaults to
+     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS} (2 minutes). The membership rows view's
+     * maximum age (`MEMBERSHIP_VIEW_MAX_AGE_MS`, 15 s) does not follow this field: a backstop
+     * longer than it reads storage on every backstop pass, a shorter one every 15 s at most.
      */
     reconcileMs?: number;
     /**
@@ -646,10 +669,10 @@ export interface NetworkConfig {
  * pinging node's monitor sees the reset and aborts the connection exactly as it would on its
  * own timeout. So this deadline is only real up to the handler timeout of the node being
  * pinged, which has to stay above it. The deployed relay sets its handler to 60 s for that
- * reason (`ops/docker/libp2p-infra/src/main.ts`). Every cadre node's handler is Optimystic's
- * bare `ping()`, `@libp2p/ping`'s 10 s, and nothing here can move it
- * (`tickets/blocked/optimystic-ping-handler-timeout-below-the-monitor-deadline.md`): between
- * two cadre nodes, a ping whose echo takes longer than 10 s still drops the connection.
+ * reason (`ops/docker/libp2p-infra/src/main.ts`). Every cadre node's handler is Optimystic's,
+ * which derives it from this object: twice `pingTimeout.maxTimeout`, so 60 s
+ * (`NodeOptions.pingHandlerTimeoutMs`, unset here, since Optimystic 1.16.0). An app that
+ * replaces this object without a `pingTimeout` gets `@libp2p/ping`'s 10 s handler back.
  *
  * WHAT THE LINK NEEDS OF IT. One ping opens a fresh stream and echoes over it: a protocol
  * negotiation plus the echo, two link round trips by `link-budget.ts`'s counts (a `newStream`
@@ -776,11 +799,10 @@ export interface CadreNodeConfig {
    * form). Mutually exclusive with {@link privateKey}. Absent ⇒ use `privateKey`
    * when set, else libp2p generates an ephemeral key.
    *
-   * In the single-key reference model the owner signing key is *derived from*
-   * the node identity (see {@link CadreNode.getIdentityOwnerKey}), so
-   * protecting the identity in a secure enclave protects the owner key too.
-   * A future separate-owner slot (`ownerKeyId`) is anticipated but not
-   * built here.
+   * The node signs owner writes through whatever owner signer the embedder wires
+   * (`CadreNode.useOwnerSigner`). An owner key has its own slot
+   * (`owner-key-store.ts`), which may be in this same store; this identity is never
+   * an owner key.
    */
   keyStore?: KeyStore;
 
@@ -844,10 +866,11 @@ export interface CadreNodeConfig {
 
   /**
    * 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.
+   * when a strand's libp2p node connects (or reconnects) to a peer, every
+   * block in the strand's own raw store that the peer is not
+   * known to hold is pushed to it, each block once per 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.
    * 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}.
@@ -876,13 +899,14 @@ export interface CadreNodeConfig {
   /**
    * 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
+   * libp2p node connects (or reconnects) to an AUTHORIZED party member, every
+   * block in the control database's own raw store that the
+   * member is not known to hold 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 the node's authorized-member snapshot (the rule
+   * `CadreNode.isAuthorizedMember` reads), 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.
@@ -895,9 +919,10 @@ export interface CadreNodeConfig {
    * 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.
+   * rather than only deleting its row. Open strands never arm it. Each strand
+   * re-reads its membership when `Strand.Member` or `Strand.MemberPeer` changes,
+   * and at the latest every `DEFAULT_REVOCATION_BACKSTOP_MS`. Omit for the
+   * defaults; `{ enabled: false }` restores the pre-existing behaviour.
    */
   strandRevocationEnforcement?: StrandRevocationEnforcementConfig;
 
@@ -910,9 +935,8 @@ export interface CadreNodeConfig {
    * 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
+   * join retries from 1 s, doubling. Omit for the defaults
+   * (`DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS`); `{ enabled: false }` disarms the loop — for test fixtures that hand-drive
    * the membership writers and assert exact row sets.
    */
   strandMembershipReconciliation?: StrandMembershipReconciliationConfig;
@@ -922,15 +946,17 @@ export interface CadreNodeConfig {
    * (`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.
+   * another member and every `Strand` and `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`,
+   * `StrandAwaitingFirstSyncError` (retryable — the launch stays up and keeps probing).
+   * While gated the machine probes whenever data lands in the strand's store, and
+   * `backstopMs` after its last probe when none has. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`,
    * sized for a machine re-attaching through a relay on a slow link, the slowest attach
    * measured; that constant's doc comment carries the number, the measurement behind it and
-   * what the budget costs, and is the only copy of them; `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`,
-   * 500 ms). There is deliberately no way to disable the gate: a machine whose store already
+   * what the budget costs, and is the only copy of them; `DEFAULT_STRAND_FIRST_SYNC_BACKSTOP_MS`,
+   * 2 s). There is deliberately no way to disable the gate: a machine whose store already
    * holds the Header is never gated, so nothing that works today is blocked by it.
    */
   strandFirstSync?: StrandFirstSyncConfig;
@@ -938,7 +964,11 @@ export interface CadreNodeConfig {
   /** Hibernation configuration */
   hibernation?: HibernationConfig;
 
-  /** Polling interval for strand watcher in ms (default: 5000) */
+  /**
+   * The strand watcher's backstop in ms (default 300000): the longest it goes without
+   * re-reading `Strand` and `JoinedStrand` when no change to them is heard. It otherwise runs
+   * on a change. Also caps the first step of its retry ladders, which is 5 s otherwise.
+   */
   strandWatchInterval?: number;
 
   /**
@@ -972,7 +1002,7 @@ export interface CadreNodeConfig {
    *
    * A node has exactly one cold-start trust source, so `claim` beside a non-empty
    * `trustedOwners.pinnedKeys` or a `seedTrustPolicy` fails `start()` closed, and
-   * `initializeSeedBootstrap` (an owner key) refuses on such a node: a hosted node never
+   * `useOwnerSigner` (an owner key) refuses on such a node: a hosted node never
    * holds an owner key. A claimed node restarted with this still set ignores it (its
    * anchor is non-empty), so the operator need not remove it.
    *
@@ -1025,7 +1055,7 @@ export interface CadreNodeConfig {
     /**
      * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
      * ('genesis' is reserved for the node's own founding key, seeded
-     * internally by `initializeSeedBootstrap`; 'chain' is written only by the
+     * internally by `useOwnerSigner`; 'chain' is written only by the
      * anchor sync, `CadreNode.syncOwnerAnchor`.)
      */
     pinnedSource?: Exclude<TrustSource, 'genesis' | 'chain'>;
@@ -1272,16 +1302,21 @@ export interface StrandRow {
   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.
+   * ed25519 (base64url) owner key that signed the owner-signed `Strand` insert
+   * (`== context.OwnerKey`, pinned by the schema's `AuthorizedInsert`). `null` on a
+   * consent-seated strand (the unsigned `FormationUsage` branch records no
+   * signer). Provenance, not content — `strandRowMismatches` excludes it from the
+   * identical-content comparison.
    */
   FounderOwnerKey: string | null;
+  /**
+   * Peer id of the machine that runs the founder bootstrap, named by the owner
+   * signature on the insert (`CadreNode.publishStrand` writes its own). A launch
+   * with no explicit `founder` flag founds iff this is its own peer id (see
+   * `CadreNode.launchStrand`), so two machines holding one owner key never both
+   * found. `null` on a consent-seated strand. Provenance, as {@link FounderOwnerKey}.
+   */
+  FounderPeerId: string | null;
 }
 
 /**
@@ -1404,7 +1439,7 @@ export interface StrandConfig {
    * 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
+   * {@link StrandRow.FounderPeerId} is its own peer id. An explicit
    * `true`/`false` wins over the derivation — the formation/responder flows pass
    * it deliberately, since a consent-seated row carries a null column.
    */
@@ -1457,6 +1492,14 @@ export interface FoundStrandConfig {
   memberPrivateKey?: string;
   /** sApp configuration the hosting application provides, as for {@link StrandConfig}. */
   sAppConfig: SAppConfig;
+  /**
+   * A formation invitation to publish bound to this strand, for the app `sAppConfig.id`, in the
+   * same control transaction and owner approval as the strand row. Mint it first with
+   * `createOpenInvitation` (its `expiration` is `expiresAtMs`). When the strand is already
+   * published the invitation is published on its own, under its own approval, as
+   * `publishFormationInvite` would; one already stored under `token` for this strand is kept.
+   */
+  formationInvite?: Omit<FoundingInvite, 'sAppId'>;
   /**
    * 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
@@ -1492,6 +1535,37 @@ export interface FoundStrandResult {
   founded: boolean;
 }
 
+/**
+ * Options for {@link CadreNode.foundStrand}. Passing them selects the form that returns once
+ * the row is published ({@link FoundStrandBackgroundResult}), for a caller that needs only the
+ * row: minting an invitation reads just its id and membership key.
+ *
+ * An invitation redeemed before the start finishes is refused, retryably: a closed host
+ * strand answers `host-strand-unavailable` and leaves the token unspent. For an open host
+ * strand the approval is sent, but carries no strand addresses, because the strand node does
+ * not exist yet.
+ */
+export interface FoundStrandOptions {
+  /** Return once the row is published; the start continues in {@link FoundStrandBackgroundResult.ready}. */
+  background: true;
+}
+
+/** What {@link CadreNode.foundStrand} returns with `{ background: true }`: the row is published; the local start continues. */
+export interface FoundStrandBackgroundResult {
+  /** The live control-plane row: freshly published, or the one already there. Same as {@link FoundStrandResult.strandRow}. */
+  strandRow: StrandRow;
+  /** Same as {@link FoundStrandResult.founded}. */
+  founded: boolean;
+  /**
+   * Settles when the local start does. Resolves with the instance `addStrand` returns.
+   * Rejects with the start's own error. After a launch failure the strand stays published
+   * and the strand watcher keeps retrying it. After a first-sync timeout (only an adopted,
+   * not-founded row waits for one) the instance stays up and still syncing, so wait with
+   * {@link CadreNode.whenStrandWritable}.
+   */
+  ready: Promise<StrandInstance>;
+}
+
 /**
  * Result of creating a new cadre peer
  */
@@ -1742,14 +1816,14 @@ export interface CadreNodeEvents {
    * Also emitted for a strand this node joined from ANOTHER party, which no control
    * row names: the node remembers every such join (see
    * {@link CadreNodeConfig.joinedStrands}) and offers it here on each start, as a row
-   * with `FounderOwnerKey: null` carrying the closed strand's `MemberPrivateKey`. That
+   * with null founder columns carrying the closed strand's `MemberPrivateKey`. That
    * row is the product of the formation's consent, so claiming it needs no second one.
    *
    * **Fired once per strand per session, and it can fire before your listener is
-   * attached.** The strand watcher's first poll runs inside `CadreNode.start()`
+   * attached.** The strand watcher's first run is 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
+   * `start()` await. The watcher then records the strand as seen and no later run
    * re-offers it, so a listener attached a moment late misses those strands for the
    * life of the process.
    *
@@ -1804,8 +1878,14 @@ export interface CadreNodeEvents {
   'pendingJoin:changed': PendingJoinStatus;
   /** Emitted when a seed is received via the seed protocol */
   'seed:received': { partyId: string; peerId: string };
-  /** Emitted when a seed is successfully applied */
-  'seed:applied': { partyId: string; peersAdded: number };
+  /**
+   * Emitted when a seed delivered over the seed protocol has been verified, merged and
+   * acknowledged to its sender. The dials of its preferred peers follow this event, so it
+   * waits on no connection. `dialTargets` are those peers (`seedDialTargets`): an embedder
+   * that restarts into another party's stores carries them there, since this node retained
+   * them in its own.
+   */
+  'seed:applied': { partyId: string; peersAdded: number; dialTargets: SeedDialTarget[] };
   /** Emitted when seed application fails */
   'seed:error': { partyId: string; error: string };
   /**
@@ -1813,10 +1893,10 @@ export interface CadreNodeEvents {
    * valid claim proof has been recorded (`claim.record`) and has durably anchored its
    * signer as this node's owner. Carries the claim's party beside the owner key: the
    * party this node should serve from now on, which its own config did not know. Fires
-   * BEFORE the seed is acknowledged to the claimant, its peers merged and its owners
-   * dialed, so it precedes that seed's `seed:applied`; an embedder that restarts into
-   * the claimed party on this event should wait for that `seed:applied` (or `seed:error`)
-   * so the acknowledgement is not lost with the node. `CadreNode.isAwaitingClaim` is the
+   * BEFORE the seed is acknowledged to the claimant and its peers merged, so it precedes
+   * that seed's `seed:applied`; an embedder that restarts into the claimed party on this
+   * event should wait for that `seed:applied` (or `seed:error`) so the acknowledgement is
+   * not lost with the node. `CadreNode.isAwaitingClaim` is the
    * matching predicate for a reader that subscribed too late to see the event.
    */
   'claim:accepted': NodeClaimRecord;
@@ -1915,25 +1995,27 @@ export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | '
 
 /**
  * One live `CadreControl.OwnerKey` row as `ControlDatabase.queryOwnerKeyRows` reads it: the
- * key and the persisted proof of how it was seated. The three proof shapes are the schema's
- * (`OwnerKey.Authorized`): the founding row (all three null), an owner-signed add (`vouchOwner`
- * and `vouchSig`, the signer's signature over `ownerKeyAddDigest(key, stampId)`), or an
- * owner-granting invitation redeemed by consent (`vouchOwner` the issuer, `vouchSig` null,
- * `vouchUsage` the `CadreInviteUsage` row). Rows whose stamp is retired in `Revocation`, and
- * the stampless row the schema permits but no writer produces, never reach a reader, so
- * `stampId` is non-null here. The anchor sync (`deriveOwnerAnchor`) judges
- * the proof against the keys it already trusts, never against the table itself.
+ * key, its label and the persisted proof of how it was seated. The three proof shapes are the
+ * schema's (`OwnerKey.Authorized`): the founding row (all three null), an owner-signed add
+ * (`vouchOwner` and `vouchSig`, the signer's signature over `ownerKeyAddDigest(key, label, stampId)`), or an
+ * owner grant redeemed by consent (`vouchOwner` the issuer, `vouchSig` null, `vouchUsage` the
+ * `OwnerGrantUsage` row). Rows whose stamp is
+ * retired in `Revocation`, and the stampless row the schema permits but no writer produces,
+ * never reach a reader, so `stampId` is non-null here. The anchor sync (`deriveOwnerAnchor`)
+ * judges the proof against the keys it already trusts, never against the table itself.
  */
 export interface OwnerKeyRow {
   /** ed25519 public key (base64url) — the row key. */
   key: string;
+  /** The user's name for the key, bound into an owner-signed add or into the grant that seated it; null when none was given. */
+  label: string | null;
   /** Single-use anti-replay nonce the voucher signature, or the usage row, is bound to. */
   stampId: string;
-  /** The owner that signed the add, or that issued the invitation that admitted it; null on the founding row. */
+  /** The owner that signed the add, or that issued the grant that seated it; null on the founding row. */
   vouchOwner: string | null;
-  /** That owner's signature over the row's `'add'` digest, base64url; null on the founding row and on an invitation-admitted row. */
+  /** That owner's signature over the row's `'add'` digest, base64url; null on the founding row and on a consent-seated row. */
   vouchSig: string | null;
-  /** The `CadreInviteUsage.UsageStampId` that admitted this row; null otherwise. */
+  /** The `OwnerGrantUsage.UsageStampId` that seated this row; null otherwise. */
   vouchUsage: string | null;
 }
 
@@ -1967,10 +2049,8 @@ export interface CadreInviteUsageRow {
   peerId: string;
   /** The admitted device's ed25519 public key (base64url). */
   peerKey: string;
-  /** The `CadrePeer.StampId` this redemption seated (or found seated). */
+  /** The `CadrePeer.StampId` this redemption seated. */
   peerStampId: string;
-  /** The `OwnerKey.StampId` this redemption seated, when the invitation grants ownership; else null. */
-  ownerStampId: string | null;
   /** The invitation private key's signature over the `'redeem'` digest, base64url. */
   inviteSig: string;
   /** The device's signature over the `'consent'` digest, base64url. */
@@ -1978,11 +2058,9 @@ export interface CadreInviteUsageRow {
 }
 
 /**
- * The usage and invitation rows an invitation-admitted row is verified through, keyed by
- * `UsageStampId` and `CadreInvite.Key`: a `CadrePeer` row through `verifyInvitationAdmission`
- * (`CadreNode.listAuthorizedMembers`) and an `OwnerKey` row through
- * `verifyInvitationOwnerAdmission` (`deriveOwnerAnchor`). Loaded once per membership refresh
- * (`CadreNode.loadInvitationChain`) and shared by both readers.
+ * The usage and invitation rows an invitation-admitted `CadrePeer` row is verified through
+ * (`verifyInvitationAdmission`, `CadreNode.listAuthorizedMembers`), keyed by `UsageStampId`
+ * and `CadreInvite.Key`. Loaded once per membership refresh (`CadreNode.loadInvitationChain`).
  */
 export interface InvitationChain {
   usages: Map<string, CadreInviteUsageRow>;
@@ -1990,9 +2068,56 @@ export interface InvitationChain {
 }
 
 /**
- * One machine of the cadre as `CadreNode.listMachines` reports it: a live `CadrePeer` row,
- * or a live `OwnerKey` whose key derives a peer id with no `CadrePeer` row (an owner key
- * seated for a machine not yet admitted, or a founder that never self-published).
+ * One `CadreControl.OwnerGrant` row: an owner-signed grant of ownership to whoever holds its
+ * private half, as `ControlDatabase.insertOwnerGrant` returns it and `queryOwnerGrant` reads
+ * it. Every column is here because the row travels, as a {@link CadreInviteRow} does: the
+ * holder carries it inside the grant bundle and a member re-seats it verbatim
+ * (`seatOwnerGrant`), so `expiresAt` is the engine-canonical `datetime` string the row
+ * stores. The signed subset is `OwnerGrantSignedFields` (`control-authorization.ts`); the
+ * grant names no machine and no peer id.
+ */
+export interface OwnerGrantRow extends OwnerGrantSignedFields {
+  /** The owner that signed the row (`IssuerKey`, base64url ed25519); a reader checks it against its anchor. */
+  issuerKey: string;
+  /** That owner's `'add'` signature over the row (`IssuerSig`, base64url). */
+  issuerSig: string;
+}
+
+/**
+ * One `CadreControl.OwnerGrantUsage` row: a redemption of an {@link OwnerGrantRow}, as
+ * `ControlDatabase.queryOwnerGrantUsages` reads it. Both signatures are stored so any reader
+ * can re-verify the chain grant → usage → `OwnerKey` row (`verifyOwnerGrantAdmission`).
+ */
+export interface OwnerGrantUsageRow {
+  /** The redemption's single-use nonce (the row key), signed into both signatures. */
+  usageStampId: string;
+  /** The `OwnerGrant.Key` redeemed. */
+  grantKey: string;
+  /** The owner key seated (base64url ed25519): the holder's, fresh or already held. */
+  seatedKey: string;
+  /** The `OwnerKey.StampId` this redemption seated. */
+  seatedStampId: string;
+  /** The grant private key's signature over the `'redeem'` digest, base64url. */
+  grantSig: string;
+  /** The seated key's signature over the `'consent'` digest, base64url. */
+  ownerSig: string;
+}
+
+/**
+ * The usage and grant rows a grant-seated `OwnerKey` row is verified through, keyed by
+ * `UsageStampId` and `OwnerGrant.Key` (`verifyOwnerGrantAdmission`, from `deriveOwnerAnchor`).
+ * The grant twin of {@link InvitationChain}, loaded beside it by `CadreNode.syncOwnerAnchor`
+ * when some owner row is consent-seated; a row's `vouchUsage` is looked up in this chain
+ * first and in the invitation chain otherwise.
+ */
+export interface OwnerGrantChain {
+  usages: Map<string, OwnerGrantUsageRow>;
+  grants: Map<string, OwnerGrantRow>;
+}
+
+/**
+ * One machine of the cadre as `CadreNode.listMachines` reports it: a live `CadrePeer` row. An
+ * owner key is not a machine; `CadreNode.listOwnerKeys` lists those.
  *
  * `profile` and `lastPublishedAt` are the machine's own claim only when the row's
  * self-signature verifies; both are null otherwise, so an owner re-vouch that bumped
@@ -2001,58 +2126,108 @@ export interface InvitationChain {
  */
 export interface CadreMachine {
   peerId: string;
-  /** ed25519 public key (base64url) behind `peerId`; null when the id is not ed25519. */
+  /** The machine's ed25519 identity key (base64url) behind `peerId`; null when the id is not ed25519. Never an owner key (`listOwnerKeys` lists those). */
   publicKey: string | null;
   /** This node itself. */
   isSelf: boolean;
-  /** `publicKey` is a live `OwnerKey` here. */
-  isOwner: boolean;
-  /** Has a live `CadrePeer` row; false for an owner key with no machine row. */
-  isMember: boolean;
   /** Passes this node's authorized-membership predicate now (`CadreNode.listAuthorizedMembers`; always false for self, which that set excludes). */
   trusted: boolean;
   /** The machine's self-published node profile; null until it publishes, or when its signature does not verify. */
   profile: NodeProfile | null;
   /** `UpdatedAt` of its self-signed record, re-stamped while it runs; null on the same terms as `profile`. */
   lastPublishedAt: number | null;
-  /** `CadrePeer.VouchOwner` (or `OwnerKey.VouchOwner` for an owner-only entry): the owner that vouched it, or the issuer of the invitation that admitted it. */
+  /** `CadrePeer.VouchOwner`: the owner key that vouched it, or the issuer of the invitation that admitted it. */
+  vouchedBy: string | null;
+}
+
+/** One live owner key as `CadreNode.listOwnerKeys` lists it, for an app's owner-key screen. */
+export interface CadreOwnerKey {
+  /** ed25519 public key (base64url). */
+  key: string;
+  /** The user's name for the key ("phone", "paper backup"); null when none was given. */
+  label: string | null;
+  /** `OwnerKey.VouchOwner`: the owner that signed its add, or that issued the owner grant that seated it; null on the founding key. */
   vouchedBy: string | null;
+  /** This node's owner signer holds it. */
+  heldHere: boolean;
+  /** In this node's trusted-owner anchor, so this node accepts what it signs. */
+  trusted: boolean;
 }
 
+/** Why `CadreNode.addOwner` refuses by name (`OwnerKeyAddRefusedError.code`). */
+export type OwnerKeyAddRefusal =
+  /** No sibling reachable (`CadreNode.hasReachableControlSibling`) while the party has other members: the row would stay on this node, and nothing re-issues an `OwnerKey` add. */
+  | 'alone';
+
 /** Why `CadreNode.removeMachine` refuses by name (`MachineRemovalRefusedError.code`). */
 export type MachineRemovalRefusal =
   /** This node holds no enrolled owner key, so it cannot sign the removal. */
   | 'not-an-owner'
-  /** The machine is this node: an owner cannot sign its own `OwnerKey` removal, so ask another owner. */
-  | 'self'
-  /** The machine holds the only live owner key here (`MinOneOwner`). */
-  | 'last-owner';
+  /** The machine is this node: leaving a cadre is the embedder's flow (stop the node, delete its data), not a removal. */
+  | 'self';
 
 /**
  * What `CadreNode.removeMachine` would do for one machine, read without writing
- * (`CadreNode.planMachineRemoval`), for an app's confirmation step.
+ * (`CadreNode.planMachineRemoval`), for an app's confirmation step. A machine vouches nothing
+ * (a `VouchOwner` is an owner key), so removing one strands no other row.
  */
 export interface MachineRemovalPlan {
   /** The machine as listed, or null when no live row names it here (already removed). */
   machine: CadreMachine | null;
   refusal: MachineRemovalRefusal | null;
-  /** The machine's key is a live owner key, so the removal also retires it. */
-  removesOwnerKey: boolean;
-  /** Rows the machine's owner key vouched, which stop passing the membership predicate everywhere once it is removed unless re-vouched first. Empty unless `removesOwnerKey`. */
-  dependents: {
-    /** Live `OwnerKey` rows whose `VouchOwner` is the machine's key, this node's own excluded. */
-    owners: string[];
-    /** Live `CadrePeer` rows whose `VouchOwner` is the machine's key, the machine itself and this node excluded. */
-    peers: string[];
-  };
   /** Live `CadreInvite` keys the machine could redeem to come back: targeted at it, or already redeemed by it with uses left. */
   invitations: string[];
-  /** This node's own `OwnerKey` or `CadrePeer` row was vouched by the machine. It cannot re-vouch its own rows; another owner has to re-add it afterwards. */
+}
+
+/** What `CadreNode.removeMachine` wrote. All false and empty when no live row named the machine here. */
+export interface MachineRemovalResult {
+  removedPeer: boolean;
+  removedDeviceToken: boolean;
+  /** `CadreInvite` keys whose withdrawal tombstone this call filed. */
+  withdrawnInvitations: string[];
+}
+
+/** Why `CadreNode.removeOwner` refuses by name (`OwnerKeyRemovalRefusedError.code`). */
+export type OwnerKeyRemovalRefusal =
+  /** This node holds no enrolled owner key, so it cannot sign the removal. */
+  | 'not-an-owner'
+  /** No live `OwnerKey` row names the key here (never an owner, or already removed). */
+  | 'unknown'
+  /** The key is the only live owner key (`MinOneOwner`); no owner can remove it. */
+  | 'last-owner'
+  /** The key is this node's own owner key: an owner cannot sign its own row's removal (`A.Key <> old.Key`), so ask another owner key. */
+  | 'self'
+  /** A re-vouch of an `OwnerKey` row was asked for while this node reaches no sibling and the party has other members: the re-added row has no re-issue path. Decided at call time, so never planned. */
+  | 'alone';
+
+/** The rows sharing the owner keys' voucher column that a removed owner key strands unless re-vouched first. */
+export interface OwnerKeyDependents {
+  /** Live `OwnerKey` rows whose `VouchOwner` is the key, this node's own excluded. */
+  owners: string[];
+  /** Live `CadrePeer` rows (peer ids) whose `VouchOwner` is the key, this node's own excluded. */
+  peers: string[];
+}
+
+/**
+ * What `CadreNode.removeOwner` would do for one owner key, read without writing
+ * (`CadreNode.planOwnerKeyRemoval`), for an app's confirmation step.
+ */
+export interface OwnerKeyRemovalPlan {
+  /** The key as `CadreNode.listOwnerKeys` lists it, or null when no live row names it here. */
+  ownerKey: CadreOwnerKey | null;
+  refusal: Exclude<OwnerKeyRemovalRefusal, 'alone'> | null;
+  /** Rows the key vouched, which stop passing the membership predicate on every machine once it is removed unless re-vouched first. */
+  dependents: OwnerKeyDependents;
+  /** This node's own `CadrePeer` row was vouched by the key, so `removeOwner` re-vouches it under this node's key first, unasked: left on the removed key, every other machine would drop this node. */
+  revouchesOwnRow: boolean;
+  /** This node's own `OwnerKey` row was vouched by the key. It cannot re-vouch that row (the re-add's delete would be its own removal); it keeps its place in every anchor that already derived it, and another owner can re-vouch it afterwards. */
   ownDependency: boolean;
+  /** Live owner grants the key issued, which stop being redeemable once it is removed (`OwnerGrantUsage.Authorized` wants a live issuer): an app says "the backup made with this key stops working". Withdrawn, expired and spent grants are not listed. */
+  grants: OwnerGrantRow[];
 }
 
-/** Options for `CadreNode.removeMachine`. */
-export interface RemoveMachineOptions {
+/** Options for `CadreNode.removeOwner`. */
+export interface RemoveOwnerOptions {
   /** Dependents to re-vouch under this node's key before the removal; each must appear in the plan's `dependents`. */
   revouch?: {
     owners?: readonly string[];
@@ -2060,18 +2235,12 @@ export interface RemoveMachineOptions {
   };
 }
 
-/** What `CadreNode.removeMachine` wrote. All false and empty when no live row named the machine here. */
-export interface MachineRemovalResult {
-  removedPeer: boolean;
-  removedOwnerKey: boolean;
-  removedDeviceToken: boolean;
-  /** `CadreInvite` keys whose withdrawal tombstone this call filed. */
-  withdrawnInvitations: string[];
-  /** Dependents re-vouched under this node's key before the removal. */
-  revouched: {
-    owners: string[];
-    peers: string[];
-  };
+/** What `CadreNode.removeOwner` wrote. */
+export interface OwnerKeyRemovalResult {
+  /** The `OwnerKey` row and its tombstone were written; false only when another owner's removal reached this node between the plan and the write. */
+  removed: boolean;
+  /** Rows re-vouched under this node's key before the removal: the dependents asked for, and this node's own row when the plan's `revouchesOwnRow`. */
+  revouched: OwnerKeyDependents;
 }
 
 /**
@@ -2105,14 +2274,36 @@ export interface CadreInviteStatus {
 
 /**
  * What `ControlDatabase.redeemCadreInvite` did. `alreadyMember` is the idempotent
- * retry after a dropped reply: the device's row (and, for an owner-granting
- * invitation, its `OwnerKey` row) was already present, so nothing was written and
- * no seat was spent. The stamps are the live rows' either way.
+ * retry after a dropped reply: the device's row was already present, so nothing was
+ * written and no seat was spent. The stamp is the live row's either way.
  */
 export interface CadreInviteRedemptionResult {
   alreadyMember: boolean;
   peerStampId: string;
-  ownerStampId: string | null;
+}
+
+/**
+ * One {@link OwnerGrantRow} with its standing, as `ControlDatabase.listOwnerGrantStatuses`
+ * reports it. `live` is the redemption's own test: not withdrawn, unexpired, uses left,
+ * issuer still an owner here.
+ */
+export interface OwnerGrantStatus {
+  grant: OwnerGrantRow;
+  live: boolean;
+  withdrawn: boolean;
+  /** Redemptions this node holds for it (`OwnerGrantUsage` rows). */
+  usesRecorded: number;
+}
+
+/**
+ * What `ControlDatabase.redeemOwnerGrant` did. `alreadyOwner` is the idempotent retry after
+ * a dropped reply, and the case of a holder seating a key that is already an owner: the
+ * key's live `OwnerKey` row was already present, so nothing was written and no use was
+ * spent. `seatedStampId` is the live row's either way.
+ */
+export interface OwnerGrantRedemptionResult {
+  alreadyOwner: boolean;
+  seatedStampId: string;
 }
 
 /**
@@ -2120,8 +2311,8 @@ export interface CadreInviteRedemptionResult {
  * `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}.
+ * Never the ledger marker an older party may hold: 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. */
@@ -2138,14 +2329,6 @@ export interface RevocationRow {
   signerSig: string;
 }
 
-/**
- * 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:
@@ -2329,7 +2512,7 @@ export interface ApnsCredentials {
 // ============================================================================
 
 /**
- * A peer entry in a control network seed.
+ * A peer entry in a control network seed, or in a cadre invitation redemption reply.
  * Contains connection information for a cadre peer.
  */
 export interface SeedPeer {
@@ -2337,12 +2520,17 @@ export interface SeedPeer {
   peerId: string;
   /** Multiaddrs for connecting to this peer */
   multiaddrs: string[];
-  /** Whether this peer holds an owner key */
-  isOwner: boolean;
-  /** ed25519 public key (base64url) — present on owner peers for signerKey verification */
-  publicKey?: string;
+  /**
+   * Dial this peer first: the machine that minted the seed (or answered the redemption) and
+   * every always-on machine (`CadrePeer.Profile = 'storage'`). A dial hint only — it grants
+   * nothing, and says nothing about owner keys (`projectSeedPeers`).
+   */
+  preferred: boolean;
 }
 
+/** A peer a seed nominates for dialing, and the addresses to dial it at (`seedDialTargets`). */
+export type SeedDialTarget = Pick<SeedPeer, 'peerId' | 'multiaddrs'>;
+
 /**
  * Control network seed for bootstrapping new nodes.
  * Pre-populates a new node's cache to solve the cold-start problem:
@@ -2553,15 +2741,15 @@ export interface ApplySeedResult {
   /** Machine-readable refusal cause, when the refusing trust policy supplied one. */
   code?: SeedRefusalCode;
   /**
-   * 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
+   * Preferred seed peers (`SeedPeer.preferred`) this apply attempted to dial. Zero when the
+   * seed carried no preferred peer with an address, or when the seed was rejected before
    * the dial loop ran.
    */
-  ownerDialsAttempted: number;
+  preferredDialsAttempted: 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
+   * How many of those dials threw. `preferredDialsAttempted > 0 && preferredDialsFailed
+   * === preferredDialsAttempted` means "seeded but stranded": the seed itself was
+   * accepted (`success: true`) but no preferred peer 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.
@@ -2573,7 +2761,7 @@ export interface ApplySeedResult {
    * down. Treat a non-zero value as certain failure and zero as "no failure
    * observed".
    */
-  ownerDialsFailed: number;
+  preferredDialsFailed: number;
 }
 
 // ============================================================================
@@ -2587,18 +2775,13 @@ export type NodeTopology = 'public' | 'nat';
 
 /**
  * What an owner asks `CadreNode.createCadreInvitation` for. The invitation is a keypair the
- * node mints; whoever holds the returned bundle can redeem it at any member machine.
+ * node mints; whoever holds the returned bundle can redeem it at any member machine. It admits
+ * a machine and grants nothing else; ownership is an owner grant (`CreateOwnerGrantOptions`).
  */
 export interface CreateCadreInvitationOptions {
   /** The one device that may redeem it; omit for whoever redeems first. */
   peerId?: string;
-  /** Whether redemption also makes the device an owner (seats an `OwnerKey` row). */
-  grantsOwner: boolean;
-  /**
-   * Lifetime from now, in ms. Defaults to 15 minutes for an untargeted owner-granting
-   * invitation — a bearer credential for admin rights — and 24 hours otherwise. A negative
-   * value mints an already-expired invitation (tests).
-   */
+  /** Lifetime from now, in ms; default 24 hours. A negative value mints an already-expired invitation (tests). */
   expiresInMs?: number;
   /** How many redemptions it allows; default 1. */
   uses?: number;
@@ -2653,19 +2836,75 @@ export type CadreJoinProgress =
        * least one member answered with a retryable refusal (issuer-unknown, busy, conflict, internal).
        */
       reason: 'no-member-answered' | 'member-not-ready';
-      outcomes: readonly CadreInviteAddressOutcome[];
+      outcomes: readonly RedemptionAddressOutcome[];
     };
 
 /** What `CadreNode.redeemCadreInvitation` returns once a member accepted. */
 export interface RedeemCadreInvitationResult {
   /** The member machine that admitted this device, when its address named one. */
   peerId: string | null;
-  /** Whether the invitation also seated this device's key as an owner. */
-  grantsOwner: boolean;
   /** When the member accepted, ISO 8601. */
   redeemedAt: string;
 }
 
+/**
+ * What an owner asks `CadreNode.createOwnerGrant` for. The grant is a keypair the node mints;
+ * whoever holds the returned bundle can become an owner of this cadre through any member
+ * machine, so it is a bearer credential for admin rights.
+ */
+export interface CreateOwnerGrantOptions {
+  /** The label every key the grant seats will carry; trimmed, at most 64 characters, blank meaning none. */
+  label?: string;
+  /**
+   * Lifetime from now, in ms; default 15 minutes. `null` means NO expiry and must be passed
+   * explicitly: a backup grant, kept as carefully as an owner key. A negative value mints an
+   * already-expired grant (tests).
+   */
+  expiresInMs?: number | null;
+  /** How many redemptions it allows; default 1. */
+  uses?: number;
+}
+
+/** What `CadreNode.createOwnerGrant` returns: the bundle, the same encoded for sharing, and how far it reaches. */
+export interface CreateOwnerGrantResult {
+  grant: OwnerGrantBundle;
+  /** `encodeOwnerGrant(grant)`: `sereus-owner-grant:1.` and base64url JSON, for a QR code, a paste or a file. */
+  encoded: string;
+  /** Whether a holder could redeem it once the minting machine is gone; see {@link CadreInvitationReach}. */
+  reach: CadreInvitationReach;
+}
+
+/** How `CadreNode.redeemOwnerGrant` and `joinWithOwnerGrant` dial the grant's members: the invitation's options, with the same meanings. */
+export type RedeemOwnerGrantOptions = RedeemCadreInvitationOptions;
+
+/** What `CadreNode.redeemOwnerGrant` returns once the key is seated. */
+export interface RedeemOwnerGrantResult {
+  /** The key seated as an owner: the signer's public key. */
+  ownerKey: string;
+  /** The key was already a live owner, so nothing was written and no use of the grant was spent. */
+  alreadyOwner: boolean;
+  /** The member machine that wrote the row, when the redemption went over the protocol and its address named one; null on the local path. */
+  memberPeerId: string | null;
+}
+
+/** What `CadreNode.joinWithOwnerGrant` returns once this node is a member and its key an owner. */
+export interface JoinWithOwnerGrantResult {
+  /** The member machine that admitted this node, when its address named one. */
+  peerId: string | null;
+  /** When the member admitted this node, ISO 8601. */
+  redeemedAt: string;
+  /** The key seated as an owner: the signer's public key. */
+  ownerKey: string;
+  /** The key was already a live owner of the party, so the grant spent no use. */
+  alreadyOwner: boolean;
+  /**
+   * The signer was wired as this node's owner signer, because its `OwnerKey` row reached this
+   * node within the bound. False when the row had not synced in time: the node is a member and
+   * the key an owner all the same, and `CadreNode.wireOwnKeyIfOwner(signer)` wires it later.
+   */
+  ownerWired: boolean;
+}
+
 /**
  * Options for adding a drone via provider API.
  */