@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/seed-bootstrap.d.ts

@@ -1,9 +1,10 @@
 import type { Libp2p } from '@libp2p/interface';
 import { type PeerDialBudget } from './peer-dial.js';
-import type { ControlNetworkSeed, SeedPeer, SeedAckMessage, SeedDeliveryTarget, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, DroneInitResult, CadreInviteRow, PeerAddressRecord, DeviceTokenRecord, RevocationRow, RevocationLedgerOpenResult } from './types.js';
-import type { ControlDatabase, MachineRemovalWrites } from './control-database.js';
+import type { ControlNetworkSeed, SeedPeer, SeedDialTarget, SeedAckMessage, SeedDeliveryTarget, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, DroneInitResult, CadreInviteRow, OwnerGrantRow, PeerAddressRecord, DeviceTokenRecord, RevocationRow, MachineRemovalResult } from './types.js';
+import type { CadrePeerRetouchMode, CadrePeerRetouchOutcome, ControlDatabase } from './control-database.js';
 import { type SeedTrustPolicy } from './seed-trust-policy.js';
 import type { TrustedOwnerStore } from './trusted-owner-store.js';
+import { type OwnerSign, type OwnerSigner } from './owner-signer.js';
 /** Protocol ID for seed delivery */
 export declare const SEED_PROTOCOL = "/sereus/seed/1.0.0";
 /**
@@ -32,6 +33,15 @@ export declare function canonicalSeedPayload(seed: Pick<ControlNetworkSeed, 'par
  * proof to one seed through this value) all name the same bytes.
  */
 export declare function seedDigest(seed: Pick<ControlNetworkSeed, 'partyId' | 'peers'>): string;
+/**
+ * The peers `seed` nominates for dialing: its preferred peers (`SeedPeer.preferred`: the machine
+ * that minted it and every always-on machine) that have an address and are not `selfPeerId`.
+ *
+ * Self is dropped because `createSeed` projects every non-revoked CadrePeer row, so a preferred
+ * machine applying a seed minted after it joined finds itself in the list, and a dial of self
+ * always throws. An undefined `selfPeerId` matches nothing.
+ */
+export declare function seedDialTargets(seed: ControlNetworkSeed, selfPeerId: string | undefined): SeedDialTarget[];
 /**
  * Merge a peer list's addresses into `node`'s peer store, so the node can dial them: the
  * seed's peers after its signature and trust checks, the dial hints a member returns on
@@ -47,10 +57,12 @@ export declare function mergeSeedPeers(node: Libp2p, peers: readonly SeedPeer[])
 export interface SeedBootstrapConfig {
     /** Party ID for this cadre */
     partyId: string;
