@serfab/cadre-core 1.16.0 → 1.18.0

package/src/edge-node/index.ts

@@ -0,0 +1,59 @@
+/**
+ * `@serfab/cadre-core/edge-node` — build and run an edge device's cadre node the prescribed way:
+ * `createEdgeNode(platform)` over the app's key store and storage. A subpath rather than the root
+ * export, so cadre-host and the CLI never load it; the React Native kit's `createPhoneNode`
+ * (`@serfab/cadre-rn/phone-node`) is this over the secure store and rn-leveldb, and the browser
+ * and NativeScript reference apps run it over IndexedDB and SQLite.
+ */
+export {
+	createEdgeNode,
+	type EdgeJoinProgress,
+	type EdgeNode,
+	type EdgeNodeStatus,
+	type JoinCadreOptions,
+	type JoinCadreResult,
+	type UnfinishedRemoval,
+} from './edge-node.js';
+export {
+	DEFAULT_EDGE_NODE_NAMES,
+	type EdgeNodeNames,
+	type EdgeNodePlatform,
+	type EdgeNodeStorage,
+	type RemovableSlot,
+} from './platform.js';
+export {
+	isNoiseCryptoMode,
+	NOISE_CRYPTO_MODES,
+	parseSavedStart,
+	serializeSavedStart,
+	type EdgeNodeOptions,
+	type EdgeNodeOrigin,
+	type NoiseCryptoMode,
+	type SavedStart,
+} from './options.js';
+export {
+	buildEdgeNodeConfig,
+	DEFAULT_OWNER_GENESIS_TIMEOUT_MS,
+	DEFAULT_OWNER_KEY_LABEL,
+	runOwnerGenesis,
+	wireJoinedOwnerKey,
+	type EdgeNodeConfigInputs,
+	type JoinedOwnerKeyOptions,
+	type OwnerGenesisOptions,
+	type OwnerGenesisResult,
+} from './config.js';
+export { attachStrandWhenWritable, DEFAULT_STRAND_PATIENCE_MS, retryAfterRestart } from './strands.js';
+export { StrandsNeedOwnerJoinError, type PendingStrandMove, type StrandMoveOutcome } from './strand-move.js';
+export { isOwnerGrant, type JoinCredential } from './join-credential.js';
+export { type RedeemedOwnerGrant } from './owner-grant.js';
+export { FormerPartyNotEmptyError, StrandMovePendingError, type DissolveFormerPartyOptions } from './dissolve.js';
+export {
+	bootstrapPeersKvKey,
+	enrolledMachinesKvKey,
+	kvStoreSlot,
+	strandNetworkKvKey,
+	trustedOwnersKvKey,
+	type KvStoreApi,
+	type NodeLocalKv,
+} from './node-local.js';
+export { lazyRawStorage } from './lazy-raw-storage.js';

package/src/edge-node/join-credential.ts

@@ -0,0 +1,16 @@
+/**
+ * What `EdgeNode.joinCadre` takes: a machine invitation, which admits the app as a machine, or an
+ * owner grant, which makes it a machine and an owner at once (docs/architecture.md → "An app
+ * joins an existing cadre"). Both name the party; the codecs refuse each other's text by name,
+ * so an app's one join field decodes whichever was pasted.
+ */
+
+import type { CadreInvitation } from '../cadre-invite-protocol.js';
+import type { OwnerGrantBundle } from '../owner-grant-protocol.js';
+
+export type JoinCredential = CadreInvitation | OwnerGrantBundle;
+
+/** The bundle's private half tells the two apart: a grant carries `grantPrivateKey`, an invitation `invitePrivateKey`. */
+export function isOwnerGrant(credential: JoinCredential): credential is OwnerGrantBundle {
+	return 'grantPrivateKey' in credential;
+}

package/src/edge-node/lazy-raw-storage.ts

