@serfab/cadre-core 1.16.0 → 1.18.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/enrolled-machine-store.ts

@@ -172,9 +172,9 @@ export class PersistentEnrolledMachineStore implements EnrolledMachineStore {
 	 * Record the count: visible via {@link count} synchronously, then persisted.
 	 *
 	 * Writes are SKIPPED when the slot already holds this number, because the sole
-	 * caller runs on every committed membership write *and* every timed reconcile
-	 * pass — a party whose membership is stable would otherwise rewrite the same
-	 * integer forever. The skip is keyed off {@link persisted} rather than
+	 * caller runs on every membership refresh — each committed membership write, each
+	 * replicated membership change, and each reconcile pass down to its backstop — so a
+	 * party whose membership is stable would otherwise rewrite the same integer forever. The skip is keyed off {@link persisted} rather than
 	 * {@link current}, so a write that FAILED is retried by the next refresh instead
 	 * of being suppressed as "unchanged".
 	 */

package/src/formation-token.ts

@@ -0,0 +1,63 @@
+import type { FormationRejectionCode } from './strand-formation-rejection.js';
+
+/** The `FormationInvite` columns a formation session acts on. */
+export interface FormationInviteFacts {
+  sAppId: string;
+  /** Epoch ms of the stored `ExpiresAt`; null when the invitation never expires. */
+  expiresAtMs: number | null;
+  /** Null is unlimited. */
+  totalUses: number | null;
+  /** A bound invitation's host strand; null on the responder-provisions path. */
+  strandId: string | null;
+  /** The outside approval hook; null when no approval is required. */
+  validationUrl: string | null;
+}
+
+/**
+ * One formation token as read once at the start of a responder session. Every later step of
+ * the session takes this value instead of reading the invite again.
+ */
+export interface FormationTokenRead {
+  token: string;
+  /** Null: no invite row here (it may not have replicated to this machine yet). */
+  invite: FormationInviteFacts | null;
+  /** Uses recorded so far; counted only for a metered, unexpired invite, else null. */
+  usesRecorded: number | null;
+}
+
+/**
+ * What the responder's token check yields; an invalid token names which way it failed. The
+ * valid arm carries the session's {@link FormationTokenRead}, absent only when the manager has
+ * no recorder and so accepts every token with nothing read.
+ */
+export type FormationTokenCheck =
+  | { valid: true; read?: FormationTokenRead }
+  | { valid: false; code: Extract<FormationRejectionCode, 'token-unknown' | 'token-spent'> };
+
+/**
+ * `expiresAtMs <= nowMs` is expired: the same boundary `hasOutstandingFormationInvite` applies,
+ * so an invite the formation handler refuses can never hold the connection gate open.
+ */
+export function isInviteExpired(invite: FormationInviteFacts, nowMs: number): boolean {
+  return invite.expiresAtMs !== null && invite.expiresAtMs <= nowMs;
+}
+
+/** Used up: a metered invite whose recorded uses reached `totalUses`. An unknown token is not used up. */
+export function isTokenReadSpent(read: FormationTokenRead): boolean {
+  const totalUses = read.invite?.totalUses ?? null;
+  return totalUses !== null && read.usesRecorded !== null && read.usesRecorded >= totalUses;
+}
+
+/**
+ * No invite row is `'token-unknown'` (retryable: the row may not have replicated to this
+ * machine yet); an expired or used-up invite is `'token-spent'` (final).
+ */
+export function classifyTokenRead(read: FormationTokenRead, nowMs: number): FormationTokenCheck {
+  if (read.invite === null) {
+    return { valid: false, code: 'token-unknown' };
+  }
+  if (isInviteExpired(read.invite, nowMs) || isTokenReadSpent(read)) {
+    return { valid: false, code: 'token-spent' };
+  }
+  return { valid: true, read };
+}