@serfab/cadre-core 1.15.0 → 1.17.0

package/src/edge-node/platform.ts

@@ -0,0 +1,151 @@
+/**
+ * What an app supplies to run the edge node (`createEdgeNode`): its key store, its storage, and
+ * the platform choices (transports, listen addresses, Noise crypto) that cadre-core cannot make
+ * for it. Fixed for the app's lifetime.
+ */
+
+import type { IRawStorage, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
+import type { KeyStore } from '../key-store.js';
+import type { DurableSlot } from '../node-local-snapshot.js';
+import type { CadreNodeConfig } from '../types.js';
+import type { NodeLocalKv } from './node-local.js';
+import type { NoiseCryptoMode } from './options.js';
+
+export interface EdgeNodePlatform {
+	/**
+	 * Everything secret: the identity (`DEFAULT_IDENTITY_KEY_ID`), the owner key in its own slot
+	 * (`DEFAULT_OWNER_KEY_ID`), the joined-strand records (`KeyStoreJoinedStrandStore`) and the
+	 * strand-move records. The phone's is the platform secure store; a browser's or a desktop
+	 * app's may be a plaintext database, which is then where its identity already lives.
+	 */
+	keyStore: KeyStore;
+	storage: EdgeNodeStorage;
+	/**
+	 * libp2p transports, given the relays the node reserves on. Default: WebSockets and circuit
+	 * relay. An app with WebRTC adds `webRTC({ rtcConfiguration: { iceServers } })`, `iceServers`
+	 * from `resolveStunServers(relayAddrs)`.
+	 */
+	transports?: (relayAddrs: readonly string[]) => Libp2pTransports;
+	/**
+	 * Listen addresses besides the bare `/p2p-circuit` entry cadre-core adds for a named relay
+	 * (`relay-addrs.ts` → `resolveListenAddrs`). Default `[]`: an edge device cannot accept a
+	 * connection, so the only address it has is the one a relay reservation earns it. A browser
+	 * tab returns `['/webrtc']` when it has relays, so a relayed connection can upgrade to a direct
+	 * one.
+	 */
+	listenAddrs?: (relayAddrs: readonly string[]) => string[];
+	/**
+	 * Noise crypto built outside libp2p-noise: `build` returns the implementation for a mode,
+	 * `defaultMode` the mode used when the start options name none. Absent: libp2p-noise's own
+	 * crypto, pure JavaScript on a phone (the React Native kit's `/noise-crypto` is the native one).
+	 */
+	noiseCrypto?: {
+		build: (mode: NoiseCryptoMode) => NoiseCryptoInterface | undefined;
+		defaultMode: NoiseCryptoMode;
+	};
+	/**
+	 * The keys inside the node-local store. Each is a persistence contract: renaming one orphans
+	 * every installed app's records. The defaults are the reference apps'; an app that names its
+	 * own should pin them in a test.
+	 */
+	names?: Partial<EdgeNodeNames>;
+	/**
+	 * Dial loopback, private and plain `ws://` addresses. Default `true`: see the
+	 * `connectionGater` comment in `buildEdgeNodeConfig`.
+	 */
+	allowPrivateDial?: boolean;
+	/** Bound on owner genesis; default 60 s. See `runOwnerGenesis`. */
+	ownerGenesisTimeoutMs?: number;
+	/**
+	 * A version naming the format of the data this build writes, for example the stack version it
+	 * was built against. Saved with each successful start and reported by `loadSavedStart` as
+	 * `writtenBy`, so a later build can tell data it cannot use from data it can.
+	 */
+	dataVersion?: string;
+	/**
+	 * The last word on the config the edge node built: strand filter, schema-signing policy,
+	 * hibernation, `linkRoundTripMs`, or anything the parameters above do not cover.
+	 */
+	configure?: (config: CadreNodeConfig) => CadreNodeConfig;
+}
+
+/** The keys inside the node-local store (`EdgeNodeStorage.nodeLocal`) that are the edge node's. */
+export interface EdgeNodeNames {
+	/**
+	 * Key of the saved-start record. One per app, not per party: it is what names the party every
+	 * other record is filed under. Dot-free, so it cannot collide with the `<record>.<partyId>`
+	 * keys of `node-local.ts`.
+	 */
+	savedStartKey: string;
+	/**
+	 * Key of the record naming a party whose dissolve has begun. Dot-free and one per app, as
+	 * {@link EdgeNodeNames.savedStartKey} is.
+	 */
+	dissolveMarkerKey: string;
+	/**
+	 * Key of the join request this app opened as a link to another app (`LinkRequestStore` in
+	 * `@serfab/cadre-rn/app-link`). Dot-free and one per app, as {@link EdgeNodeNames.savedStartKey} is.
+	 */
+	linkRequestKey: string;
+	/**
+	 * Key of the apps the user allowed to join before they asked (`AppRecommendationStore` in
+	 * `@serfab/cadre-rn/app-link`). Dot-free and one per app, as {@link EdgeNodeNames.savedStartKey}
+	 * is; each entry names its party.
+	 */
+	recommendationsKey: string;
+}
+
+export const DEFAULT_EDGE_NODE_NAMES: EdgeNodeNames = {
+	savedStartKey: 'start-options',
+	dissolveMarkerKey: 'dissolving-party',
+	linkRequestKey: 'link-join-request',
+	recommendationsKey: 'recommended-apps',
+};
+
+/**
+ * The app's storage, as the edge node opens, closes and deletes it: one raw block store per
+ * cadre-core storage scope, and one node-local key-value store beside them. The platform owns
+ * every handle; the edge node only says when it is done with them (`close`).
+ */
+export interface EdgeNodeStorage {
+	/**
+	 * Names the storage. `createEdgeNode` refuses a second starting, joining or running edge node
+	 * over the same id in one process, and replaces a stopped one: two over the same storage
+	 * would share databases and an identity.
+	 */
+	readonly id: string;
+	/**
+	 * One storage scope's raw block storage: `controlStorageScope(partyId)` for the control
+	 * network, the strand id for each strand. The key is already safe as a database-name segment;
+	 * use it verbatim, do not parse it. Synchronous, as `CadreNodeConfig.storage.provider` is; a
+	 * platform whose opener is async returns `lazyRawStorage(...)`. The same handle for the same
+	 * scope until {@link close}: cadre-core asks once per scope per runtime, and again after a
+	 * strand stops.
+	 */
+	rawStorage(scope: string): IRawStorage;
+	/** Delete a scope's storage. No handle on it may be open. Resolves when it is gone or was absent. */
+	destroyScope(scope: string): Promise<void>;
+	/**
+	 * The node-local key-value store, holding the saved start, the dissolve marker, the app-link
+	 * records and the per-party records of `node-local.ts`. Usable with no node running: reopens
+	 * after {@link close}.
+	 */
+	nodeLocal(): NodeLocalKv;
+	/**
+	 * Flush and close the node-local store, then close every handle {@link rawStorage} opened. A
+	 * failure closing one is logged and the rest still close; the call does not reject.
+	 */
+	close(): Promise<void>;
+	/**
+	 * Per-party slot for the trusted-owner anchor (`PersistentTrustedOwnerStore`). Absent: the
+	 * node-local key `trustedOwnersKvKey(partyId)`. The anchor is not secret but it is
+	 * trust-bearing, so the phone puts it in its secure store, beside the identity it qualifies.
+	 */
+	trustedOwnerSlot?(partyId: string): RemovableSlot;
+}
+
+/** A {@link DurableSlot} a removal can delete: the trusted-owner anchor of a party being removed. */
+export interface RemovableSlot extends DurableSlot {
+	/** Delete the slot's record, durably. Resolves when it is gone or was absent. */
+	remove(): Promise<void>;
+}

package/src/edge-node/strand-move.ts

@@ -0,0 +1,270 @@
+/**
+ * Carrying the strands of the party this app founded into the party it joins
+ * (docs/architecture.md → "An app joins an existing cadre" → "Moving the app's strands").
+ *
+ * The app runs one node, so cadre-core's two ends of a move run on two nodes, one after the
+ * other: `exportStrandBundle` on the left party's node before the switch, `adoptStrandBundle` on
+ * the joined party's node once the app's key is wired as an owner there. Between them the bundle
+ * is kept here, one record per left party, so a join killed partway, or an owner key wired only
+ * on a later launch, finishes the move on a later start. The bundle carries read secrets, party
+ * keys and bearer invitations, so the record lives in the key store beside the identity.
+ */
+
+import { adoptStrandBundle, StrandMoveNotOwnerError } from '../strand-move.js';
+import type { StrandBundle, StrandMoveReport } from '../strand-move.js';
+import type { CadreNode } from '../cadre-node.js';
+import type { KeyId, KeyStore } from '../key-store.js';
+import { isOwnerGrant, type JoinCredential } from './join-credential.js';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+
+/** How a join's strand move settled: `JoinCadreResult.strandMove`. */
+export type StrandMoveOutcome =
+	/** Adopted. `partial`: `report.failed` lists what the next start, or `finishStrandMove`, retries. */
+	| { state: 'done' | 'partial'; report: StrandMoveReport }
+	/** Not adopted yet: the app's key is not wired as an owner of the joined party. A start after it is adopts. */
+	| { state: 'deferred'; reason: 'owner-key-not-wired' }
+	/** Not adopted yet: the adoption threw (logged). The next start, or `finishStrandMove`, retries. */
+	| { state: 'deferred'; reason: 'adoption-failed'; error: Error };
+
+/** A move still waiting: `EdgeNode.pendingStrandMove`. */
+export interface PendingStrandMove {
+	fromPartyId: string;
+	/** The party the strands move into; the record is adopted there and nowhere else. */
+	toPartyId: string;
+	/** Strands of `fromPartyId` not seated in `toPartyId` yet. */
+	strandIds: string[];
+	/** Strands `toPartyId` refused permanently so far: it participates in them under its own identity. */
+	refused: StrandMoveReport['refused'];
+}
+
+/**
+ * `EdgeNode.joinCadre` refused before anything stopped: the party this app founded holds strands,
+ * pending joins or invitations, and a machine invitation does not make the app an owner of the
+ * party it joins. Every row a move seats there is owner-signed, so a member's join would leave
+ * them in a party the app no longer runs. Joining with an owner grant moves them.
+ */
+export class StrandsNeedOwnerJoinError extends Error {
+	readonly fromPartyId: string;
+	readonly toPartyId: string;
+	readonly strandCount: number;
+
+	constructor(bundle: StrandBundle, toPartyId: string) {
+		super(
+			`Cannot join party ${toPartyId} as a member: ${describeContent(bundle)} of party ${bundle.partyId} ` +
+			'would be left behind, and only an owner can move them. Join with an owner grant instead, made under the owner app\'s Owner keys.',
+		);
+		this.name = 'StrandsNeedOwnerJoinError';
+		this.fromPartyId = bundle.partyId;
+		this.toPartyId = toPartyId;
+		this.strandCount = bundle.strands.length;
+	}
+}
+
+/** What the key store holds for one left party between the export and a complete adoption. */
+interface StrandMoveRecord {
+	v: typeof RECORD_VERSION;
+	targetPartyId: string;
+	bundle: StrandBundle;
+	/** Strand ids an earlier adoption seated. Never left out of a retry: an invitation bound to one needs it under `moved`. */
+	moved: string[];
+	/** Permanent refusals from earlier adoptions, left out of a retry and reported each time. */
+	refused: StrandMoveReport['refused'];
+}
+
+const RECORD_VERSION = 1;
+
+/** Key-store id prefix of every move record; the left party's id follows, base64url. */
+const SLOT_PREFIX = 'cadre/strand-move/';
+
+/**
+ * A persistence contract: `cadre/strand-move/<base64url of the party id's UTF-8 bytes>`, the
+ * id the React Native kit wrote before the records moved here (its `secureStoreKeySegment`
+ * encodes the same way), so an installed phone's record is read back.
+ */
+function slotId(fromPartyId: string): KeyId {
+	return SLOT_PREFIX + uint8ArrayToString(uint8ArrayFromString(fromPartyId, 'utf8'), 'base64url');
+}
+
+/** The move records, one key-store slot per left party. A read the key store refuses throws; it is never read as "no record". */
+export class StrandMoveRecords {
+	constructor(private readonly keyStore: KeyStore) {}
+
+	/**
+	 * Replaces the left party's record: a newer export is the fuller one.
+	 *
+	 * NOTE: on a phone, a bundle with a routing table per strand runs past expo-secure-store's
+	 * 2048-byte value guideline; version 14 warns and stores it, and the iOS Keychain and Android's
+	 * encrypted preferences hold more. If a later SDK throws instead, keep the routing tables
+	 * (not secret) in the node-local store and only the secrets here.
+	 */
+	save(record: StrandMoveRecord): Promise<void> {
+		return this.keyStore.set(slotId(record.bundle.partyId), uint8ArrayFromString(JSON.stringify(record), 'utf8'));
+	}
+
+	load(fromPartyId: string): Promise<StrandMoveRecord | undefined> {
+		return this.read(slotId(fromPartyId));
+	}
+
+	remove(fromPartyId: string): Promise<void> {
+		return this.keyStore.delete(slotId(fromPartyId));
+	}
+
+	/** Every record naming `toPartyId`, in slot order. */
+	async naming(toPartyId: string): Promise<StrandMoveRecord[]> {
+		const slots = (await this.keyStore.list()).filter((slot) => slot.startsWith(SLOT_PREFIX)).sort();
+		const records: StrandMoveRecord[] = [];
+		for (const slot of slots) {
+			const record = await this.read(slot);
+			if (record?.targetPartyId === toPartyId) records.push(record);
+		}
+		return records;
+	}
+
+	/**
+	 * The record in `slot`. One that does not parse is deleted with a warning: nothing can adopt
+	 * it, and the strands are still in the left party's storage. Its absence then reads as
+	 * "nothing waiting", so code that deletes that storage must not take a missing record alone
+	 * as proof that every strand reached the joined party.
+	 */
+	private async read(slot: KeyId): Promise<StrandMoveRecord | undefined> {
+		const bytes = await this.keyStore.get(slot);
+		if (bytes === undefined) return undefined;
+		const record = parseRecord(uint8ArrayToString(bytes, 'utf8'));
+		if (record !== undefined && slotId(record.bundle.partyId) === slot) return record;
+		console.warn(`[cadre-core/edge-node] deleting the strand move record in ${slot}: it is not one this kit wrote`);
+		try {
+			await this.keyStore.delete(slot);
+		} catch (err) {
+			// Read as absent either way; failing every start over a record nothing can use would be worse.
+			console.warn(`[cadre-core/edge-node] could not delete the strand move record in ${slot}:`, err);
+		}
+		return undefined;
+	}
+}
+
+/**
+ * The record a join writes before the switch, or `undefined` when the bundle holds nothing to
+ * move. Throws {@link StrandsNeedOwnerJoinError} when it does and `credential` is a machine
+ * invitation, which does not make the app an owner of the party it joins.
+ */
+export function joinMoveRecord(bundle: StrandBundle, credential: JoinCredential): StrandMoveRecord | undefined {
+	if (bundle.strands.length + bundle.pendingJoins.length + bundle.formationInvites.length === 0) return undefined;
+	if (!isOwnerGrant(credential)) throw new StrandsNeedOwnerJoinError(bundle, credential.partyId);
+	return { v: RECORD_VERSION, targetPartyId: credential.partyId, bundle, moved: [], refused: [] };
+}
+
+/**
+ * Adopt `record` on `node`, running in the record's target party, without the strands an earlier
+ * attempt had refused; then delete the record when nothing failed, or save this attempt's
+ * progress. The report lists every refusal so far. Throws what `adoptStrandBundle` throws. A
+ * failure updating the record is only logged: the record left behind is adopted again, without
+ * harm, by the next start.
+ */
+export async function adoptMoveRecord(node: CadreNode, records: StrandMoveRecords, record: StrandMoveRecord): Promise<StrandMoveReport> {
+	const refused = new Set(record.refused.map((entry) => entry.strandId));
+	const strands = record.bundle.strands.filter((entry) => !refused.has(entry.row.Id));
+	const adopted = await adoptStrandBundle(node, { ...record.bundle, strands });
+	const report: StrandMoveReport = { ...adopted, refused: [...record.refused, ...adopted.refused] };
+	await keepWhatIsLeft(records, record, report);
+	return report;
+}
+
+async function keepWhatIsLeft(records: StrandMoveRecords, record: StrandMoveRecord, report: StrandMoveReport): Promise<void> {
+	const fromPartyId = record.bundle.partyId;
+	try {
+		if (report.failed.length === 0) {
+			await records.remove(fromPartyId);
+		} else {
+			const moved = [...new Set([...record.moved, ...report.moved])];
+			await records.save({ ...record, moved, refused: report.refused });
+		}
+	} catch (err) {
+		console.warn(`[cadre-core/edge-node] could not update the strand move record of party ${fromPartyId}; the next start adopts it again:`, err);
+	}
+}
+
+/**
+ * Adopt every record naming the node's party, by left party. A record the key store refuses to
+ * read throws; an adoption that throws is logged and reported as deferred, and its record kept.
+ */
+export async function adoptMovesInto(node: CadreNode, records: StrandMoveRecords): Promise<Map<string, StrandMoveOutcome>> {
+	const outcomes = new Map<string, StrandMoveOutcome>();
+	for (const record of await records.naming(node.partyId)) {
+		outcomes.set(record.bundle.partyId, await adoptOrDefer(node, records, record));
+	}
+	return outcomes;
+}
+
+async function adoptOrDefer(node: CadreNode, records: StrandMoveRecords, record: StrandMoveRecord): Promise<StrandMoveOutcome> {
+	try {
+		const report = await adoptMoveRecord(node, records, record);
+		return { state: report.failed.length === 0 ? 'done' : 'partial', report };
+	} catch (err) {
+		console.warn(`[cadre-core/edge-node] moving the strands of party ${record.bundle.partyId} failed; the next start retries:`, err);
+		return deferredOutcome(err);
+	}
+}
+
+export function deferredOutcome(err: unknown): StrandMoveOutcome {
+	if (err instanceof StrandMoveNotOwnerError) return { state: 'deferred', reason: 'owner-key-not-wired' };
+	return { state: 'deferred', reason: 'adoption-failed', error: toError(err) };
+}
+
+/** A thrown value as an `Error`, for a status or outcome that carries one. */
+export function toError(err: unknown): Error {
+	return err instanceof Error ? err : new Error(String(err));
+}
+
+export function pendingMove(record: StrandMoveRecord): PendingStrandMove {
+	const settled = new Set([...record.moved, ...record.refused.map((entry) => entry.strandId)]);
+	return {
+		fromPartyId: record.bundle.partyId,
+		toPartyId: record.targetPartyId,
+		strandIds: record.bundle.strands.map((entry) => entry.row.Id).filter((strandId) => !settled.has(strandId)),
+		refused: record.refused,
+	};
+}
+
+/** The record in `text`, or `undefined` (logged) when it is not one. */
+function parseRecord(text: string): StrandMoveRecord | undefined {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		console.warn('[cadre-core/edge-node] a strand move record is not JSON:', err);
+		return undefined;
+	}
+	return isRecord(raw) ? raw : undefined;
+}
+
+/** The record's shape down to the bundle's lists; their entries are cadre-core's export, written by this module. */
+function isRecord(value: unknown): value is StrandMoveRecord {
+	if (!isObject(value) || value.v !== RECORD_VERSION || typeof value.targetPartyId !== 'string') return false;
+	if (!Array.isArray(value.moved) || !Array.isArray(value.refused)) return false;
+	const bundle = value.bundle;
+	return isObject(bundle)
+		&& bundle.v === 1
+		&& typeof bundle.partyId === 'string'
+		&& Array.isArray(bundle.strands)
+		&& Array.isArray(bundle.pendingJoins)
+		&& Array.isArray(bundle.formationInvites);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** "2 strands and 1 invitation": the bundle's non-empty lists. */
+function describeContent(bundle: StrandBundle): string {
+	const parts = [
+		count(bundle.strands.length, 'strand'),
+		count(bundle.pendingJoins.length, 'pending join'),
+		count(bundle.formationInvites.length, 'invitation'),
+	].filter((part): part is string => part !== null);
+	return parts.length > 1 ? `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}` : parts.join('');
+}
+
+function count(n: number, noun: string): string | null {
+	if (n === 0) return null;
+	return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}

package/src/edge-node/strands.ts

@@ -0,0 +1,72 @@
+/**
+ * Strand helpers every edge app needs around a running node, from sereus-chat's bring-up.
+ */
+
+import { StrandAwaitingFirstSyncError } from '../strand-first-sync-gate.js';
+import type { CadreNode } from '../cadre-node.js';
+import type { StrandConfig, StrandInstance } from '../types.js';
+
+/** Default patience for {@link attachStrandWhenWritable}: generous enough that running out means something is wrong. */
+export const DEFAULT_STRAND_PATIENCE_MS = 240_000;
+
+/**
+ * `addStrand`, then keep waiting when the first sync outlasts its budget.
+ *
+ * `addStrand` rejects with `StrandAwaitingFirstSyncError` when the first sync has not finished,
+ * and leaves the strand launched and syncing: the timeout is a progress report, not an outcome.
+ * Measured on a link with a 1.8 s round trip, a first sync completed at about 150 s against a
+ * 120 s budget. So this waits for the strand to become writable, and rejects only when it has not
+ * within `patienceMs`.
+ */
+export async function attachStrandWhenWritable(
+	node: CadreNode,
+	config: StrandConfig,
+	options: { patienceMs?: number } = {},
+): Promise<StrandInstance> {
+	try {
+		return await node.addStrand(config);
+	} catch (err) {
+		if (!(err instanceof StrandAwaitingFirstSyncError)) throw err;
+		const patienceMs = options.patienceMs ?? DEFAULT_STRAND_PATIENCE_MS;
+		console.info(
+			`[cadre-core/edge-node] first sync of ${config.strandRow.Id} still arriving; ` +
+			`waiting up to ${patienceMs / 1000} s for it to become writable`,
+		);
+		return await node.whenStrandWritable(config.strandRow.Id, { timeoutMs: patienceMs });
+	}
+}
+
+/**
+ * Optimystic's cluster coordinator reports a write that could not gather enough approvals this
+ * way. It is transient right after a node restarts alone: its cohort has not reconnected yet.
+ *
+ * NOTE: matched on the message because Optimystic throws a plain `Error` here. If it gains a typed
+ * error, match on that instead — a reworded message would silently stop the retries.
+ */
+const SUPER_MAJORITY_FAILURE = /Failed to get super-majority/i;
+
+/**
+ * Run a write, retrying only on the transient super-majority failure the first writes after a lone
+ * restart hit (v1.9 release notes): `attempts` tries, `delayMs` apart. Any other error, and the
+ * last attempt's, propagates.
+ */
+export async function retryAfterRestart<T>(
+	write: () => Promise<T>,
+	options: { attempts?: number; delayMs?: number } = {},
+): Promise<T> {
+	const attempts = options.attempts ?? 5;
+	const delayMs = options.delayMs ?? 3_000;
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return await write();
+		} catch (err) {
+			if (!isTransientWriteFailure(err) || attempt >= attempts) throw err;
+			console.info(`[cadre-core/edge-node] write attempt ${attempt} lacked a super-majority; retrying in ${delayMs} ms`);
+			await new Promise((resolve) => setTimeout(resolve, delayMs));
+		}
+	}
+}
+
+function isTransientWriteFailure(err: unknown): boolean {
+	return SUPER_MAJORITY_FAILURE.test(err instanceof Error ? err.message : String(err));
+}