@@ -0,0 +1,178 @@
+/**
+ * `lazyRawStorage` — an `IRawStorage` over an opener that is asynchronous.
+ *
+ * `CadreNodeConfig.storage.provider`, and so `EdgeNodeStorage.rawStorage`, is a synchronous
+ * factory. rn-leveldb opens synchronously, but IndexedDB and NativeScript's SQLite open with a
+ * promise, so those platforms return this proxy: every (already asynchronous) method awaits one
+ * cached `open()` before delegating, and an async-iterator method opens only once iteration
+ * starts. Per-scope handle caching, and closing, stay the platform's: the proxy owns nothing.
+ */
+
+import type { ActionId, ActionRev, BlockId, IBlock, Transform } from '@optimystic/db-core';
+import type { BlockCommitProof, BlockMetadata, FlushOptions, IRawStorage, StoreDurability } from '@optimystic/db-p2p';
+
+/** The optional `IRawStorage` members this proxy forwards, delegating when the opened storage has them. */
+type OptionalMethodForwarded = 'getApproximateBytesUsed' | 'listBlockIds';
+/**
+ * `getStoreIdentity`: see the accepted tradeoff on {@link LazyRawStorage}. `readCached`: a marker
+ * set only by a storage with a read cache beneath it, which the proxy cannot know before opening
+ * and cadre-core's cache wrap reads before any open. `close`: the storage behind the proxy is the
+ * platform's, shared with every later proxy over the same scope, and nothing in cadre-core closes
+ * a store its provider returned.
+ */
+type OptionalMemberOmitted = 'getStoreIdentity' | 'readCached' | 'close';
+
+type OptionalKeys<T> = { [K in keyof T]-?: object extends Pick<T, K> ? K : never }[keyof T];
+type MustBeNever<T extends never> = T;
+/**
+ * Fails to compile when `IRawStorage` gains an optional member that is in neither list above, so
+ * each one is forwarded or omitted by decision rather than by default.
+ */
+export type UnclassifiedOptionalMember = MustBeNever<
+	Exclude<OptionalKeys<IRawStorage>, OptionalMethodForwarded | OptionalMemberOmitted>
+>;
+
+/**
+ * `IRawStorage`'s optional methods are detected by callers checking that the method exists, so
+ * one this proxy leaves out reads as "not supported". The `implements` clause names the optional
+ * methods the proxy forwards, so dropping one is a compile error, and `UnclassifiedOptionalMember`
+ * rejects one added upstream later. The two forwarded ones delegate when the opened storage has
+ * them and otherwise answer as an omission would (0 bytes; no block ids).
+ *
+ * NOTE: those two are always present on the proxy, a stub when the opened storage lacks them,
+ * which `IRawStorage` asks backends not to do (feature detection should see the true capability:
+ * the peer-join backfill is inert without `listBlockIds` and runs an empty scan with the stub).
+ * The proxy cannot know before opening, and every storage a platform opens behind it (IndexedDB,
+ * SQLite) has both. If a platform ever opens one without them, let it declare the capability
+ * beside `durability` and omit the method here.
+ *
+ * NOTE: accepted tradeoff — `getStoreIdentity` is omitted although the opened storage may have it.
+ * It is synchronous and must return a string fixed at construction, but the real identity exists
+ * only after the asynchronous open; the interface says a backend that cannot honour that must
+ * omit the method. `withReadCache` then identifies the store by object. Revisit if two proxies over
+ * one scope are seen getting separate read caches, or if the interface allows a lazily-resolved
+ * identity.
+ */
+class LazyRawStorage implements IRawStorage, Required<Pick<IRawStorage, OptionalMethodForwarded>> {
+	private opening: Promise<IRawStorage> | null = null;
+
+	constructor(
+		private readonly open: () => Promise<IRawStorage>,
+		readonly durability: StoreDurability,
+	) {}
+
+	/**
+	 * One open shared by every call; a rejected open is forgotten, so the next call retries while
+	 * the calls that awaited the failed one still get its rejection.
+	 *
+	 * NOTE: retries have no backoff: one fresh open attempt per operation on a permanently broken
+	 * scope. Revisit only if a failing scope is seen issuing opens in a tight loop.
+	 */
+	private storage(): Promise<IRawStorage> {
+		if (this.opening) return this.opening;
+		const opening = this.open();
+		this.opening = opening;
+		// The rejection itself reaches every caller awaiting `opening`; this only forgets it.
+		void opening.catch(() => {
+			if (this.opening === opening) this.opening = null;
+		});
+		return opening;
+	}
+
+	async getMetadata(blockId: BlockId): Promise<BlockMetadata | undefined> {
+		return (await this.storage()).getMetadata(blockId);
+	}
+
+	async saveMetadata(blockId: BlockId, metadata: BlockMetadata): Promise<void> {
+		return (await this.storage()).saveMetadata(blockId, metadata);
+	}
+
+	async getRevision(blockId: BlockId, rev: number): Promise<ActionId | undefined> {
+		return (await this.storage()).getRevision(blockId, rev);
+	}
+
+	async saveRevision(blockId: BlockId, rev: number, actionId: ActionId): Promise<void> {
+		return (await this.storage()).saveRevision(blockId, rev, actionId);
+	}
+
+	async *listRevisions(blockId: BlockId, startRev: number, endRev: number): AsyncIterable<ActionRev> {
+		const storage = await this.storage();
+		yield* storage.listRevisions(blockId, startRev, endRev);
+	}
+
+	async getPendingTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		return (await this.storage()).getPendingTransaction(blockId, actionId);
+	}
+
+	async savePendingTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		return (await this.storage()).savePendingTransaction(blockId, actionId, transform);
+	}
+
+	async deletePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		return (await this.storage()).deletePendingTransaction(blockId, actionId);
+	}
+
+	async *listPendingTransactions(blockId: BlockId): AsyncIterable<ActionId> {
+		const storage = await this.storage();
+		yield* storage.listPendingTransactions(blockId);
+	}
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		return (await this.storage()).getTransaction(blockId, actionId);
+	}
+
+	async saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		return (await this.storage()).saveTransaction(blockId, actionId, transform);
+	}
+
+	async getBlockProof(blockId: BlockId, rev: number): Promise<BlockCommitProof | undefined> {
+		return (await this.storage()).getBlockProof(blockId, rev);
+	}
+
+	async saveBlockProof(blockId: BlockId, rev: number, proof: BlockCommitProof): Promise<void> {
+		return (await this.storage()).saveBlockProof(blockId, rev, proof);
+	}
+
+	async getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined> {
+		return (await this.storage()).getMaterializedBlock(blockId, actionId);
+	}
+
+	async saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void> {
+		return (await this.storage()).saveMaterializedBlock(blockId, actionId, block);
+	}
+
+	async promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		return (await this.storage()).promotePendingTransaction(blockId, actionId);
+	}
+
+	async flush(options?: FlushOptions): Promise<void> {
+		return (await this.storage()).flush(options);
+	}
+
+	async whenDurable(): Promise<void> {
+		return (await this.storage()).whenDurable();
+	}
+
+	async getApproximateBytesUsed(): Promise<number> {
+		const storage = await this.storage();
+		return storage.getApproximateBytesUsed ? storage.getApproximateBytesUsed() : 0;
+	}
+
+	async *listBlockIds(): AsyncIterable<BlockId> {
+		const storage = await this.storage();
+		if (storage.listBlockIds) yield* storage.listBlockIds();
+	}
+}
+
+/**
+ * An `IRawStorage` whose every method awaits one cached `open()` before delegating. A rejected
+ * open is forgotten, so the next call retries; the async-iterator methods open only once
+ * iteration starts.
+ *
+ * `durability` is what the opened storage reports (`IRawStorage.durability`), stated here because
+ * it is read synchronously, before any open: a platform knows its backend (`'power-loss'` for
+ * SQLite and IndexedDB).
+ */
+export function lazyRawStorage(open: () => Promise<IRawStorage>, durability: StoreDurability): IRawStorage {
+	return new LazyRawStorage(open, durability);
+}

