@serfab/cadre-core 1.13.0 → 1.15.0

package/dist/types.d.ts

@@ -8,6 +8,7 @@ import type { StrandRevocationEnforcementConfig } from './strand-revocation-enfo
 import type { StrandMembershipReconciliationConfig } from './strand-membership-reconciler.js';
 import type { StrandFirstSyncConfig } from './strand-first-sync-gate.js';
 import type { StrandDatabase } from './strand-database.js';
+import type { StrandCommitDurability, StrandCommitHeld } from './strand-commit-durability.js';
 import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
 import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
@@ -16,9 +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 { RevocableTable } from './control-authorization.js';
+import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
+import type { CadreInvitation, CadreInviteAddressOutcome } from './cadre-invite-protocol.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 import type { FormationRejectionCode } from './strand-formation-rejection.js';
+import type { ListenTransportOptions } from './relay-addrs.js';
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
  * createLibp2pNode after node creation (not surfaced on the base Libp2p type).
@@ -368,6 +371,20 @@ export interface NetworkConfig {
      * ```
      */
     transports?: Libp2pTransports;
+    /**
+     * Builds `@optimystic/db-p2p`'s default transport list, for the one case where cadre has to
+     * pass a list itself while {@link transports} is unset: a node with configured relays, which
+     * is built with libp2p's relay discovery switched off (`node-transports.ts`). Called with the
+     * switches the node's listen entries imply (`wsPort` when one names WebSocket). Ignored when
+     * {@link transports} is set.
+     *
+     * A Node host passes `nodeDefaultTransports` from the Node-only
+     * `@serfab/cadre-core/node-default-transports` subpath, as `cadre-cli` does. It is injected
+     * rather than built in, because that list names `@libp2p/tcp`, which must stay out of the
+     * graph React Native and browser bundles reach. Left unset, such a node is built from
+     * db-p2p's own list with relay discovery on.
+     */
+    defaultTransports?: (listen: ListenTransportOptions) => Libp2pTransports;
     /**
      * Crypto primitives for the Noise handshake and the encrypted connection that
      * follows, threaded to both the control node and every strand's cohort node — every
@@ -534,7 +551,7 @@ export interface NetworkConfig {
         /**
          * Limit on dialing ONE peer — all of its candidate addresses together — in
          * ms. Bounds a reconcile pass at (dialed siblings) × this. The same limit
-         * applies to the owner dials of `applySeed` and to `dialInvite`. Defaults to
+         * applies to the owner dials of `applySeed`. Defaults to
          * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}.
          */
         dialTimeoutMs?: number;
@@ -591,6 +608,16 @@ export interface NetworkConfig {
  * kept it (the same pair aborted at a 200ms stall only when the deadline was 300ms). An
  * interval strictly above the deadline is what makes the 30 seconds real.
  *
+ * WHY THE OTHER END'S PING HANDLER CAPS IT TOO. The node being pinged echoes through
+ * `@libp2p/ping`'s inbound handler, which aborts the ping stream when its own timer fires; the
+ * 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.
+ *
  * 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`
  * over a relayed circuit measured 3016 ms at 1500 ms one-way). At the slowest link sereus