package/src/index.ts

@@ -5,14 +5,23 @@ export * from './types.js';
 export { canonicalJson } from './canonical-json.js';
 
 // Main CadreNode class
-export { CadreNode, OWNER_INVITATION_DEFAULT_TTL_MS, CADRE_INVITATION_DEFAULT_TTL_MS } from './cadre-node.js';
+export { CadreNode, CADRE_INVITATION_DEFAULT_TTL_MS, OWNER_GRANT_DEFAULT_TTL_MS } from './cadre-node.js';
 
 // Removing a machine from a cadre: the by-name refusal `CadreNode.removeMachine` throws
 // (the listing, plan and result types are in types.ts)
 export { MachineRemovalRefusedError } from './machine-removal.js';
 
+// Adding and removing an owner key: the by-name refusals `CadreNode.addOwner` and
+// `CadreNode.removeOwner` throw (the listing, plan and result types are in types.ts)
+export { OwnerKeyAddRefusedError, OwnerKeyRemovalRefusedError } from './owner-keys.js';
+
 // Control database
-export { ControlDatabase, parseNullableStoredDatetimeMs, MissingHostStrandError, InvitationExhaustedError, CadreInviteIssuerUnknownError, buildAuthorizationMessage, registerPartyIdFunction, formationVouchMessage, formationConsentMessage, cadreInviteAddMessage, cadreInviteRedeemMessage, cadreInviteConsentMessage, projectSeedPeers, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type FormationInviteRow, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef, type MachineRemovalWrites } from './control-database.js';
+export { ControlDatabase, parseNullableStoredDatetimeMs, MissingHostStrandError, InvitationExhaustedError, CadreInviteIssuerUnknownError, OwnerGrantIssuerUnknownError, IssuedRowNotHereYetError, buildAuthorizationMessage, registerPartyIdFunction, formationVouchMessage, formationConsentMessage, cadreInviteAddMessage, cadreInviteRedeemMessage, cadreInviteConsentMessage, ownerGrantAddMessage, ownerGrantRedeemMessage, ownerGrantConsentMessage, projectSeedPeers, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type FormationInviteRow, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef, type ControlSign, type OwnerGrantRedemptionFields } from './control-database.js';
+
+// What `start()` throws when the control store was written with a control schema this build
+// cannot apply to it (recreate procedure: docs/architecture.md)
+export { CONTROL_SCHEMA_VERSION, CONTROL_SCHEMA_BASELINE_VERSION } from './control-schema.js';
+export { ControlStoreIncompatibleError } from './control-schema-version.js';
 
 // Bounded retry for transient control-write failures (classifier + loop behind
 // ControlDatabase.lockedWithRetry; exported so the integration package can drive the