package/src/edge-node/node-local.ts

@@ -0,0 +1,84 @@
+/**
+ * The edge node's node-local records: the key each of cadre-core's node-local records is filed
+ * under in the platform's node-local key-value store (`EdgeNodeStorage.nodeLocal`), and the
+ * `DurableSlot` over one such key, which the persistent stores (`PersistentBootstrapPeerStore`,
+ * `PersistentEnrolledMachineStore`, `PersistentStrandNetworkStateStore`, and
+ * `PersistentTrustedOwnerStore` on a platform with no anchor slot of its own) read through.
+ *
+ * Every record key is `<record>.<partyId>`, so a party's records never collide with another's,
+ * and an app's own records in the same store stay clear of them by using a dot-free key. The
+ * party id needs no encoding: the store deals in text keys.
+ *
+ * Which records are trust-bearing, and so belong in a more tamper-resistant store where the
+ * platform has one, is `EdgeNodeStorage.trustedOwnerSlot`'s concern; the React Native kit's
+ * `@serfab/cadre-rn/node-local` carries that reasoning.
+ */
+
+import type { DurableSlot } from '../node-local-snapshot.js';
+
+/**
+ * The subset of a key-value store a slot needs. Declared here, structurally, so a platform
+ * passes its own store (`LevelDBKVStore`, `SqliteKVStore`, an IndexedDB object store) and a
+ * test an in-memory fake.
+ */
+export interface KvStoreApi {
+	/** The key's text, or `undefined` when absent. Throws on a read fault. */
+	get(key: string): Promise<string | undefined>;
+	/** Resolves once `get` on this store reads `value`; durable only after a later {@link flush}. */
+	set(key: string, value: string): Promise<void>;
+	/** Make every write that resolved before this call durable. */
+	flush(): Promise<void>;
+}
+
+/** The node-local store the edge node runs over: {@link KvStoreApi} plus deletion, for the records a removal drops. */
+export interface NodeLocalKv extends KvStoreApi {
+	/** Resolves once `get` reads the key as absent; durable only after a later {@link KvStoreApi.flush}. Idempotent. */
+	delete(key: string): Promise<void>;
+}
+
+/** Key of a party's retained cold-start dial targets (`PersistentBootstrapPeerStore`). */
+export function bootstrapPeersKvKey(partyId: string): string {
+	return `bootstrap-peers.${partyId}`;
+}
+
+/** Key of a party's last-known enrolled-machine count (`PersistentEnrolledMachineStore`). */
+export function enrolledMachinesKvKey(partyId: string): string {
+	return `enrolled-machines.${partyId}`;
+}
+
+/**
+ * Key of a party's strand network state (`PersistentStrandNetworkStateStore`): per strand, the
+ * FRET routing table its strand node saved, re-imported after a relaunch.
+ */
+export function strandNetworkKvKey(partyId: string): string {
+	return `strand-network.${partyId}`;
+}
+
+/**
+ * Key of a party's trusted-owner anchor (`PersistentTrustedOwnerStore`) on a platform that
+ * supplies no `EdgeNodeStorage.trustedOwnerSlot`: the browser and NativeScript apps. The anchor
+ * is trust-bearing, so a platform with a more tamper-resistant store than its node-local one
+ * (the phone's secure store) keeps it there instead.
+ */
+export function trustedOwnersKvKey(partyId: string): string {
+	return `trusted-owners.${partyId}`;
+}
+
+/**
+ * A {@link DurableSlot} over one key of a key-value store.
+ *
+ * A pass-through but for the flush: the store already deals in text and already reports an
+ * absent key as `undefined`, and a read fault throws out of `get`, which is exactly the
+ * "present but unreadable ⇒ throw" contract {@link DurableSlot} asks for. A `set` may resolve
+ * into the store's write group, so `save` flushes after it to be durable when it resolves, as
+ * {@link DurableSlot.save} requires.
+ */
+export function kvStoreSlot(kv: KvStoreApi, key: string): DurableSlot {
+	return {
+		load: () => kv.get(key),
+		save: async (text) => {
+			await kv.set(key, text);
+			await kv.flush();
+		},
+	};
+}