-    /** Owner private key for signing seeds and peer authorizations (base64url) */
-    ownerPrivateKey?: string;
-    /** Owner public key (base64url) - derived from private key if not provided */
-    ownerPublicKey?: string;
+    /**
+     * The owner signer every seed and owner-signed write of this service goes through
+     * (`owner-signer.ts`). Unset for a listener-only service, which receives and applies seeds
+     * but refuses every owner write.
+     */
+    ownerSigner?: OwnerSigner;
     /**
      * Trust anchor for incoming seeds. Decides whether a signature-verified
      * `signerKey` should be trusted, against the receiver's anchored owner
@@ -107,7 +119,7 @@ export interface SeedBootstrapConfig {
      * sized for the forms that dial inside it. Delivery does not set `runOnLimitedConnection`,
      * so it does not use a limited relayed connection today; the relayed-dial count is the upper
      * bound on the dial it can use, the same choice `CadreNode.controlDialBudget` makes for every
-     * address. It holds only link work because the receiver acks before its owner dials.
+     * address. It holds only link work because the receiver acks before it dials the seed's peers.
      *
      * NOTE: no transfer allowance — a seed is a peer list of a few KB, and `MAX_SEED_SIZE` (1 MiB)
      * is a defensive cap. If seeds ever grow toward that cap, add an allowance the way
@@ -116,7 +128,7 @@ export interface SeedBootstrapConfig {
     seedDeliverTimeoutMs?: number;
     /**
      * Time limits for each peer this service dials from a list of addresses —
-     * {@link SeedBootstrapService.applySeed}'s owner dials and
+     * {@link SeedBootstrapService.applySeed}'s dials of the seed's preferred peers and
      * {@link SeedBootstrapService.deliverSeed}'s dial of a peer id with addresses — per
      * address and per peer (see `peer-dial.ts`). Defaults to {@link DEFAULT_PEER_DIAL_BUDGET}; a `CadreNode`
      * passes its `network.controlCohort` limits.
@@ -130,12 +142,13 @@ export interface SeedEventCallbacks {
     /** Called when a seed is received via the protocol */
     onSeedReceived?: (partyId: string, peerId: string) => void;
     /**
-     * Called when a seed is successfully applied.
+     * Called when a seed delivered over the protocol has been verified, merged and
+     * acknowledged; the dials of its preferred peers follow, so this waits on no connection.
      *
      * `seed` is the applied seed itself: the inbound protocol handler applies it
      * INSIDE the service, so this callback is the only seam through which a
      * `CadreNode` sees a wire-delivered seed's contents — which it needs to
-     * retain the owner-flagged peers as cold-start bootstrap dial targets.
+     * retain the preferred peers as cold-start bootstrap dial targets.
      */
     onSeedApplied?: (partyId: string, peersAdded: number, seed: ControlNetworkSeed) => void;
     /** Called when seed application fails */