@@ -777,7 +804,7 @@ export interface CadreNodeConfig {
      * should enable it, because a node without it neither announces nor serves as part of the
      * group a notification is rooted at. Enabling registers Optimystic's change-notification
      * protocol handlers on the strand node, which the closed-strand per-stream gate does not
-     * cover, and each watched table pays a cold-start proof of work on every node build. Both
+     * cover, and each watched table registers again on every node build. Both
      * are spelled out in `docs/strands.md` → "Change notifications (reactivity)". The control
      * node never gets it.
      */
@@ -860,9 +887,43 @@ export interface CadreNodeConfig {
      * inside SeedBootstrapService when unset — a node whose node-local trusted-owner
      * anchor was never seeded then rejects every seed. A per-call
      * `applySeed(seed, { trustPolicy })` override still wins over this default for
-     * callers that hold out-of-band material (e.g. a pinned key from a CadreInvite).
+     * callers that hold out-of-band material (e.g. an operator-pinned owner key).
      */
     seedTrustPolicy?: SeedTrustPolicy;
+    /**
+     * Start this node waiting to be CLAIMED: it belongs to nobody until someone delivers
+     * a seed carrying a proof of this one-time secret (`claim-proof.ts`,
+     * `claimSecretTrustPolicy`), and that signer becomes its anchored owner. The node
+     * turns its seed listener on itself and, while unclaimed, lets a stranger do nothing
+     * but deliver a seed: connections are admitted, control-database streams and relay
+     * reservations are refused (`CadreNode.isAwaitingClaim`).
+     *
+     * 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
+     * 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.
+     *
+     * The claim also decides which party the node serves: `controlNetwork.partyId` on an
+     * unclaimed node is a placeholder, and the real party is the claim seed's. The node
+     * itself keeps serving the placeholder for the rest of the process — everything it
+     * holds is keyed on the party it started with — so `record` is where the embedder
+     * learns the claimed party, and it is the embedder's job to restart into it.
+     */
+    claim?: {
+        /** The one-time claim secret, base64url of 32 bytes. Never written to replicated state or logs. */
+        secret: string;
+        /**
+         * Record the claim durably: called with the seed's party and the claimant's key after
+         * the proof verifies and BEFORE the claimant is anchored, and awaited. A rejection
+         * refuses the claim `claim-not-persisted` with nothing anchored, so the claimant
+         * retries. Record first, anchor second: a crash between the two leaves a record and
+         * an empty anchor, and an embedder that starts from its record (cadre-cli does)
+         * then comes up claimed by that owner, who is accepted idempotently when it retries.
+         * The other order would leave an anchored node with no record of its party.
+         */
+        record: (claim: NodeClaimRecord) => Promise<void>;
+    };
     /**
      * Node-local trusted-owner anchor (see `trusted-owner-store.ts`): the
      * NON-replicated, per-party record of owner keys established out of band —
@@ -883,16 +944,18 @@ export interface CadreNodeConfig {
         /**
          * Owner keys (base64url ed25519) established out of band and seeded into
          * the store during start(): operator pins (e.g. cadre-cli
-         * `--pin-owner-key` / `CADRE_OWNER_KEYS`) or a `CadreInvite.ownerKeys`
-         * already known at config time. Seeding is idempotent across restarts.
+         * `--pin-owner-key` / `CADRE_OWNER_KEYS`). A cadre invitation's `ownerKeys`
+         * are pinned at redemption instead (`CadreNode.redeemCadreInvitation`).
+         * Seeding is idempotent across restarts.
          */
         pinnedKeys?: string[];
         /**
          * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
          * ('genesis' is reserved for the node's own founding key, seeded
-         * internally by `initializeSeedBootstrap`.)
+         * internally by `initializeSeedBootstrap`; 'chain' is written only by the
+         * anchor sync, `CadreNode.syncOwnerAnchor`.)
          */
-        pinnedSource?: Exclude<TrustSource, 'genesis'>;
+        pinnedSource?: Exclude<TrustSource, 'genesis' | 'chain'>;
     };
     /**
      * Node-local cold-start bootstrap-peer store (see `bootstrap-peer-store.ts`):
@@ -1124,13 +1187,11 @@ export interface StrandRow {
     FounderOwnerKey: string | null;
 }
 /**
- * A `CadreControl.PendingJoin` row: a join this party asked for through another party's
- * invitation, readable by every machine of the party. Each outcome carries only its own
- * columns (the schema's `OutcomeShape` check): `'joined'` sets `StrandId` (and, for a
- * closed strand, `MembershipInvite`), `'failed'` sets `FailureCode`, and a pending row
- * (`Outcome: null`) sets neither.
+ * A `CadreControl.JoinRequest` row: a join this party asked for through another party's
+ * invitation, readable by every machine of the party. The row never changes; its outcome is
+ * a `JoinSuccess` or `JoinFailure` row keyed by `StampId` (see {@link PendingJoin}).
  */
-export interface PendingJoinRow {
+export interface JoinRequestRow {
     /** base64url sha256 of the invitation token (`pendingJoinId`). */
     Id: string;
     /** `CadreNode.encodeInvitation` of the invitation. A bearer credential. */
@@ -1141,30 +1202,45 @@ export interface PendingJoinRow {
     RequestedAt: number;
     /** Epoch ms; no attempt starts at or after it. */
     ExpiresAt: number;
-    Outcome: null | 'joined' | 'failed';
-    /** Epoch ms the outcome was recorded; null while pending. */
-    OutcomeAt: number | null;
-    /** `'joined'`: the strand the formation returned. */
-    StrandId: string | null;
-    /** `'joined'`, closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
-    MembershipInvite: string | null;
-    /** `'failed'`: a `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
-    FailureCode: string | null;
-    /** `'failed'`: human-readable text. */
-    FailureReason: string | null;
-    /** Single-use nonce of this row incarnation; `ControlDatabase.replacePendingJoin` names it as the row it replaces. */
+    /** Single-use nonce of this request incarnation; its outcome rows name it. */
     StampId: string;
 }
+/**
+ * The outcome of a {@link JoinRequestRow}: a `CadreControl.JoinSuccess` row (`'joined'`) or
+ * a `CadreControl.JoinFailure` row (`'failed'`), without the request stamp that keys it.
+ */
+export type JoinOutcome = {
+    kind: 'joined';
+    /** Epoch ms the outcome was recorded. */
+    RecordedAt: number;
+    /** The strand the formation returned. */
+    StrandId: string;
+    /** Closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
+    MembershipInvite: string | null;
+} | {
+    kind: 'failed';
+    /** Epoch ms the outcome was recorded. */
+    RecordedAt: number;
+    /** A `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
+    Code: string;
+    /** Human-readable text. */
+    Reason: string;
+};
+/** A join request with its outcome, as `ControlDatabase.queryPendingJoins` reads the three tables. */
+export interface PendingJoin extends JoinRequestRow {
+    /** Null while pending. */
+    outcome: JoinOutcome | null;
+}
 /**
  * A join this party asked for through `CadreNode.requestJoin`, as one machine sees it.
  *
- * `pending`, `joined` and `failed` come from the party-wide `PendingJoin` row and read the same
+ * `pending`, `joined` and `failed` come from the party-wide join request and its outcome row and read the same
  * on every machine. `trying` (an attempt is running on this machine) and `waiting` (this
  * machine's last attempt failed in a way worth retrying) are this machine's own view of a
  * pending row, so two machines can report different states for it.
  */
 export interface PendingJoinStatus {
-    /** `PendingJoin.Id`: the sha256 of the invitation token. */
+    /** `JoinRequest.Id`: the sha256 of the invitation token. */
     id: string;
     sAppId: string;
     /** Epoch ms. */
@@ -1377,7 +1453,7 @@ export interface StrandMembershipInvite {
      * whoever holds it can `consumeInvite` exactly once. Same sensitivity class and
      * handling as `memberPrivateKey` — delivered only inside the validated,
      * post-approval formation result. The inviting side never writes it to its control
-     * DB. The joining side may copy it into its own `PendingJoin` row
+     * DB. The joining side may copy it into its own `JoinSuccess` row
      * (`MembershipInvite`), owner-signed and party-private like
      * `JoinedStrand.MemberPrivateKey`, so a join finished on one machine of the party
      * can be seated by whichever machine launches the strand first.
@@ -1489,6 +1565,24 @@ export interface CadreNodeEvents {
     'strand:writable': {
         strandId: string;
     };
+    /**
+     * Emitted after every commit on a strand's database that wrote something, with whether
+     * another member already holds it (`heldElsewhere`) and whether `strand:commit-held` will
+     * say when it does (`followed`). Synchronous, inside the commit, before the app's statement
+     * returns: keep handlers short. Covers every commit on the strand database, cadre-core's own
+     * membership writes included, so filter by the ids you hold — the `StampId()` a
+     * `returning StampId() as Tx` statement gave you. The same record is readable afterwards with
+     * `StrandDatabase.commitDurability(tx)`. See docs/strands.md, "A commit's durability".
+     */
+    'strand:commit-durability': StrandCommitDurability;
+    /**
+     * Emitted once when a commit reported `followed` below full replication becomes held by every
+     * member of its cohort — the moment a write made while the others were away reaches them.
+     * Synchronous, like `strand:commit-durability`, and can come right after it inside the same
+     * commit. Never emitted for a commit made before your listener attached, or one forgotten
+     * because its database closed, hibernated or the node restarted.
+     */
+    'strand:commit-held': StrandCommitHeld;
     /**
      * Emitted when this node discovers it is no longer a member of a CLOSED
      * strand — its party was removed by a manager, or it left. Detected by the
@@ -1627,6 +1721,30 @@ export interface CadreNodeEvents {
         partyId: string;
         error: string;
     };
+    /**
+     * Emitted once on a node started with `CadreNodeConfig.claim`, when a seed carrying a
+     * 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
+     * matching predicate for a reader that subscribed too late to see the event.
+     */
+    'claim:accepted': NodeClaimRecord;
+    /**
+     * Emitted once per node object when this node learns that an owner removed it from the
+     * cadre: a `CadrePeer` tombstone names its peer id, it has no live `CadrePeer` row, and a
+     * membership refresh of this process had seen its live row before. `CadreNode.removedFromCadre`
+     * is the matching query for a reader that subscribed too late.
+     *
+     * BEST-EFFORT: it fires only if the tombstone reached this node before the other machines
+     * cut it off, so a machine that was offline at removal time usually never sees it. Nothing
+     * is stopped or deleted for you; the node only stops its owner re-issue drains, which can no
+     * longer succeed. Stopping the node and deleting the cadre's data are the embedder's.
+     */
+    'cadre:removed': CadreRemoval;
 }
 /**
  * A peer's self-published, freshness-stamped, self-signed address record.
@@ -1637,8 +1755,8 @@ export interface CadreNodeEvents {
  * PeerId by reading the record, re-verifying the self-signature against
  * `publicKey`, checking freshness, and applying a trust gate.
  *
- * The signature covers `peerId`, the comma-joined `addrs`, and `updatedAt` — see
- * `peerRecordSignedPayload`. `publicKey` is NOT inside the signed payload: it is
+ * The signature covers `peerId`, the comma-joined `addrs`, `updatedAt` and `profile` —
+ * see `peerRecordSignedPayload`. `publicKey` is NOT inside the signed payload: it is
  * the key the signature is verified *with*, and its libp2p-identity binding to
  * `peerId` is checked separately at resolve time, so re-signing it would be
  * redundant.
@@ -1652,34 +1770,244 @@ export interface PeerAddressRecord {
     addrs: string[];
     /** epoch ms — freshness; strictly increasing per peer. */
     updatedAt: number;
+    /**
+     * The publisher's own {@link CadreNodeConfig.profile}: `'transaction'` is an app (phone,
+     * browser), `'storage'` an always-on node. Null on a row the machine has not yet
+     * self-published (an owner or an invitation seated it).
+     */
+    profile: NodeProfile | null;
     /** ed25519 self-signature over the signed payload, base64url. */
     sig: string;
 }
 /**
  * One `CadreControl.CadrePeer` row as read by `ControlDatabase.queryCadrePeers`:
- * the addressing columns plus the persisted membership voucher.
+ * the addressing columns plus the persisted membership proof.
  *
- * The voucher triple (`stampId`, `vouchOwner`, `vouchSig`) is what
+ * A row carries exactly one proof. An owner-vouched row has `vouchSig`, the owner's
+ * signature over the row's (`peerId`, `stampId`), which
  * {@link CadreNode.listAuthorizedMembers} re-checks against the node-local
- * trusted-owner anchor — it is null on a row written before the voucher columns
- * existed, and all three must be present for the row to be authorizable. Named
- * (rather than restated inline at each read site) so a future column addition
- * cannot reach the query without the predicate seeing it.
+ * trusted-owner anchor. An invitation-admitted row has `vouchSig` null and
+ * `vouchUsage` naming the `CadreInviteUsage` row that admitted it; the reader
+ * verifies the chain row → usage → invitation instead (`verifyInvitationAdmission`),
+ * with `vouchOwner` the invitation's issuer. All columns are null on a row written
+ * before they existed, and such a row is never authorizable. Named (rather than
+ * restated inline at each read site) so a future column addition cannot reach the
+ * query without the predicate seeing it.
  */
 export interface CadrePeerRow {
     /** libp2p peer ID (base58btc) — the row key. */
     peerId: string;
+    /** ed25519 public key (base64url) stored for the peer, or null (not ed25519, or a row written before the column). */
+    publicKey: string | null;
     /** Comma-joined dialable multiaddrs as stored, or null when unpublished. */
     multiaddr: string | null;
-    /** Single-use anti-replay nonce the voucher signature is bound to. */
+    /** The machine's freshness stamp (epoch ms); 0 when it has never self-published. */
+    updatedAt: number;
+    /** The machine's self-declared node profile; null until it self-publishes. */
+    profile: NodeProfile | null;
+    /** The machine's self-signature over its address record (`peerRecordSignedPayload`); null until it self-publishes. */
+    sig: string | null;
+    /** Single-use anti-replay nonce the voucher signature, or the usage row, is bound to. */
     stampId: string | null;
-    /** ed25519 public key (base64url) of the owner that vouched this row. */
+    /** ed25519 public key (base64url) of the owner that vouched this row, or that issued the invitation that admitted it. */
     vouchOwner: string | null;
-    /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', peerId, stampId)`, base64url. */
+    /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', partyId, peerId, stampId)`, base64url; null on an invitation-admitted row. */
     vouchSig: string | null;
+    /** The `CadreInviteUsage.UsageStampId` that admitted this row; null on an owner-vouched row. */
+    vouchUsage: string | null;
+}
+/** The proof-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
+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.
+ */
+export interface OwnerKeyRow {
+    /** ed25519 public key (base64url) — the row key. */
+    key: string;
+    /** 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. */
+    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. */
+    vouchSig: string | null;
+    /** The `CadreInviteUsage.UsageStampId` that admitted this row; null otherwise. */
+    vouchUsage: string | null;
+}
+/**
+ * One `CadreControl.CadreInvite` row: an owner-signed invitation to join the cadre,
+ * as `ControlDatabase.insertCadreInvite` returns it and `queryCadreInvite` reads it.
+ * Every column is here because the row travels: the holder carries it inside the
+ * invitation bundle and a member re-seats it verbatim (`seatCadreInvite`), so
+ * `expiresAt` is the engine-canonical `datetime` string the row stores, not epoch
+ * ms — the `'add'` signature covers that exact text. The signed subset is
+ * `CadreInviteSignedFields` (`control-authorization.ts`).
+ */
+export interface CadreInviteRow extends CadreInviteSignedFields {
+    /** 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.CadreInviteUsage` row: a redemption of a {@link CadreInviteRow},
+ * as `ControlDatabase.queryCadreInviteUsages` reads it. The two signatures are
+ * stored so any reader can re-verify the admission chain (`verifyInvitationAdmission`).
+ */
+export interface CadreInviteUsageRow {
+    /** The redemption's single-use nonce (the row key), signed into both signatures. */
+    usageStampId: string;
+    /** The `CadreInvite.Key` redeemed. */
+    inviteKey: string;
+    /** The admitted device's libp2p peer id — the identity multihash of `peerKey`. */
+    peerId: string;
+    /** The admitted device's ed25519 public key (base64url). */
+    peerKey: string;
+    /** The `CadrePeer.StampId` this redemption seated (or found 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.
+ */
+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).
+ *
+ * `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
+ * `UpdatedAt` without re-signing, or a row the machine never published, reports nothing
+ * rather than someone else's stamp.
+ */
+export interface CadreMachine {
+    peerId: string;
+    /** ed25519 public key (base64url) behind `peerId`; null when the id is not ed25519. */
+    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. */
+    vouchedBy: string | null;
+}
+/** 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';
+/**
+ * What `CadreNode.removeMachine` would do for one machine, read without writing
+ * (`CadreNode.planMachineRemoval`), for an app's confirmation step.
+ */
+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[];
+    };
+}
+/**
+ * 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
+ * `cadre:removed` event; "Removing a machine" in docs/architecture.md).
+ */
+export interface CadreRemoval {
+    /** The cadre this node was removed from (`CadreNode.partyId`). */
+    partyId: string;
+    /** The `StampId` the tombstone retired. */
+    stampId: string;
+    /** The owner key that filed the tombstone, when its signature verifies and the key is in this node's trusted-owner anchor; null otherwise. */
+    signerKey: string | null;
+    /** When this node learned of the removal (epoch ms). */
+    at: number;
+}
+/**
+ * One {@link CadreInviteRow} with its standing, as `ControlDatabase.listCadreInviteStatuses`
+ * (and `CadreNode.listCadreInvitations`) reports it. `live` is the redemption's own test:
+ * not withdrawn, unexpired, uses left, issuer still an owner here.
+ */
+export interface CadreInviteStatus {
+    invite: CadreInviteRow;
+    live: boolean;
+    withdrawn: boolean;
+    /** Redemptions this node holds for it (`CadreInviteUsage` rows). */
+    usesRecorded: number;
+}
+/**
+ * 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.
+ */
+export interface CadreInviteRedemptionResult {
+    alreadyMember: boolean;
+    peerStampId: string;
+    ownerStampId: string | null;
 }
-/** The voucher-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
-export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig'>;
 /**
  * One `CadreControl.Revocation` tombstone as read by
  * `ControlDatabase.queryRevocations`: the identity triple plus the `ReissuedAt`
@@ -1697,6 +2025,10 @@ export interface RevocationRow {
     stampId: string;
     /** Monotonic re-issue counter; carries no semantics (see the schema comment). */
     reissuedAt: number;
+    /** The owner key that filed the tombstone (`Revocation.SignerKey`). */
+    signerKey: string;
+    /** That owner's signature over the tombstone's `'remove'` digest (`Revocation.SignerSig`). */
+    signerSig: string;
 }
 /**
  * Outcome of `ControlDatabase.openRevocationLedger`: `'opened'` when this call filed the
@@ -1907,6 +2239,47 @@ export interface SeedMessage {
     signature: string;
     /** The owner key that signed this message */
     signerKey: string;
+    /**
+     * Proof that the sender holds the receiving node's one-time claim secret
+     * (`claim-proof.ts`), sent only when claiming a brand-new node. Rides beside
+     * the seed rather than inside `ControlNetworkSeed`: it is not part of what the
+     * owner signs, and a claimed node never needs it again.
+     *
+     * The protocol id stays `/sereus/seed/1.0.0` and no version field is added:
+     * there is no backwards compatibility yet, a receiver without this feature
+     * ignores the field and refuses by its anchored policy, and a sender without it
+     * gets a definite refusal (`claim-proof-invalid`) from an unclaimed node.
+     */
+    claimProof?: string;
+}
+/**
+ * Why a seed was refused, for callers that must branch on the cause without
+ * parsing the human-readable `reason`. The phone claiming a node needs to tell
+ * "someone else already claimed it" from "wrong secret".
+ *
+ *  - `already-claimed`: the node's anchor already holds an owner key other than
+ *    the signer's; the claim secret is no longer consulted.
+ *  - `claim-proof-invalid`: the node is unclaimed and the seed carried no claim
+ *    proof, or a proof that does not verify.
+ *  - `claim-rate-limited`: too many failed proofs recently; the proof was not
+ *    verified. Retry after the window.
+ *  - `claim-not-persisted`: the proof verified but the node could not durably
+ *    record the claim; nothing was anchored, so the same claim may be retried.
+ */
+export type SeedRefusalCode = 'already-claimed' | 'claim-proof-invalid' | 'claim-rate-limited' | 'claim-not-persisted';
+/**
+ * What a claim settles for the node that accepted it: the party it serves from now on
+ * and the owner it belongs to. Both come from the claim seed — the party is the seed's
+ * `partyId`, the owner the key that signed it — because an unclaimed node's own
+ * configured party is a placeholder; nobody could know the real one before the claim.
+ * Handed to `CadreNodeConfig.claim.record` before the owner is anchored, and carried by
+ * `claim:accepted`.
+ */
+export interface NodeClaimRecord {
+    /** The party the claim seed named: the cadre this node now serves. */
+    partyId: string;
+    /** The claimant's ed25519 owner key (base64url): the key the claim anchors. */
+    ownerKey: string;
 }
 /**
  * Acknowledgment message from new node to instigator.
@@ -1916,6 +2289,8 @@ export interface SeedAckMessage {
     accepted: boolean;
     /** Reason for rejection (if not accepted) */
     reason?: string;
+    /** Machine-readable refusal cause, when the refusing policy supplies one. */
+    code?: SeedRefusalCode;
 }
 /**
  * Request sent over the control network's `WAKE_PROTOCOL` from a same-cadre peer
@@ -1968,12 +2343,14 @@ export interface StrandAddrRequest {
  *
  * - `ok` — looked up; `multiaddrs` is the truth, possibly empty (strand not running here).
  * - `unavailable` — the responder could not answer: over its concurrency cap, the
- *   request was unreadable, or its own lookup threw (e.g. a control-database read failed).
- * - `refused` — the requester is not an authorized member in the responder's
- *   current view (possibly because its `CadrePeer` row has not replicated there yet);
- *   any `delegatePeerId` it carried was NOT recorded.
+ *   request was unreadable, or its own lookup threw.
+ *
+ * A requester the responder does not count as an authorized member (possibly because
+ * its `CadrePeer` row has not replicated there yet) gets no response at all: the
+ * responder's protocol guard resets the stream, and any `delegatePeerId` it carried
+ * is not recorded.
  */
-export type StrandAddrStatus = 'ok' | 'unavailable' | 'refused';
+export type StrandAddrStatus = 'ok' | 'unavailable';
 /**
  * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
  * multiaddrs, returned on the same stream.
@@ -1998,6 +2375,17 @@ export interface AuthorizePeerOptions {
     /** Optional multiaddrs for the peer */
     multiaddrs?: string[];
 }
+/**
+ * Where `deliverSeed` sends a seed: one multiaddr string, dialed as given, or a
+ * peer id with its known addresses. The object form merges the addresses into
+ * the peer store and dials by peer id, so an existing connection is reused and
+ * libp2p tries every address under the one delivery deadline. It is what a phone
+ * uses to claim a node from the addresses it scanned.
+ */
+export type SeedDeliveryTarget = string | {
+    peerId: string;
+    multiaddrs: string[];
+};
 /**
  * Result of applying a seed to a node.
  */
@@ -2008,6 +2396,8 @@ export interface ApplySeedResult {
     peersAdded: number;
     /** Error message if not successful */
     error?: string;
+    /** 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
@@ -2023,7 +2413,8 @@ export interface ApplySeedResult {
      * `CadreNode.dialColdStartBootstrap`), so this is a signal, not a fatal error.
      *
      * Zero failures is NOT proof of a live connection: the receiving node's
-     * membership gate denies AFTER the dialer's upgrade completes (see
+     * connection gate decides AFTER the dialer's upgrade completes, and closes a
+     * provisionally admitted connection at its deadline (see
      * `createMembershipConnectionGater`), so a dial can resolve and then be torn
      * down. Treat a non-zero value as certain failure and zero as "no failure
      * observed".
@@ -2035,30 +2426,80 @@ export interface ApplySeedResult {
  */
 export type NodeTopology = 'public' | 'nat';
 /**
- * Invite code for phone-to-server enrollment.
- * Used when a server invites a phone to join the cadre.
+ * 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.
  */
-export interface CadreInvite {
-    /** Party ID of the cadre */
-    partyId: string;
-    /** Multiaddrs to dial the owner */
-    ownerAddrs: string[];
-    /**
-     * Owner ed25519 public keys (base64url) of the cadre, carried out-of-band
-     * so a cold-start invitee can pin the trusted owner set before applying
-     * any seed (the seed itself cannot vouch for its own signer). Populated by
-     * `createInvite` from the issuer's OWN node-local trusted-owner anchor —
-     * not its replicated `OwnerKey` table, because the invitee anchors whatever
-     * arrives here and a stranger's genesis-inserted key must not ride an
-     * otherwise-legitimate invite into a fresh node's anchor.
-     */
-    ownerKeys?: string[];
-    /** Optional invite token for validation */
-    token?: string;
-    /** Timestamp when invite was created */
-    createdAt: number;
-    /** Optional expiration timestamp */
-    expiresAt?: number;
+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).
+     */
+    expiresInMs?: number;
+    /** How many redemptions it allows; default 1. */
+    uses?: number;
+}
+/**
+ * Where a phone could redeem a cadre invitation from, judged on the addresses of machines
+ * other than the one that minted it — the answer to "can the new app join once this one is
+ * closed?". A minting machine that is itself always on can therefore read `issuer-only`.
+ */
+export type CadreInvitationReach = 
+/** Another machine has a relayed (`/p2p-circuit`), public-name or public-IP WebSocket address. */
+'anywhere'
+/** Other machines are named, but only at private or loopback addresses: works on their network only. */
+ | 'local-network'
+/** The bundle names no other machine at an address a phone can dial. */
+ | 'issuer-only';
+/** What `CadreNode.createCadreInvitation` returns: the bundle, and the same encoded for sharing. */
+export interface CreateCadreInvitationResult {
+    invitation: CadreInvitation;
+    /** `encodeCadreInvitation(invitation)`: `sereus-invite:1.` and base64url JSON, for a QR code, a paste or a link. */
+    encoded: string;
+    /** Whether a device could redeem it once the minting machine is gone; see {@link CadreInvitationReach}. */
+    reach: CadreInvitationReach;
+}
+/** How `CadreNode.redeemCadreInvitation` runs. */
+export interface RedeemCadreInvitationOptions {
+    /**
+     * Keep making passes over the bundle's addresses while every answer is retryable, until a
+     * member accepts, one refuses finally, the invitation expires, or `signal` aborts.
+     * Default false: one pass.
+     */
+    waitForMember?: boolean;
+    /** Ends the pause and the pass in flight; the call then throws the signal's reason. */
+    signal?: AbortSignal;
+    /** Called at each pass and each pause; an exception it throws is logged and ignored. */
+    onProgress?: (progress: CadreJoinProgress) => void;
+}
+/** A redemption's progress, as `RedeemCadreInvitationOptions.onProgress` reports it. */
+export type CadreJoinProgress = {
+    state: 'redeeming';
+    pass: number;
+} | {
+    state: 'waiting';
+    pass: number;
+    /** Epoch ms of the next pass. */
+    retryAtMs: number;
+    /**
+     * `'no-member-answered'`: every address failed to dial or answer. `'member-not-ready'`: at
+     * least one member answered with a retryable refusal (issuer-unknown, busy, conflict, internal).
+     */
+    reason: 'no-member-answered' | 'member-not-ready';
+    outcomes: readonly CadreInviteAddressOutcome[];
+};
+/** 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;
 }
 /**
  * Options for adding a drone via provider API.
@@ -2069,15 +2510,6 @@ export interface AddDroneOptions {
     /** Multiaddrs of the drone (returned from provider) */
     droneMultiaddrs: string[];
 }
-/**
- * Options for adding a phone via invite flow.
- */
-export interface AddPhoneOptions {
-    /** Peer ID of the phone (sent by phone when it connects) */
-    phonePeerId: string;
-    /** Invite token for validation (must match issued invite) */
-    token?: string;
-}
 /**
  * Result of preparing a seed for drone initialization.
  */
@@ -2087,12 +2519,3 @@ export interface DroneInitResult {
     /** Base64url encoded seed for transport */
     encodedSeed: string;
 }
-/**
- * Result of creating an invite for a phone.
- */
-export interface InviteResult {
-    /** The invite to share out-of-band */
-    invite: CadreInvite;
-    /** Base64url encoded invite for QR/link */
-    encodedInvite: string;
-}