package/src/edge-node/options.ts

@@ -0,0 +1,179 @@
+/**
+ * What one edge-node start is made with, and the record that remembers it between launches.
+ *
+ * The record is one per app, not party-scoped: it is what *selects* the party, so every other
+ * node-local record is read through the `partyId` it carries. `EdgeNode.start` writes it after
+ * every successful start and `joinCadre` once a member admitted the app (`autoStart: true`),
+ * `stop` rewrites it with `autoStart: false`, and a removal from the party replaces it
+ * ({@link startAfterRemoval}); an app's launch and a push wake into a killed process read it to
+ * start the node unattended.
+ */
+
+/**
+ * How much of Noise's crypto the platform replaces (`EdgeNodePlatform.noiseCrypto`): none, the
+ * per-frame hash and cipher, or those and the handshake's key exchange too. Named here, apart from
+ * any implementation, so a stored mode can be validated without loading a native module; the
+ * React Native kit's `/noise-crypto` builds the implementation for each.
+ */
+export type NoiseCryptoMode = 'off' | 'symmetric' | 'full';
+
+export interface EdgeNodeOptions {
+	/** Party ID — identifies this cadre. The app mints one on first run. */
+	partyId: string;
+	/** Bootstrap multiaddrs (the party's always-on machines). */
+	bootstrapAddrs: string[];
+	/**
+	 * Circuit-relay multiaddrs this node reserves a slot on. An edge device accepts no inbound
+	 * connection, so a relay reservation is the only address anyone can dial it at. Empty is
+	 * allowed: the node starts and dials out, but cannot be invited to or joined.
+	 */
+	relayAddrs: string[];
+	/** How much of Noise's crypto the platform replaces; read only when the node is built. */
+	noiseCryptoMode?: NoiseCryptoMode;
+	/**
+	 * How this app came to `partyId`. A `'founded'` party runs owner genesis on every start; a
+	 * `'joined'` one never does, because genesis on a party whose control store has not arrived
+	 * would seat this app as a second founder. Absent means `'founded'`.
+	 */
+	origin?: EdgeNodeOrigin;
+	/**
+	 * The name the founding owner key gets on its `OwnerKey` row when this start founds the party
+	 * ("phone", "Ann's iPhone"). Read only by genesis; default `'phone'`. Trimmed, at most 64
+	 * characters (`OWNER_KEY_MAX_LABEL`); a longer one fails the start.
+	 */
+	ownerKeyLabel?: string;
+	/**
+	 * The party this app founded and left by joining another (`EdgeNode.joinCadre`). Its data
+	 * stays on disk under its own names, for moving its strands and dissolving the old cadre.
+	 */
+	formerPartyId?: string;
+}
+
+/** Whether this app founded its party, or joined it by invitation. */
+export type EdgeNodeOrigin = 'founded' | 'joined';
+
+/** The last start, as `EdgeNode.loadSavedStart` reports it. */
+export interface SavedStart {
+	/** Exactly what the node was last successfully started with. */
+	options: EdgeNodeOptions;
+	/** True after a successful start, false after `stop`. Gates every unattended start. */
+	autoStart: boolean;
+	/**
+	 * The `EdgeNodePlatform.dataVersion` of the build that last started over this device's data,
+	 * or `undefined` when that build named none. The app compares it with its own to decide whether
+	 * the stored data is usable.
+	 */
+	writtenBy?: string;
+}
+
+/**
+ * The saved start once an owner of its party removed this app: the party this app founded and
+ * left (`formerPartyId`), which it may go back to, not started unattended; `undefined` when it
+ * left none. No bootstrap addresses: the former party's machines are in its own bootstrap-peer
+ * store, which every start reads.
+ */
+export function startAfterRemoval(saved: SavedStart): SavedStart | undefined {
+	const { partyId, formerPartyId, relayAddrs, noiseCryptoMode } = saved.options;
+	if (formerPartyId === undefined || formerPartyId === partyId) return undefined;
+	const options: EdgeNodeOptions = { partyId: formerPartyId, bootstrapAddrs: [], relayAddrs, origin: 'founded' };
+	if (noiseCryptoMode !== undefined) options.noiseCryptoMode = noiseCryptoMode;
+	return { options, autoStart: false, ...(saved.writtenBy !== undefined && { writtenBy: saved.writtenBy }) };
+}
+
+/** Every Noise crypto mode, so a stored mode can be validated without loading the native module. */
+export const NOISE_CRYPTO_MODES: readonly NoiseCryptoMode[] = ['symmetric', 'full', 'off'];
+
+export function isNoiseCryptoMode(value: unknown): value is NoiseCryptoMode {
+	return (NOISE_CRYPTO_MODES as readonly unknown[]).includes(value);
+}
+
+const RECORD_VERSION = 1;
+
+/** The stored shape. Flat, so a record read by hand is legible. */
+interface StartRecord {
+	version: typeof RECORD_VERSION;
+	partyId: string;
+	bootstrapAddrs: string[];
+	relayAddrs: string[];
+	noiseCryptoMode?: NoiseCryptoMode;
+	origin?: EdgeNodeOrigin;
+	formerPartyId?: string;
+	ownerKeyLabel?: string;
+	autoStart: boolean;
+	writtenBy?: string;
+}
+
+export function serializeSavedStart(saved: SavedStart): string {
+	const { partyId, bootstrapAddrs, relayAddrs, noiseCryptoMode, origin, formerPartyId, ownerKeyLabel } = saved.options;
+	const record: StartRecord = {
+		version: RECORD_VERSION,
+		partyId,
+		bootstrapAddrs,
+		relayAddrs,
+		noiseCryptoMode,
+		origin,
+		formerPartyId,
+		ownerKeyLabel,
+		autoStart: saved.autoStart,
+		writtenBy: saved.writtenBy,
+	};
+	return JSON.stringify(record);
+}
+
+/**
+ * The saved record, or `undefined` when there is none or it is unusable (logged).
+ *
+ * Only the party id is worth discarding a record over. A malformed optional field falls back to
+ * its default — `[]` for an address list, the build default for the Noise mode, absent for
+ * `origin`, `formerPartyId` and `ownerKeyLabel`, `false` for `autoStart` — so a damaged record still keeps the
+ * app in its party, at worst needing the user to start the node by hand.
+ */
+export function parseSavedStart(text: string | undefined): SavedStart | undefined {
+	if (text === undefined) return undefined;
+	const record = parseRecord(text);
+	if (!record) return undefined;
+	const { partyId } = record;
+	if (typeof partyId !== 'string' || partyId.trim().length === 0) {
+		console.warn('[cadre-core/edge-node] ignoring saved start options with no party id');
+		return undefined;
+	}
+	const options: EdgeNodeOptions = {
+		partyId,
+		bootstrapAddrs: stringArrayOrEmpty(record.bootstrapAddrs),
+		relayAddrs: stringArrayOrEmpty(record.relayAddrs),
+	};
+	if (isNoiseCryptoMode(record.noiseCryptoMode)) options.noiseCryptoMode = record.noiseCryptoMode;
+	if (record.origin === 'founded' || record.origin === 'joined') options.origin = record.origin;
+	if (typeof record.formerPartyId === 'string' && record.formerPartyId.trim().length > 0) {
+		options.formerPartyId = record.formerPartyId;
+	}
+	if (typeof record.ownerKeyLabel === 'string') options.ownerKeyLabel = record.ownerKeyLabel;
+	const saved: SavedStart = { options, autoStart: record.autoStart === true };
+	if (typeof record.writtenBy === 'string') saved.writtenBy = record.writtenBy;
+	return saved;
+}
+
+/** The record's fields, or `undefined` (logged) when the text is not a record of this version. */
+function parseRecord(text: string): Record<string, unknown> | undefined {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		console.warn('[cadre-core/edge-node] ignoring saved start options that are not JSON:', err);
+		return undefined;
+	}
+	if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+		console.warn('[cadre-core/edge-node] ignoring saved start options that are not an object');
+		return undefined;
+	}
+	const record = raw as Record<string, unknown>;
+	if (record.version !== RECORD_VERSION) {
+		console.warn(`[cadre-core/edge-node] ignoring saved start options of unknown version ${String(record.version)}`);
+		return undefined;
+	}
+	return record;
+}
+
+function stringArrayOrEmpty(value: unknown): string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? value : [];
+}