@@ -49,10 +58,10 @@ export type {
 } from './control-retry.js';
 
 // Control-plane authorization field vector (the domain/action tagging every signer shares)
-export { controlAuthorizationFields, unboundAuthorizationFields, cadreInviteRowFields, type ControlDomain, type BoundControlDomain, type UnboundControlDomain, type ControlAction, type CadreInviteSignedFields } from './control-authorization.js';
+export { controlAuthorizationFields, unboundAuthorizationFields, cadreInviteRowFields, ownerGrantRowFields, type ControlDomain, type BoundControlDomain, type UnboundControlDomain, type ControlAction, type CadreInviteSignedFields, type OwnerGrantSignedFields } from './control-authorization.js';
 
 // Ed25519 key bridge (libp2p Ed25519 -> base64url keypair)
-export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, ed25519PublicKeyB64FromPeerId, requireEd25519PublicKeyB64, type Ed25519KeyPair } from './ed25519-key.js';
+export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, ed25519PublicKeyB64FromPeerId, requireEd25519PublicKeyB64, requireEd25519PrivateKeyB64, type Ed25519KeyPair } from './ed25519-key.js';
 
 // Pluggable key store (backend-agnostic identity/owner key material seam).
 // Dependency-free: the interface, error, default slot id, and in-memory backend