@@ -152,7 +165,6 @@ export declare class SeedBootstrapService {
     private readonly config;
     private libp2pNode;
     private controlDatabase;
-    private readonly ownerPublicKey;
     private readonly trustPolicy;
     private readonly seedReadTimeoutMs;
     private readonly maxConcurrentSeeds;
@@ -168,20 +180,21 @@ export declare class SeedBootstrapService {
      */
     setEventCallbacks(callbacks: SeedEventCallbacks): void;
     /**
-     * Whether this service holds an owner private key, i.e. can produce the
-     * owner signatures that gate `CadrePeer` / `DeviceToken` inserts, deletes,
-     * and re-authorizations. A seed-listener-only service (`enableSeedListener`,
-     * no owner key) returns false: it can receive/apply seeds but cannot author
-     * or re-issue owner writes. Used by the write-while-alone re-replication
-     * drain to skip owner work on a non-owner node.
+     * Whether this service holds an owner signer, i.e. can produce the owner signatures that
+     * gate `CadrePeer` / `DeviceToken` inserts, deletes, and re-authorizations. A
+     * seed-listener-only service (`enableSeedListener`, no signer) returns false: it can
+     * receive/apply seeds but cannot author or re-issue owner writes. Used by the
+     * write-while-alone re-replication drain to skip owner work on a non-owner node.
      */
     canAuthorize(): boolean;
+    /** The owner signer this service was built with, or null for a listener-only service. */
+    get ownerSigner(): OwnerSigner | null;
     /**
      * Initialize the service with libp2p node and control database.
      *
      * `registerHandler` (default true) gates registration of the shared inbound
      * `/sereus/seed/1.0.0` handler on `libp2pNode`. Persistent services
-     * (`initializeSeedBootstrap`, `enableSeedListener`) own that handler and leave
+     * (`CadreNode.useOwnerSigner`, `enableSeedListener`) own that handler and leave
      * it on. The throwaway temp service CadreNode builds in `applySeed` passes
      * `false`: it only needs the stored `libp2pNode` / `controlDatabase` for
      * dialing and known-key lookup, and must NOT bind a discarded closure to the
@@ -207,8 +220,11 @@ export declare class SeedBootstrapService {
      * `UpdatedAt` but no self-signature (`Sig` null) — the owner cannot produce
      * the peer's self-signature, so the peer must self-publish (see
      * {@link CadreNode.registerSelf}) before the row resolves.
+     *
+     * @param sign - The signature function of an owner approval the caller already holds, so a
+     *   multi-step action asks once; omitted, this write asks for its own approval.
      */
-    authorizePeer(options: AuthorizePeerOptions): Promise<void>;
+    authorizePeer(options: AuthorizePeerOptions, sign?: OwnerSign): Promise<void>;
     /**
      * Owner-signed INSERT of this node's OWN self-signed address record.
      *
@@ -222,17 +238,16 @@ export declare class SeedBootstrapService {
      *   in which case the row in the database is NOT this record and carries whatever
      *   `Sig` that writer had, so the caller must self-update to publish its signature.
      */
-    insertSelfPeerRecord(record: PeerAddressRecord): Promise<boolean>;
+    insertSelfPeerRecord(record: PeerAddressRecord, sign?: OwnerSign): Promise<boolean>;
     /**
-     * Shared owner-signed `CadrePeer` INSERT — the row fields and the owner-key
+     * Shared owner-signed `CadrePeer` INSERT — the row fields and the owner-signer
      * precondition; the stamp mint, voucher signature, write lock, existence check and
      * membership notify are all {@link ControlDatabase.insertCadrePeer}'s (see there for
      * the anti-replay and insert-race rationale). No `CadrePeer` write may bypass that
      * method: the write is what admits the peer's traffic.
      *
-     * The DB check precedes the owner-key check here, matching the order this method has
-     * always surfaced them (the owner-key error used to come out of the signer, after the
-     * DB check).
+     * The DB check precedes the owner-signer check here, matching the order this method has
+     * always surfaced them.
      *
      * @returns `true` when this call performed the INSERT, `false` when the row was
      *   already seated by a concurrent writer. The loser needs to know: an authorize seats
@@ -257,7 +272,7 @@ export declare class SeedBootstrapService {
      * fresh signature — unaffected by the cleared row's retired stamp
      * (`DeviceToken.NotRevoked`).
      */
-    insertSelfDeviceToken(record: DeviceTokenRecord): Promise<void>;
+    insertSelfDeviceToken(record: DeviceTokenRecord, sign?: OwnerSign): Promise<void>;
     /**
      * Owner-signed DELETE of a peer's `DeviceToken` row (logout / token
      * invalidation). The `DeviceToken.AuthorizedDelete` constraint validates an owner
@@ -276,44 +291,27 @@ export declare class SeedBootstrapService {
      * Both digests, the stamp read, and the transaction come from
      * {@link ControlDatabase.deleteDeviceToken} — one shared implementation across
      * `CadrePeer` / `DeviceToken` / `Strand` / `ValidationKey`. What stays here is the
-     * owner-key precondition; a no-op on an already-absent row is the shared body's
+     * owner-signer precondition; a no-op on an already-absent row is the shared body's
      * behavior, and unlike {@link removePeer} nothing here rides on it.
      */
-    deleteDeviceToken(peerId: string): Promise<void>;
-    /**
-     * Return the configured owner private key, or throw if none is set. The single
-     * precondition gate for every owner-signed write. {@link removePeer} /
-     * {@link reauthorizePeer} read the row's `StampId` from the DB BEFORE they sign, so
-     * they call this up front — otherwise a keyless service would either surface the
-     * wrong "Control database not initialized" error or, worse, silently no-op when the
-     * target row is absent (the early `stampId === null` return) instead of rejecting.
-     */
-    private requireOwnerPrivateKey;
+    deleteDeviceToken(peerId: string, sign?: OwnerSign): Promise<void>;
     /**
-     * The owner PUBLIC key that rides in every owner-signed write's context, non-null.
-     *
-     * The field is nullable because a read-only service carries no owner key at all, but the
-     * constructor derives the public key whenever `ownerPrivateKey` is set — so gating on
-     * {@link requireOwnerPrivateKey} first makes the pair inseparable and the second throw
-     * unreachable. Callers that must reject a keyless service BEFORE any DB read use this as
-     * their first line and get the owner-key precondition for free.
-     */
-    private requireOwnerPublicKey;
-    /**
-     * Sign a base64url digest with the owner key (ed25519). The single place the
-     * owner private key is applied; callers pass the canonical domain-tagged digest for
-     * the specific action ({@link deviceTokenAddDigest}), or the raw-bytes form via
-     * {@link signMessageBytes}. Throws if no owner key is set.
+     * Return the configured owner signer, or throw if none is set. The single precondition
+     * gate for every owner-signed write. {@link removePeer} / {@link reauthorizePeer} read the
+     * row from the DB BEFORE they sign, so they call this up front — otherwise a signerless
+     * service would either surface the wrong "Control database not initialized" error or,
+     * worse, silently no-op when the target row is absent (their early absent return) instead
+     * of rejecting.
      */
-    private signDigest;
+    private requireOwnerSigner;
+    /** The control database {@link initialize} attached, or a throw. */
+    private requireControlDatabase;
     /**
-     * Adapt the control database's raw-bytes `signMessage` callback (every guarded delete
-     * takes one) to {@link signDigest}'s base64url-string form. Both encodings hash to the
-     * same signed bytes (`sign` decodes its base64url input), so a signature minted here
-     * satisfies the same schema CHECK as one from the callers that sign the bytes directly — see
-     * `control-revocation-replay.spec.ts`'s "raw-bytes and digest-string signers agree".
+     * Run `body` with an owner signature function: the caller's `sign` when it passes one (a
+     * `CadreNode` action already inside its approval), otherwise one approval of this service's
+     * signer for `action`, the plain-words description a prompting signer shows.
      */
-    private signMessageBytes;
+    private withOwnerSign;
     /**
      * Remove a peer from the cadre by owner signature.
      *
@@ -336,64 +334,69 @@ export declare class SeedBootstrapService {
      * Both digests, the stamp read, the transaction, and the post-commit membership notify
      * come from {@link ControlDatabase.deleteCadrePeer} — one shared implementation across
      * `CadrePeer` / `DeviceToken` / `Strand` / `ValidationKey`. What stays here is the
-     * owner-key precondition and the absent-row gate the notify depends on (below).
+     * owner-signer precondition and the absent-row gate the notify depends on (below).
      */
-    removePeer(peerId: string): Promise<void>;
+    removePeer(peerId: string, sign?: OwnerSign): Promise<void>;
     /**
-     * Seat `ownerPublicKey` as a further owner, signed by this service's owner key. The
+     * Seat `ownerPublicKey` as a further owner, signed by this service's owner signer. The
      * liveness check, the stamp, the signature and the membership notify are
-     * {@link ControlDatabase.insertOwnerKeyVouched}'s; what stays here is the owner-key
+     * {@link ControlDatabase.insertOwnerKeyVouched}'s; what stays here is the owner-signer
      * precondition, checked before any read (see {@link removePeer}).
      *
+     * @param label - the user's name for the key, bound into the signature
+     *   ({@link ControlDatabase.insertOwnerKey} has the rule).
      * @returns `true` when the row was seated, `false` when the key is already a live owner.
      */
-    addOwner(ownerPublicKey: string): Promise<boolean>;
+    addOwner(ownerPublicKey: string, label?: string, sign?: OwnerSign): Promise<boolean>;
     /**
-     * Remove `ownerPublicKey` from the owners, signed by this service's owner key: the delete
+     * Remove `ownerPublicKey` from the owners, signed by this service's owner signer: the delete
      * and its `Revocation` tombstone in one transaction. The by-name refusals (self-removal,
      * the last owner), the digests and the membership notify are
-     * {@link ControlDatabase.deleteOwnerKey}'s; what stays here is the owner-key precondition,
+     * {@link ControlDatabase.deleteOwnerKey}'s; what stays here is the owner-signer precondition,
      * checked before any read (see {@link removePeer}).
      *
      * @returns `true` when the row was removed, `false` when the key is not a live owner here.
      */
-    removeOwner(ownerPublicKey: string): Promise<boolean>;
+    removeOwner(ownerPublicKey: string, sign?: OwnerSign): Promise<boolean>;
     /**
-     * Re-vouch another owner's row under this service's owner key, so it stands on a remaining
+     * Re-vouch another owner's row under this service's owner signer, so it stands on a remaining
      * owner's signature before the owner that added it is removed
-     * ({@link ControlDatabase.revouchOwnerKey}; for `CadreNode.removeMachine` only). What stays
-     * here is the owner-key precondition, checked before any read (see {@link removePeer}).
+     * ({@link ControlDatabase.revouchOwnerKey}; for `CadreNode.removeOwner` only). What stays
+     * here is the owner-signer precondition, checked before any read (see {@link removePeer}).
      *
      * @returns `true` when the row was re-vouched, `false` when the key is not a live owner here.
      */
-    revouchOwner(ownerPublicKey: string): Promise<boolean>;
+    revouchOwner(ownerPublicKey: string, sign?: OwnerSign): Promise<boolean>;
     /**
-     * Remove a machine completely, signed by this service's owner key: its `CadrePeer` row, its
-     * `OwnerKey` row when `target.ownerKey` names one, its `DeviceToken` row, and the
-     * withdrawal of every invitation in `target.inviteKeys`, all in one transaction
-     * ({@link ControlDatabase.removeMachine}). What stays here is the owner-key precondition,
-     * checked before any read (see {@link removePeer}).
+     * Remove a machine completely, signed by this service's owner signer: its `CadrePeer` row, its
+     * `DeviceToken` row, and the withdrawal of every invitation in `target.inviteKeys`, all in one
+     * transaction ({@link ControlDatabase.removeMachine}). What stays here is the owner-signer
+     * precondition, checked before any read (see {@link removePeer}).
      */
-    removeMachine(target: Parameters<ControlDatabase['removeMachine']>[0]): Promise<MachineRemovalWrites>;
+    removeMachine(target: Parameters<ControlDatabase['removeMachine']>[0], sign?: OwnerSign): Promise<MachineRemovalResult>;
     /**
-     * Owner "re-touch" of an existing `CadrePeer` membership row: bump `UpdatedAt` and
-     * re-vouch the row so it is re-emitted as a fresh, broadcasting transaction. This is
-     * the write-while-alone re-replication primitive (`control-write-ensure-replicated`):
-     * a membership row that committed local-only (its block's cluster ≤1 at insert) is
-     * pushed to the cohort once it grows.
+     * Owner "re-touch" of an existing `CadrePeer` membership row, in one of two modes
+     * ({@link CadrePeerRetouchMode}): `'rebroadcast'` bumps `UpdatedAt` and re-vouches the row so
+     * it is re-emitted as a fresh, broadcasting transaction — the write-while-alone re-replication
+     * primitive (`control-write-ensure-replicated`): a membership row that committed local-only
+     * (its block's cluster ≤1 at insert) is pushed to the cohort once it grows — and writes only
+     * while the machine has not self-published; `'revouch'` rebinds the voucher to this node's
+     * owner key, leaving `UpdatedAt` alone, whether or not the machine has self-published
+     * (`CadreNode.removeOwner`).
      *
-     * The stamp read, the voucher signature, the write lock and the membership notify are
+     * The row read, the mode's decision, the stamp bump, the voucher signature, the write lock,
+     * the lost-update retry and the membership notify are
      * {@link ControlDatabase.reauthorizeCadrePeer}'s — including the caveat that it rebinds
-     * `VouchOwner` to this node's owner key. What stays here is the owner-key precondition.
-     *
-     * A no-op (no throw, no notify) when the row does not exist.
+     * `VouchOwner` to this node's owner key. What stays here is the owner-signer precondition.
      *
      * @param peerId - the membership row to re-touch.
-     * @param updatedAt - the strictly-increasing freshness stamp to write.
-     * @throws if no owner private key is configured (a non-owner cannot
+     * @param mode - re-broadcast or re-vouch.
+     * @returns what was found and done ({@link CadrePeerRetouchOutcome}); an absent row, or a
+     *   self-published one in `'rebroadcast'` mode, writes nothing and does not throw.
+     * @throws if no owner signer is configured (a non-owner cannot
      *   re-sign another peer's row) or the control database is not initialized.
      */
-    reauthorizePeer(peerId: string, updatedAt: number): Promise<void>;
+    reauthorizePeer(peerId: string, mode: CadrePeerRetouchMode, sign?: OwnerSign): Promise<CadrePeerRetouchOutcome>;
     /**
      * Owner re-issue of a batch of `Revocation` tombstones: bump each row's
      * `ReissuedAt` so the storage layer re-broadcasts a tombstone that committed
@@ -404,51 +407,68 @@ export declare class SeedBootstrapService {
      *
      * The signatures, the single transaction, and the strictly-monotonic
      * `reissuedAt` contract are {@link ControlDatabase.reissueRevocations}'s. What
-     * stays here is the owner-key precondition.
+     * stays here is the owner-signer precondition.
      *
      * @returns how many tombstones were re-issued (`rows.length` on success).
-     * @throws if no owner private key is configured or the control database is not
+     * @throws if no owner signer is configured or the control database is not
      *   initialized.
      */
-    reissueRevocations(rows: readonly RevocationRow[], reissuedAt: number): Promise<number>;
-    /**
-     * Owner filing of the singleton `Revocation` ledger marker, so the table is never a
-     * never-written block that the storage layer re-consults on every read.
-     *
-     * The signature, the insert-if-absent guard and the `'already-open'` mapping are
-     * {@link ControlDatabase.openRevocationLedger}'s. What stays here is the owner-key
-     * precondition.
-     *
-     * @throws if no owner private key is configured or the control database is not
-     *   initialized.
-     */
-    openRevocationLedger(): Promise<RevocationLedgerOpenResult>;
+    reissueRevocations(rows: readonly RevocationRow[], reissuedAt: number, sign?: OwnerSign): Promise<number>;
     /**
      * Owner-signed INSERT of a `CadreInvite` row — an invitation any member machine can redeem
      * on this owner's behalf ({@link ControlDatabase.insertCadreInvite}). The keypair mint, the
      * expiry and use-count defaults, and the bundle the holder receives are
-     * `CadreNode.createCadreInvitation`'s; what stays here is the owner-key precondition and
-     * the signature, as {@link insertSelfDeviceToken} keeps them for device tokens.
+     * `CadreNode.createCadreInvitation`'s; what stays here is the owner-signer precondition and
+     * the approval, as {@link insertSelfDeviceToken} keeps them for device tokens.
      *
      * @returns the row as stored, which the invitation bundle carries verbatim.
-     * @throws if no owner private key is configured or the control database is not initialized.
+     * @throws if no owner signer is configured or the control database is not initialized.
      */
-    insertCadreInvite(invite: Parameters<ControlDatabase['insertCadreInvite']>[0]): Promise<CadreInviteRow>;
+    insertCadreInvite(invite: Parameters<ControlDatabase['insertCadreInvite']>[0], sign?: OwnerSign): Promise<CadreInviteRow>;
     /**
      * Owner-signed WITHDRAWAL of a `CadreInvite`: the `Revocation` tombstone over its stamp, with
      * the row kept ({@link ControlDatabase.withdrawCadreInvite}). What stays here is the
-     * owner-key precondition.
+     * owner-signer precondition.
      *
      * @returns `true` when this call filed the tombstone, `false` when the row is absent here or
      *   already withdrawn.
-     * @throws if no owner private key is configured or the control database is not initialized.
+     * @throws if no owner signer is configured or the control database is not initialized.
+     */
+    withdrawCadreInvite(key: string, sign?: OwnerSign): Promise<boolean>;
+    /**
+     * Owner-signed INSERT of an `OwnerGrant` row — a grant of ownership any member machine can
+     * redeem on this owner's behalf ({@link ControlDatabase.insertOwnerGrant}). The keypair mint,
+     * the lifetime default and the bundle the holder receives are `CadreNode.createOwnerGrant`'s;
+     * what stays here is the owner-signer precondition and the approval, as for
+     * {@link insertCadreInvite}. The label is checked before the approval opens, so one the row
+     * would refuse never prompts the user.
+     *
+     * @returns the row as stored, which the grant bundle carries verbatim.
+     * @throws if no owner signer is configured, the control database is not initialized, or the label is too long.
      */
-    withdrawCadreInvite(key: string): Promise<boolean>;
+    insertOwnerGrant(grant: Parameters<ControlDatabase['insertOwnerGrant']>[0], sign?: OwnerSign): Promise<OwnerGrantRow>;
+    /**
+     * Owner-signed WITHDRAWAL of an `OwnerGrant`: the `Revocation` tombstone over its stamp, with
+     * the row kept ({@link ControlDatabase.withdrawOwnerGrant}). What stays here is the
+     * owner-signer precondition.
+     *
+     * @returns `true` when this call filed the tombstone, `false` when the row is absent here or
+     *   already withdrawn.
+     * @throws if no owner signer is configured or the control database is not initialized.
+     */
+    withdrawOwnerGrant(key: string, sign?: OwnerSign): Promise<boolean>;
     /**
      * Create a seed from the current control network state.
-     * The seed contains peer information and is signed by an owner.
+     * The seed contains peer information and is signed by an owner; its `signerKey` is the
+     * owner signer's key.
      */
-    createSeed(): Promise<ControlNetworkSeed>;
+    createSeed(sign?: OwnerSign): Promise<ControlNetworkSeed>;
+    /**
+     * {@link createSeed}, with `selfRelayAddr` added to this node's own peer entry before the
+     * seed is signed: the signature covers every address ({@link seedDigest}), so nothing may
+     * be added after it.
+     */
+    private mintSeed;
     /**
      * Apply a seed to populate the peer cache and enable connections.
      *
@@ -456,9 +476,8 @@ export declare class SeedBootstrapService {
      * `signerKey` that does NOT come from the seed body: the receiver's
      * node-local {@link SeedBootstrapConfig.trustedOwners} anchor, optionally
      * augmented by pinned keys or TOFU via the configured/overriding
-     * `SeedTrustPolicy`. A forged self-asserting seed — one that merely lists its
-     * own signer as an owner peer — no longer passes, and neither does one signed
-     * by a key a stranger genesis-inserted into the replicated `OwnerKey` table.
+     * `SeedTrustPolicy`. A forged self-signed seed does not pass, and neither does
+     * one signed by a key a stranger genesis-inserted into the replicated `OwnerKey` table.
      *
      * A key accepted via a pin/TOFU is persisted into the anchor (the policy says
      * so via `SeedTrustDecision.anchorAs`), so the next seed from that owner is
@@ -475,22 +494,26 @@ export declare class SeedBootstrapService {
     /**
      * The first half of {@link applySeed}: check the signature and the signer's trust, then merge
      * the seed's peer addresses into the peer store. Every rejection happens here, so this result is
-     * what the inbound handler acks with; the owner dials that follow cannot change it.
+     * what the inbound handler acks with; the dials that follow cannot change it.
      */
     private verifyAndMergeSeed;
     /**
-     * The second half of {@link applySeed}: dial the seed's owner peers to establish connections.
+     * The second half of {@link applySeed}: dial the seed's preferred peers (`SeedPeer.preferred`:
+     * the machine that minted it and every always-on machine) to establish connections.
      *
-     * Best-effort and COUNTED: an owner that is momentarily down leaves this node seeded but
+     * Best-effort and COUNTED: a peer that is momentarily down leaves this node seeded but
      * unconnected, which the caller can only see if the outcome is reported (see
-     * `ApplySeedResult.ownerDialsFailed`). Recovery is not this loop's job —
+     * `ApplySeedResult.preferredDialsFailed`). Recovery is not this loop's job —
      * `CadreNode.dialColdStartBootstrap` retries these same addresses on every control-cohort
      * reconcile pass until the control database has siblings.
      *
-     * The inbound handler runs this AFTER it has acked and closed the stream
-     * ({@link handleSeedStream}), because an unreachable owner can take `dialBudget.totalMs`.
+     * The inbound handler runs this AFTER it has acked, closed the stream and reported the seed
+     * applied ({@link handleSeedStream}), because an unreachable peer can take `dialBudget.totalMs`.
+     * The node may stop while these dials are in flight (cadre-cli restarts a claimed node on
+     * `seed:applied`): the node's stop aborts the dial in flight and every later one is refused
+     * at once (`dialAddr`), and each is counted as failed here.
      */
-    private dialSeedOwners;
+    private dialPreferredPeers;
     /**
      * Persist a signer that a pin/TOFU accepted into the node-local anchor, so a
      * later seed from the same owner is anchored without re-supplying the pin
@@ -603,10 +626,10 @@ export declare class SeedBootstrapService {
      */
     validateSeedSignature(seed: ControlNetworkSeed, digestB64?: string): boolean;
     /**
-     * The peers a seed carries: the control database's own projection
+     * The peers a seed `minterPeerId` mints carries: the control database's own projection
      * ({@link ControlDatabase.querySeedPeers}, shared with the cadre invitation redemption
-     * reply), which reads through the revocation filter and flags owners from the replicated
-     * `OwnerKey` table — a dial hint, not a trust decision (the NOTE at `projectSeedPeers`).
+     * reply), which reads through the revocation filter and marks the minter and every
+     * always-on machine preferred — a dial hint, not a trust decision.
      */
     private queryPeers;
     /**
@@ -617,14 +640,16 @@ export declare class SeedBootstrapService {
     private registerProtocolHandler;
     /**
      * Read one inbound seed frame, verify and merge it, write the ack and close the
-     * stream, then dial the seed's owners.
+     * stream, report the seed applied, then dial the seed's preferred peers.
      *
-     * The ack and the close come BEFORE the owner dials: an unreachable owner can hold
-     * a dial for `dialBudget.totalMs` (86 s at the default declared link), which is not
-     * link time and does not belong inside the sender's delivery deadline. The close is
-     * what releases the sender, which reads the ack to end-of-stream. The stream stays
-     * counted in {@link activeStreams} through the dials, so {@link maxConcurrentSeeds}
-     * still bounds concurrent owner-dial phases.
+     * The ack, the close and `onSeedApplied` come BEFORE those dials: an unreachable peer
+     * can hold a dial for `dialBudget.totalMs` (86 s at the default declared link), which is
+     * not link time and does not belong inside the sender's delivery deadline, nor ahead of
+     * a claimed node's restart (which stops this node, so its dials would be wasted). The
+     * close is what releases the sender, which reads the ack to end-of-stream, and it is
+     * awaited before `onSeedApplied`, so the ack is flushed before anything the callback
+     * starts. The stream stays counted in {@link activeStreams} through the dials, so
+     * {@link maxConcurrentSeeds} still bounds concurrent dial phases.
      *
      * Hardened against a buggy/compromised own-cadre node: a concurrency cap (over
      * {@link maxConcurrentSeeds}, reply without applying), a read timeout (a peer
@@ -664,10 +689,12 @@ export declare class SeedBootstrapService {
      * does not listen. Call `CadreNode.reconcileControlCohort()` after delivering
      * the seed to dial at once.
      *
+     * The vouch and the seed are one owner approval.
+     *
      * @param options - Drone peer info from provider API
      * @returns Seed and encoded seed for drone initialization
      */
-    addDrone(options: AddDroneOptions): Promise<DroneInitResult>;
+    addDrone(options: AddDroneOptions, sign?: OwnerSign): Promise<DroneInitResult>;
     /**
      * Add a phone to the cadre with relay support.
      *
@@ -675,8 +702,10 @@ export declare class SeedBootstrapService {
      * 1. Authorizes the new phone peer
      * 2. Creates a seed with relay addresses for dialing
      *
+     * The vouch and the seed are one owner approval.
+     *
      * @param phonePeerId - Peer ID of the new phone
      * @returns Seed with relay addresses for out-of-band delivery
      */
-    addPhoneWithRelay(phonePeerId: string): Promise<DroneInitResult>;
+    addPhoneWithRelay(phonePeerId: string, sign?: OwnerSign): Promise<DroneInitResult>;
 }