package/src/edge-node/owner-grant.ts

@@ -0,0 +1,63 @@
+/**
+ * `EdgeNode.redeemOwnerGrant`'s sequence: make the app an owner of the party it runs in with
+ * owner-grant text, seating the owner slot's key (docs/architecture.md → "Owner grants"). Runs
+ * over a narrow view of the runtime ({@link OwnerGrantRuntime}), inside one of its transitions,
+ * as the join does.
+ */
+
+import type { CadreNode } from '../cadre-node.js';
+import { decodeOwnerGrant, OwnerGrantRejectedError } from '../owner-grant-protocol.js';
+import type { OwnerSigner } from '../owner-signer.js';
+import type { OwnerGenesisResult } from './config.js';
+
+/** The part of the edge-node runtime a redemption drives; the join's view has the same two calls. */
+export interface OwnerGrantRuntime {
+	/** The owner slot's key, created when the slot is empty: the key an owner grant seats. */
+	ownerSlotSigner(): Promise<OwnerSigner>;
+	/** `granted`: an owner grant has just seated the slot's key, so wait for the row. */
+	wireJoinedOwner(node: CadreNode, granted: boolean): Promise<OwnerGenesisResult>;
+}
+
+/** What {@link redeemOwnerGrantText} settled. */
+export interface RedeemedOwnerGrant {
+	/** The owner slot's key: the one the grant seated, or found already an owner. */
+	ownerKey: string;
+	/** The key was already a live owner of the party: nothing was signed or written, and the grant spent no use. */
+	alreadyOwner: boolean;
+	/**
+	 * The key is wired as the node's owner signer. False when its row has not reached this node
+	 * within the owner-step bound (a redemption at another member); a later start wires it.
+	 */
+	wired: boolean;
+}
+
+/**
+ * Decode `text`, refuse a grant for another party, answer a slot key that is already an owner
+ * here, else redeem the grant for the slot's key (`CadreNode.redeemOwnerGrant`) and wire it.
+ *
+ * The already-owner answer comes first because the redemption's local path refuses `alone`
+ * before it asks whether the key is an owner, and a device that is one should hear so whether
+ * or not it is connected.
+ *
+ * @throws the decoder's error for text that is not an owner grant; `OwnerGrantRejectedError`
+ *   `party-mismatch` for a grant of another party, the code a member serving another cadre answers;
+ *   and what `CadreNode.redeemOwnerGrant` throws.
+ */
+export async function redeemOwnerGrantText(runtime: OwnerGrantRuntime, node: CadreNode, text: string): Promise<RedeemedOwnerGrant> {
+	const bundle = decodeOwnerGrant(text);
+	if (bundle.partyId !== node.partyId) {
+		throw new OwnerGrantRejectedError('party-mismatch', `This grant is for cadre ${bundle.partyId}, not the one this app runs in`);
+	}
+	// NOTE: a key created here stays in the slot when the redemption then fails, as a failed grant
+	// join's does (`edge-join.ts`), so a later import of a different exported key is refused as
+	// slot-occupied until a grant seats this one. If users meet that, delete a key this call created
+	// when the refusal is one that wrote nothing (every refusal but an unreachable member or an
+	// unverifiable reply, after either of which the row may exist).
+	const signer = await runtime.ownerSlotSigner();
+	if (await node.wireOwnKeyIfOwner(signer)) {
+		return { ownerKey: signer.publicKey, alreadyOwner: true, wired: true };
+	}
+	const { alreadyOwner } = await node.redeemOwnerGrant(bundle, signer);
+	const wired = (await runtime.wireJoinedOwner(node, true)) === 'enrolled';
+	return { ownerKey: signer.publicKey, alreadyOwner, wired };
+}