@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/types.d.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';
@@ -36,6 +39,23 @@ 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>;
 }
 /**
  * Node profile determines storage participation
@@ -544,8 +564,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;
         /**
@@ -613,10 +638,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`
@@ -723,11 +748,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;
     /** Slot id for the node identity in {@link keyStore}. Default: `'cadre/identity'`. */
@@ -782,10 +806,11 @@ export interface CadreNodeConfig {
     strandClusterSize?: number;
     /**
      * 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}.
@@ -812,13 +837,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.
@@ -830,9 +856,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;
     /**
@@ -844,9 +871,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;
@@ -855,21 +881,27 @@ 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;
     /** 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;
     /**
      * Require a valid author signature on every sApp schema before a strand is
@@ -900,7 +932,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.
      *
@@ -952,7 +984,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'>;
@@ -1175,16 +1207,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;
 }
 /**
  * A `CadreControl.JoinRequest` row: a join this party asked for through another party's
@@ -1305,7 +1342,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.
      */
@@ -1357,6 +1394,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
@@ -1390,6 +1435,35 @@ 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
  */
@@ -1643,14 +1717,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.
      *
@@ -1711,10 +1785,17 @@ export interface CadreNodeEvents {
         partyId: string;
         peerId: string;
     };
-    /** Emitted when a seed is successfully applied */
+    /**
+     * 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': {
@@ -1726,10 +1807,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;
@@ -1820,25 +1901,27 @@ export interface CadrePeerRow {
 export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig' | 'vouchUsage'>;
 /**
  * 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;
 }
 /**
@@ -1870,30 +1953,70 @@ 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. */
     peerSig: string;
 }
 /**
- * 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>;
     invites: Map<string, CadreInviteRow>;
 }
 /**
- * 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
@@ -1902,74 +2025,112 @@ 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. */
-    ownDependency: boolean;
-}
-/** Options for `CadreNode.removeMachine`. */
-export interface RemoveMachineOptions {
-    /** Dependents to re-vouch under this node's key before the removal; each must appear in the plan's `dependents`. */
-    revouch?: {
-        owners?: readonly string[];
-        peers?: readonly string[];
-    };
 }
 /** 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[];
+}
+/** 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.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[];
+        peers?: readonly 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;
+}
 /**
  * This node's own removal from its cadre, as it learned it: the `CadrePeer` tombstone naming
  * its peer id, read after it had seen its own live row (`CadreNode.removedFromCadre`, the
@@ -1999,22 +2160,42 @@ 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;
 }
 /**
  * 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.
- * 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. */
@@ -2030,13 +2211,6 @@ export interface RevocationRow {
     /** That owner's signature over the tombstone's `'remove'` digest (`Revocation.SignerSig`). */
     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:
@@ -2197,7 +2371,7 @@ export interface ApnsCredentials {
     production?: boolean;
 }
 /**
- * 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 {
@@ -2205,11 +2379,15 @@ 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:
@@ -2399,15 +2577,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.
@@ -2419,7 +2597,7 @@ export interface ApplySeedResult {
      * down. Treat a non-zero value as certain failure and zero as "no failure
      * observed".
      */
-    ownerDialsFailed: number;
+    preferredDialsFailed: number;
 }
 /**
  * Node network topology type for seed helper scenarios.
@@ -2427,18 +2605,13 @@ export interface ApplySeedResult {
 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;
@@ -2490,17 +2663,68 @@ 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.
  */