@@ -63,6 +72,7 @@ export {
   InMemoryKeyStore,
   KeyStoreAccessError,
   DEFAULT_IDENTITY_KEY_ID,
+  DEFAULT_OWNER_KEY_ID,
   type KeyStore,
   type KeyId
 } from './key-store.js';
@@ -75,6 +85,44 @@ export { encodeFileSafeComponent } from './file-safe-name.js';
 // node key BEFORE `CadreNode` exists.
 export { loadOrCreateIdentityKey } from './identity-key.js';
 
+// Owner keys (`docs/architecture.md` → Owner Keys): the one interface owner signatures go
+// through, the key-store slot an owner key lives in apart from the identity slot, and the
+// text form a key is exported and imported in. Cross-platform: pure JS crypto only.
+export {
+  softwareOwnerSigner,
+  OwnerSigningDeclinedError,
+  type OwnerSigner,
+  type OwnerSign,
+  type OwnerSigningRequest
+} from './owner-signer.js';
+export {
+  createOwnerKey,
+  loadOwnerSigner,
+  importOwnerKey,
+  readOwnerPrivateKey,
+  OwnerKeySlotOccupiedError
+} from './owner-key-store.js';
+export {
+  encodeOwnerKeyExport,
+  decodeOwnerKeyExport,
+  unlockOwnerKeyExport,
+  OwnerKeyExportError,
+  OWNER_KEY_EXPORT_PREFIX,
+  LOCKED_OWNER_KEY_EXPORT_PREFIX,
+  OWNER_KEY_MAX_LABEL,
+  type OwnerKeyExportErrorCode,
+  type OwnerKeyExportContents,
+  type OwnerKeyExportInput,
+  type DecodedOwnerKeyExport
+} from './owner-key-export.js';
+export {
+  exportOwnerKey,
+  importOwnerKeyInto,
+  type ExportedOwnerKey,
+  type ImportedOwnerKey,
+  type OwnerKeyExportOptions
+} from './owner-key-flows.js';
+
 // Node-local trusted-owner anchor: the NON-replicated, per-party record of
 // out-of-band-established owner keys (the trust anchor the replicated OwnerKey
 // table cannot be). Cross-platform: interface + in-memory store only — the
