@serfab/cadre-core 1.7.0 → 1.9.0

package/src/index.ts

@@ -117,10 +117,10 @@ export {
   type EnrolledMachineStore
 } from './enrolled-machine-store.js';
 
-// Node-local record of the strands this node joined from ANOTHER party, re-offered on
-// every start as `strand:discovered`. Cross-platform: its durable form rides the
-// KeyStore seam above (the record carries a closed strand's read secret), so there is
-// no file-backed subpath.
+// Node-local record of the strands this node joined from ANOTHER party and has not yet
+// published party-wide, re-offered on every start as `strand:discovered`.
+// Cross-platform: its durable form rides the KeyStore seam above (the record carries a
+// closed strand's read secret), so there is no file-backed subpath.
 export {
   MemoryJoinedStrandStore,
   KeyStoreJoinedStrandStore,
@@ -128,66 +128,27 @@ export {
   type JoinedStrandRecord
 } from './joined-strand-store.js';
 
-// Node-local strand peer book: per strand, the strand peers this node has met and
-// their last-known addresses, dialed first on every launch so a restarted machine
-// re-finds the other parties. Same cross-platform split as the bootstrap-peer store
-// above — interface + in-memory + slot-backed stores here, Node-only file backend
-// behind the subpath '@serfab/cadre-core/strand-peer-book-file'.
-export {
-  MemoryStrandPeerBookStore,
-  PersistentStrandPeerBookStore,
-  mergeStrandPeerEntry,
-  sanitizeStrandPeerEntry,
-  strandPeerFreshness,
-  MAX_STRAND_PEERS,
-  STRAND_PEER_MAX_AGE_MS,
-  type StrandPeerBookStore,
-  type StrandPeerBookOptions,
-  type StrandPeerEntry
-} from './strand-peer-book.js';
-export {
-  StrandPeerObserver,
-  dialableAddrs,
-  connectedIdentifiedPeers,
-  STRAND_PEER_OBSERVE_THROTTLE_MS,
-  type StrandPeerObservation,
-  type StrandPeerObserverDeps,
-  type StrandPeerObserverOptions,
-  type ConnectedIdentifiedPeer
-} from './strand-peer-observer.js';
-// The signed book SWAP between strand peers (`/sereus/strand-peers/1.0.0`): the wire
-// protocol, signing and verification, and the per-strand driver that arms it.
-export {
-  STRAND_PEER_BOOK_PROTOCOL,
-  SIGNED_STRAND_PEER_ENTRY_VERSION,
-  STRAND_PEER_ISSUED_AT_SKEW_MS,
-  MAX_BOOK_FRAME_SIZE,
-  StrandPeerBookService,
-  exchangeStrandPeerBook,
-  signStrandPeerEntry,
-  signedStrandPeerEntryPayload,
-  verifySignedStrandPeerEntry,
-  verifyStrandPeerBookFrame,
-  trimBookFrameToFit,
-  assertBookFrameFits,
-  type SignedStrandPeerEntry,
-  type StrandPeerBookFrame,
-  type StrandPeerEntryVerdict,
-  type StrandPeerBookServiceDeps,
-  type ExchangeStrandPeerBookOptions
-} from './strand-peer-book-protocol.js';
-export {
-  StrandPeerBookSwap,
-  STRAND_PEER_BOOK_SWAP_THROTTLE_MS,
-  OWN_ENTRY_RESIGN_DEBOUNCE_MS,
-  type StrandPeerBookSwapDeps,
-  type StrandPeerBookSwapOptions
-} from './strand-peer-book-swap.js';
+// Node-local strand network state: per strand, the state Optimystic's db-p2p saves for
+// the strand node (its FRET routing table with each peer's signed address record), so a
+// restarted strand node re-imports the peers it was talking to. Same cross-platform
+// split as the bootstrap-peer store above — interface + in-memory + slot-backed stores
+// here, Node-only file backend behind '@serfab/cadre-core/strand-network-state-file'.
+export {
+  MemoryStrandNetworkStateStore,
+  PersistentStrandNetworkStateStore,
+  strandNetworkStatePersistence,
+  type StrandNetworkStateStore
+} from './strand-network-state.js';
+// The signed address records a running strand node's FRET table holds, as per-peer dial
+// addresses: what the periodic refresh re-merges into the node's address book, and a
+// diagnostic for "whom could this strand node redial right now?".
+export { strandFretPeerAddrs, type FretAddrHost, type FretPeerAddrs } from './strand-fret-addrs.js';
 
 // Storage scope keys — what `CadreNodeConfig.storage.provider` is called with. A
 // strand's key is its strand id; the control database's key carries the party id,
 // so two parties on one device never share a control store. Every key stays within
-// `[A-Za-z0-9._-]`: the control key by base64url encoding, a strand's by
+// `[a-z0-9._-]` — lowercase, so distinct keys stay distinct on a case-insensitive
+// filesystem: the control key by lowercase hex encoding, a strand's by
 // `assertStrandScopeKey`, which every strand launch runs.
 export {
   controlStorageScope,
@@ -305,6 +266,8 @@ export {
   createDefaultFormationResponseValidator,
   type DisclosureValidator,
   type FormationUsageRecorder,
+  type FormationUsageParams,
+  type AuthorizedFormationUsage,
   type ResolvedHostStrand,
   type StrandProvisioner,
   type FormationResponseValidator,
@@ -430,14 +393,16 @@ export {
 } from './strand-wake-protocol.js';
 
 // Strand Address (control-network strand-address RPC) — wire types come via
-// `export * from './types.js'` (StrandAddrRequest / StrandAddrResponse).
+// `export * from './types.js'` (StrandAddrRequest / StrandAddrResponse / StrandAddrStatus).
 export {
   StrandAddrService,
   collectStrandAddrs,
   STRAND_ADDR_PROTOCOL,
   type StrandAddrServiceOptions,
   type StrandAddrPeer,
-  type CollectStrandAddrsOptions
+  type CollectStrandAddrsOptions,
+  type StrandAddrOutcome,
+  type StrandAddrCollection
 } from './strand-addr-protocol.js';
 
 // Peer-address record (self-published, signed, freshness-stamped CadrePeer row)
@@ -504,6 +469,7 @@ export {
 // limit, so an address that never answers cannot starve the rest.
 export {
   dialPeerAddrs,
+  SelfRelayOnlyError,
   tryAddrsInTurn,
   directBeforeRelayed,
   DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS,
@@ -521,12 +487,14 @@ export {
   RELAYED_DIAL_ROUND_TRIPS,
   RELAY_RESERVATION_ROUND_TRIPS,
   CIRCUIT_REQUEST_ROUND_TRIPS,
+  RELAYED_REQUEST_ROUND_TRIPS,
   PUSH_TRANSFER_ALLOWANCE_MS,
+  ADMISSION_DECISION_TIMEOUT_MS,
   resolveLinkRoundTripMs,
   relayedDialBudgetMs,
-  connectionManagerTimeouts,
   relayReservationBudgetMs,
   circuitRequestBudgetMs,
+  relayedRequestBudgetMs,
   peerJoinPushBudget,
   type PeerJoinPushBudget
 } from './link-budget.js';
@@ -568,6 +536,7 @@ export {
   type FormationDialResult,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
+export { formationDeadlines, type FormationDeadlines } from './strand-formation-deadlines.js';
 
 // Strand Formation manager (drives the native transport)
 export {
@@ -576,6 +545,7 @@ export {
   MEMBERSHIP_INVITE_TTL_MS,
   MEMBERSHIP_INVITE_UNAVAILABLE_REASON,
   HOST_STRAND_MUST_BE_RECREATED_REASON,
+  type MembershipInviteIssuer,
   type StrandFormationManagerConfig,
   type StrandFormationManagerOptions
 } from './strand-formation-manager.js';
@@ -585,11 +555,9 @@ export {
   createMembershipConnectionGater,
   STRANGER_OPEN_PROTOCOLS,
   DEFAULT_ENROLLMENT_WINDOW_MS,
-  ADMISSION_DECISION_TIMEOUT_MS,
   RELAY_ADMISSION_RESERVE_DEADLINE_MS,
   RELAY_ADMISSION_CLOSE_TIMEOUT_MS,
   MAX_UNAUTHORIZED_RELAY_RESERVATIONS,
-  UNAUTHORIZED_RESERVATION_TTL_MS,
   UnauthorizedReservationBudget,
   type InboundAdmissionPolicy,
   type InboundConnectionVerdict
@@ -615,6 +583,16 @@ export {
   resolveListenAddrs
 } from './relay-addrs.js';
 export { strandNodeAddrs, type StrandNodeAddrs } from './strand-network-config.js';
+// The circuit-relay SERVER a node runs, and with which init — one resolution shared by the
+// control node and every strand node. Exported alongside the listen derivations above for the
+// same reason: an embedder can assert on what its `network` block resolves to.
+export {
+  resolveRelayServer,
+  PARTY_RELAY_MAX_RESERVATIONS,
+  PARTY_RELAY_RESERVATION_TTL_MS,
+  type ResolvedRelayServer,
+  type ResolvedRelayReservations
+} from './relay-server.js';
 
 // Relay reservation via the bare `/p2p-circuit` search listener — the one route
 // every control node takes; `network.relayAddrs` is its fail-fast posture

package/src/joined-strand-store.ts

@@ -1,18 +1,25 @@
 /**
- * Node-local record of the strands this node joined from ANOTHER party.
+ * The strands this party joined from ANOTHER party, held in two records.
  *
  * A party's own strands come back after a restart through its control database: the
  * `Strand` table holds their rows, the strand watcher polls it, and each row no sApp
  * config claims is offered as `strand:discovered`. A strand joined through formation with
- * another party (`CadreNode.formStrand`) has no row there — the other party's control
- * database holds it — so nothing re-offered it after a restart, and every embedding app
- * kept its own list of joins, read secret included (gotchoices/sereus#18).
+ * another party (`CadreNode.formStrand`) has its `Strand` row in the OTHER party's control
+ * database, so it needs a record of its own (gotchoices/sereus#18):
  *
- * `CadreNode` records each such join here, hands the records to its strand watcher beside
- * the control rows ({@link JoinedStrandRows}), and forgets one on `forgetJoinedStrand` or
- * when this party is removed from the strand.
+ *  - the PARTY-WIDE record, a `CadreControl.JoinedStrand` row ({@link PartyJoinedStrandLedger}).
+ *    Once it exists it is the authority: every machine of the party offers it, a storage
+ *    replica host launches it, and removing it is how the party leaves the strand;
+ *  - the MACHINE-LOCAL record ({@link JoinedStrandStore}, below), a queue of joins this
+ *    machine made that the party does not know about yet. A join is recorded here first,
+ *    published by an owner machine's connected reconcile pass, and forgotten as soon as the
+ *    party-wide row is visible, so a local record always means "joined here, not yet
+ *    published". A machine that is not an owner never publishes; its joins stay here.
  *
- * Two implementations:
+ * {@link JoinedStrandSession} moves joins between the two and is what the strand watcher
+ * polls beside the control rows.
+ *
+ * Two store implementations:
  *  - {@link MemoryJoinedStrandStore} — joins die with the process. The default only for a
  *    node configured with no `keyStore`.
  *  - {@link KeyStoreJoinedStrandStore} — one {@link KeyStore} slot per join. A record holds
@@ -35,7 +42,7 @@ import type { StrandRow } from './types.js';
 
 const log = debug('sereus:cadre:joined-strand-store');
 
-/** One strand this node joined from ANOTHER party — nothing in this party's control DB names it. */
+/** One strand this node joined from ANOTHER party and has not yet published party-wide. */
 export interface JoinedStrandRecord {
 	/** The strand id (a valid scope key, see storage-scope.ts). */
 	Id: string;
@@ -222,85 +229,268 @@ function parseRecord(strandId: string, bytes: Uint8Array): JoinedStrandRecord |
 }
 
 /**
- * What the strand watcher sees of the joined-strand store: the control rows plus one row per
- * remembered join, which is how a join comes back as `strand:discovered` (or auto-launches)
- * after a restart with no second offer path. One instance per node session.
+ * The party-wide joined-strand table (`CadreControl.JoinedStrand`), as the node's control
+ * database exposes it. `CadreNode` builds it over `ControlDatabase` and the owner signing
+ * key; this module sees only the seam, so it stays free of the runtime.
+ */
+export interface PartyJoinedStrandLedger {
+	/** Every party-wide join, as offerable rows (`FounderOwnerKey: null`). */
+	list(): Promise<StrandRow[]>;
+	/** Whether this party's control database names `strandId`, as its own strand or as a party-wide join. */
+	names(strandId: string): Promise<boolean>;
+	/** Whether this machine can sign {@link publish} and {@link remove}: it holds an owner key the party enrolls. */
+	canSign(): Promise<boolean>;
+	/** Owner-signed insert. Resolves when the row landed or a sibling's join already holds the id. */
+	publish(record: JoinedStrandRecord): Promise<void>;
+	/** Owner-signed delete + tombstone; false when there is no row. Throws when a row exists and this machine cannot sign. */
+	remove(strandId: string): Promise<boolean>;
+}
+
+/**
+ * One node session's joined strands: what the strand watcher sees of the two records, and
+ * the moves between them. Rebuilt at every start, which is what ends the per-session state
+ * below.
  *
- * Holds the two pieces of state a plain union would get wrong, both of which would otherwise
- * make the watcher detach running strands, since a joined row missing from a poll reads to it
- * as a removal:
- *  - the last list the store answered, reused when a later list fails, so a read failure is
- *    not "every join was forgotten";
- *  - joins forgotten because this party was removed from the strand
- *    ({@link forgetAfterThisSession}): gone from the store, so the next start does not
- *    re-attach them, but still offered until this session ends, because `strand:revoked`
- *    promises that nothing is torn down for the app.
+ * The watcher reads a row missing from a poll as a removal and detaches the strand, so this
+ * holds the state a plain union would get wrong:
+ *  - the last list each record answered, reused when a later read fails, so a failed read
+ *    is not "every join was forgotten";
+ *  - joins this party was removed from ({@link forgetAfterThisSession}): offered until this
+ *    session ends, because `strand:revoked` promises that nothing is torn down for the app,
+ *    and queued for party-wide removal so the next start does not re-attach them.
  */
-export class JoinedStrandRows {
-	private lastListed: JoinedStrandRecord[] = [];
-	private readonly keptForSession = new Map<string, JoinedStrandRecord>();
+export class JoinedStrandSession {
+	private lastUnpublished: JoinedStrandRecord[] = [];
+	private lastPartyWide: StrandRow[] = [];
+	private readonly keptForSession = new Map<string, StrandRow>();
+	/** Strands whose party-wide row {@link syncWithParty} removes, queued by a self-revocation. */
+	private readonly pendingRemovals = new Set<string>();
+	/**
+	 * Tail of the moves that must not interleave ({@link serialized}): a publish that found no
+	 * party-wide row, then a {@link leave} that removed nothing, then the publish's insert
+	 * would leave the party holding a strand the app just left.
+	 */
+	private exclusive: Promise<unknown> = Promise.resolve();
 
-	constructor(private readonly store: JoinedStrandStore) {}
+	constructor(private readonly store: JoinedStrandStore, private readonly ledger: PartyJoinedStrandLedger) {}
 
 	/**
-	 * `control` plus a row for every remembered join. A control row wins an id collision: the
-	 * strand is this party's own now (its founding party enrolled this machine, say), the
-	 * control database remembers it, and the record is stale — so it is forgotten here.
+	 * `control` plus every join, one row per id, in this precedence: the control rows (the
+	 * party's own strands), then the party-wide joins, then this machine's unpublished joins
+	 * and the joins kept for this session. A local record named by either of the first two in
+	 * a read that succeeded this poll is stale — published, or the strand is the party's own
+	 * now — so it is forgotten here; this also cleans up after a crash between a publish and
+	 * its local forget. One named only by the last-good party-wide list is kept: that list may
+	 * predate a leave the record re-joined after.
 	 */
 	async withControlRows(control: readonly StrandRow[]): Promise<StrandRow[]> {
 		const controlIds = new Set(control.map((row) => row.Id));
-		const joined = new Map<string, JoinedStrandRecord>(this.keptForSession);
-		for (const record of await this.listed()) {
-			joined.set(record.Id, record);
+		const named = new Set(controlIds);
+		const offered = new Map<string, StrandRow>(control.map((row) => [row.Id, row]));
+		const partyWide = await this.partyWide();
+		// NOTE: a party-wide join whose id the party's own `Strand` table also holds (the party
+		// founded AND joined it — contrived) is shadowed here, not deleted: a watcher poll must
+		// not make owner-signed writes. If the party later unpublishes its own row the join row
+		// resurfaces; if that is ever seen, remove the join row inside `unpublishStrand`.
+		for (const row of partyWide.rows) {
+			if (!offered.has(row.Id)) {
+				offered.set(row.Id, row);
+			}
+			if (partyWide.fresh) {
+				named.add(row.Id);
+			}
 		}
-		const rows = [...control];
-		for (const record of joined.values()) {
-			if (controlIds.has(record.Id)) {
+		for (const record of await this.unpublished()) {
+			if (named.has(record.Id)) {
 				await this.forgetSuperseded(record.Id);
-			} else {
-				rows.push(joinedStrandRow(record));
+			} else if (!offered.has(record.Id)) {
+				offered.set(record.Id, joinedStrandRow(record));
+			}
+		}
+		for (const [strandId, row] of this.keptForSession) {
+			if (controlIds.has(strandId)) {
+				this.keptForSession.delete(strandId);
+			} else if (!offered.has(strandId)) {
+				offered.set(strandId, row);
 			}
 		}
-		return rows;
+		return [...offered.values()];
 	}
 
-	/** Forget a join for good: the app is leaving the strand. */
-	async forget(strandId: string): Promise<void> {
-		this.keptForSession.delete(strandId);
-		await this.store.forget(strandId);
+	/** Record a join `formStrand` just made. A re-join also cancels a removal a revocation queued. */
+	async remember(record: JoinedStrandRecord): Promise<void> {
+		this.pendingRemovals.delete(record.Id);
+		await this.store.record(record);
 	}
 
 	/**
-	 * Forget a join durably, but keep offering it until this session ends. For a strand this
-	 * party was removed from: it must not re-attach on every launch, and it must not be torn
-	 * down underneath the app either. A no-op for a strand with no record.
+	 * Record `row`, joined by `addStrand`, unless this party's control database already names
+	 * it (its own strand, or a join already published) or an identical record is already here
+	 * (an app re-claiming a remembered join on every start). Keeps the first `joinedAt`. Like
+	 * {@link remember}, cancels a queued removal.
 	 */
-	async forgetAfterThisSession(strandId: string): Promise<void> {
-		const record = (await this.listed()).find((listed) => listed.Id === strandId);
-		if (!record) {
+	async rememberForeign(row: StrandRow): Promise<void> {
+		this.pendingRemovals.delete(row.Id);
+		if (await this.namedByParty(row.Id)) {
 			return;
 		}
-		// Kept BEFORE the store forgets, so no poll can list the store without it and union
-		// without the kept copy.
-		this.keptForSession.set(strandId, record);
-		await this.store.forget(strandId);
+		const existing = (await this.store.list()).find((record) => record.Id === row.Id);
+		if (existing?.Type === row.Type && existing.MemberPrivateKey === row.MemberPrivateKey) {
+			return;
+		}
+		await this.store.record({
+			Id: row.Id,
+			Type: row.Type,
+			MemberPrivateKey: row.MemberPrivateKey,
+			joinedAt: existing?.joinedAt ?? Date.now()
+		});
+	}
+
+	/**
+	 * Leave a join for the whole party: remove the party-wide row, then this machine's record.
+	 * Throws, keeping both, when a party-wide row exists and this machine cannot sign.
+	 */
+	leave(strandId: string): Promise<void> {
+		return this.serialized(async () => {
+			await this.ledger.remove(strandId);
+			this.pendingRemovals.delete(strandId);
+			this.keptForSession.delete(strandId);
+			this.lastPartyWide = this.lastPartyWide.filter((row) => row.Id !== strandId);
+			await this.store.forget(strandId);
+		});
+	}
+
+	/**
+	 * For a strand this party was removed from: keep offering it until this session ends, and
+	 * queue its party-wide row for removal by {@link syncWithParty}, so it does not re-attach
+	 * on every start of every machine. A no-op for a strand with neither record (one of the
+	 * party's own). The queue is in memory: if the process dies first, the next start
+	 * relaunches the strand, the revoked-peer gate raises `strand:revoked` again, and this
+	 * runs again.
+	 */
+	forgetAfterThisSession(strandId: string): Promise<void> {
+		return this.serialized(async () => {
+			const local = (await this.unpublished()).find((record) => record.Id === strandId);
+			const row = local ? joinedStrandRow(local) : this.lastPartyWide.find((listed) => listed.Id === strandId);
+			if (!row) {
+				return;
+			}
+			// Kept BEFORE the store forgets, so no poll can union without it. Queued even for a
+			// local-only join, which a sibling may have published already.
+			this.keptForSession.set(strandId, row);
+			this.pendingRemovals.add(strandId);
+			if (local) {
+				await this.store.forget(strandId);
+			}
+		});
+	}
+
+	/**
+	 * The owner machine's half, run by the node's connected reconcile pass: publish every
+	 * unpublished join party-wide, then remove the party-wide rows queued by
+	 * {@link forgetAfterThisSession}. Does nothing on a machine that cannot sign, whose joins
+	 * stay machine-local. Per strand, a failure is logged and kept for the next pass; a
+	 * failure to list the store or to check the signer throws.
+	 */
+	syncWithParty(): Promise<void> {
+		return this.serialized(async () => {
+			// Straight from the store, never the last-good list: a stale list could republish a
+			// join that was left since.
+			const unpublished = await this.store.list();
+			if (unpublished.length === 0 && this.pendingRemovals.size === 0) {
+				return;
+			}
+			if (!(await this.ledger.canSign())) {
+				return;
+			}
+			for (const record of unpublished) {
+				await this.publish(record);
+			}
+			for (const strandId of [...this.pendingRemovals]) {
+				await this.removeQueued(strandId);
+			}
+		});
+	}
+
+	// NOTE: a sibling that joined the same strand and has not yet published publishes it after
+	// a leave, bringing the strand back party-wide. Needs two devices joining one strand within
+	// a reconcile interval of the leave; if it is ever seen, check the strand's `Revocation`
+	// tombstone before publishing.
+	private async publish(record: JoinedStrandRecord): Promise<void> {
+		try {
+			if (!(await this.ledger.names(record.Id))) {
+				await this.ledger.publish(record);
+				// Into the last-good list too: its local record goes next, so a party-wide read that
+				// fails before one succeeds would otherwise drop the strand from the poll and hide it
+				// from a self-revocation.
+				this.lastPartyWide = [...this.lastPartyWide.filter((row) => row.Id !== record.Id), joinedStrandRow(record)];
+				log('joined strand %s published party-wide (party=%s)', record.Id, this.store.partyId);
+			}
+			await this.store.forget(record.Id);
+		} catch (error) {
+			log('joined strand %s: publishing party-wide failed; kept for the next pass: %o', record.Id, error);
+		}
+	}
+
+	private async removeQueued(strandId: string): Promise<void> {
+		try {
+			const removed = await this.ledger.remove(strandId);
+			this.pendingRemovals.delete(strandId);
+			log('joined strand %s: party-wide row %s after this party was removed from it',
+				strandId, removed ? 'removed' : 'already absent');
+		} catch (error) {
+			log('joined strand %s: removing the party-wide row failed; queued for the next pass: %o', strandId, error);
+		}
+	}
+
+	/** The party-wide joins; `fresh` is false when this read failed and the last list it answered stands in. */
+	private async partyWide(): Promise<{ rows: StrandRow[]; fresh: boolean }> {
+		try {
+			this.lastPartyWide = await this.ledger.list();
+			return { rows: this.lastPartyWide, fresh: true };
+		} catch (error) {
+			log('party-wide joined-strand read failed; offering the last list it answered (%d join(s)): %o',
+				this.lastPartyWide.length, error);
+			return { rows: this.lastPartyWide, fresh: false };
+		}
+	}
+
+	/**
+	 * {@link PartyJoinedStrandLedger.names}, answering false when the control database cannot
+	 * be read (a machine cut off from its party before it received the `JoinedStrand` block).
+	 * Recording is the safe side: a local record the party turns out to name is forgotten by
+	 * the next poll that reads it, while a join with no record is not offered after a restart.
+	 */
+	private async namedByParty(strandId: string): Promise<boolean> {
+		try {
+			return await this.ledger.names(strandId);
+		} catch (error) {
+			log('joined strand %s: could not read whether the control database names it; recording it locally: %o', strandId, error);
+			return false;
+		}
+	}
+
+	/** Run `work` after every earlier serialized move settles; see {@link exclusive}. */
+	private serialized<T>(work: () => Promise<T>): Promise<T> {
+		const result = this.exclusive.then(work);
+		this.exclusive = result.catch(() => undefined);
+		return result;
 	}
 
-	private async listed(): Promise<JoinedStrandRecord[]> {
+	private async unpublished(): Promise<JoinedStrandRecord[]> {
 		try {
-			this.lastListed = await this.store.list();
+			this.lastUnpublished = await this.store.list();
 		} catch (error) {
 			log('joined-strand store list failed; offering the last list it answered (%d join(s)): %o',
-				this.lastListed.length, error);
+				this.lastUnpublished.length, error);
 		}
-		return this.lastListed;
+		return this.lastUnpublished;
 	}
 
 	private async forgetSuperseded(strandId: string): Promise<void> {
-		this.keptForSession.delete(strandId);
 		try {
 			await this.store.forget(strandId);
-			log('joined strand %s now has a control row — record forgotten', strandId);
+			log('joined strand %s is named by this party\'s control database — local record forgotten', strandId);
 		} catch (error) {
 			log('forgetting superseded joined strand %s failed; the next poll retries: %o', strandId, error);
 		}

package/src/key-store-file.ts

@@ -45,19 +45,28 @@ function encodeKeyId(keyId: KeyId): string {
 
 /**
  * Reverse {@link encodeKeyId}: strip the slot suffix and percent-decode. Returns
- * `undefined` for a `.key` filename this store did not write (a foreign file
- * with an invalid percent-sequence), so {@link FileKeyStore.list} can skip it
- * rather than letting one undecodable entry throw and break enumeration of every
- * real slot.
+ * `undefined` for a `.key` filename this store did not write, so
+ * {@link FileKeyStore.list} can skip it rather than letting one undecodable
+ * entry throw and break enumeration of every real slot. That includes a name
+ * that decodes but is not the one {@link encodeKeyId} produces for the result
+ * (e.g. a slot written before uppercase letters were escaped):
+ * {@link FileKeyStore.get} looks only at the canonical name, so listing it
+ * would name a key id that reads back as absent.
  */
 function decodeKeyId(fileName: string): KeyId | undefined {
 	const encoded = fileName.slice(0, -SLOT_SUFFIX.length);
+	let keyId: KeyId;
 	try {
-		return decodeURIComponent(encoded);
+		keyId = decodeURIComponent(encoded);
 	} catch (error) {
 		log('FileKeyStore: skipping undecodable slot filename %s: %o', fileName, error);
 		return undefined;
 	}
+	if (encodeKeyId(keyId) !== encoded) {
+		log('FileKeyStore: skipping non-canonical slot filename %s', fileName);
+		return undefined;
+	}
+	return keyId;
 }
 
 /**