@@ -395,9 +443,14 @@ export {
   verifyRevocationSigner,
   verifyFormationConsent,
   verifyInvitationAdmission,
-  verifyInvitationOwnerAdmission,
   verifyCadreInviteRow,
   verifyCadreInviteRedemption,
+  ownerGrantAddDigest,
+  ownerGrantRedeemDigest,
+  ownerGrantConsentDigest,
+  verifyOwnerGrantRow,
+  verifyOwnerGrantRedemption,
+  verifyOwnerGrantAdmission,
   type DeviceTokenAuthorizedRow
 } from './peer-authorization.js';
 
@@ -599,6 +652,8 @@ export {
   requireCadreJoinReply,
   CADRE_JOIN_REQUEST_PREFIX,
   CADRE_INVITATION_PREFIX,
+  OWNER_KEY_EXPORT_STEM,
+  OWNER_GRANT_PREFIX,
   CADRE_JOIN_REQUEST_MAX_APP_NAME,
   type CadreJoinReply,
   type CadreJoinRequest
@@ -683,6 +738,48 @@ export {
   type RedeemSigner,
   type CadreInviteRedemption
 } from './cadre-invite-protocol.js';
+// Owner grant redemption transport: the bundle an owner hands out, the wire messages, the
+// member-side handler and the holder-side dialer, and how a redemption fails
+export {
+  OwnerGrantHandler,
+  redeemOwnerGrantAtMembers,
+  redeemOwnerGrantInPasses,
+  signOwnerGrantRequest,
+  verifyOwnerGrantReply,
+  encodeOwnerGrant,
+  decodeOwnerGrant,
+  isWellFormedOwnerGrantRow,
+  OwnerGrantRejectedError,
+  OwnerGrantUnreachableError,
+  OwnerGrantReplyInvalidError,
+  OWNER_GRANT_PROTOCOL,
+  OWNER_GRANT_REJECTION_RETRYABLE,
+  isOwnerGrantRejectionCode,
+  type OwnerGrantBundle,
+  type OwnerGrantRedeemRequest,
+  type OwnerGrantRedeemReply,
+  type OwnerGrantAccepted,
+  type OwnerGrantRejectionCode,
+  type OwnerGrantHandlerOptions,
+  type OwnerGrantStore,
+  type RedeemOwnerGrantAtMembersOptions,
+  type RedeemOwnerGrantInPassesOptions,
+  type OwnerGrantRedemption
+} from './owner-grant-protocol.js';
+// The exchange shape both redemption protocols are built on
+export {
+  MemberRedemptionHandler,
+  dialRedemption,
+  dialRedemptionInPasses,
+  MAX_REDEMPTION_FRAME_BYTES,
+  type MemberRedemptionHandlerOptions,
+  type MemberRedemptionOptions,
+  type MemberRedemptionPassOptions,
+  type MemberRedemption,
+  type RedemptionAddressOutcome,
+  type RedemptionRejection,
+  type RedemptionRefusalFrame
+} from './member-redemption.js';
 // Which machines, and how many addresses of each, an invitation names; how far a cadre invitation reaches
 export {
   selectCadreInvitationMembers,