@serfab/cadre-core 1.17.0 → 1.19.0

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 };
+}

package/src/index.ts

@@ -16,12 +16,13 @@ export { MachineRemovalRefusedError } from './machine-removal.js';
 export { OwnerKeyAddRefusedError, OwnerKeyRemovalRefusedError } from './owner-keys.js';
 
 // Control database
-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';
+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 FoundingRows, type FoundingInvite, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef, type ControlSign, type SelfRecordSigner, type CadrePeerRetouchMode, type CadrePeerRetouchOutcome, 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';
+// The control schema version a store is migrated to on start, and what `start()` throws, with a
+// reason, when the store must not be migrated (docs/architecture.md → "Control schema versions and
+// migrations")
+export { CONTROL_SCHEMA_VERSION, CONTROL_SCHEMA_BASELINE_VERSION, CONTROL_SCHEMA_VERSION_TAG } from './control-schema.js';
+export { ControlStoreIncompatibleError, type ControlStoreIncompatibility } 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
@@ -29,9 +30,11 @@ export { ControlStoreIncompatibleError } from './control-schema-version.js';
 export {
   CONTROL_WRITE_ATTEMPTS,
   CONTROL_WRITE_RETRY_BUDGET_MS,
+  LOST_UPDATE_RETRY_POLICY,
   SCHEMA_INIT_ATTEMPTS,
   SCHEMA_INIT_RETRY_POLICY,
   isRetriableControlWriteFailure,
+  isRetriableLostUpdateFailure,
   isRetriableSchemaInitFailure,
   retryControlWrite,
   type ControlWriteRetryOptions
@@ -236,10 +239,7 @@ export {
 export {
   StrandAwaitingFirstSyncError,
   DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS,
-  DEFAULT_STRAND_FIRST_SYNC_POLL_MS,
-  strandHeaderHeld,
-  appTablesReadable,
-  strandFirstSyncComplete,
+  DEFAULT_STRAND_FIRST_SYNC_BACKSTOP_MS,
   type StrandFirstSyncConfig
 } from './strand-first-sync-gate.js';
 
@@ -249,7 +249,6 @@ export {
 export {
   PeerJoinBackfill,
   DEFAULT_PEER_JOIN_BACKFILL,
-  MAX_BLOCK_MESSAGE_BYTES,
   PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES,
   type PeerJoinBackfillConfig,
   type PeerJoinBackfillDeps,
@@ -269,14 +268,15 @@ export {
   StrandRevocationEnforcer,
   createRevocationConnectionGater,
   readStrandRevocationRows,
-  DEFAULT_REVOCATION_POLL_INTERVAL_MS,
+  DEFAULT_REVOCATION_BACKSTOP_MS,
+  REVOCATION_REFRESH_RETRY_MS,
+  REVOCATION_WIDE_STRAND_REFRESH_MS,
   type StrandRevocationEnforcementConfig,
   type StrandRevocationEnforcerDeps,
   type StrandRevocationRows,
   type StrandMemberPeerBinding,
   type StrandRevocationJudge,
-  type StrandRevocationNetwork,
-  type RevocationRefreshScheduler
+  type StrandRevocationNetwork
 } from './strand-revocation-enforcer.js';
 
 // Closed-strand membership reconciliation: the bring-up loop that finishes a
@@ -285,6 +285,7 @@ export {
 // bring-up (see the module doc for the pass ladder and terminal states).
 export {
   StrandMembershipReconciler,
+  DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS,
   IDLE_PASSES_BEFORE_ESCALATION,
   INITIAL_JOIN_RETRY_INTERVAL_MS,
   type StrandMembershipReconcilerDeps,
@@ -292,8 +293,8 @@ export {
   type PendingMembershipInviteSource
 } from './strand-membership-reconciler.js';
 
-// The timer seam the self-rescheduling strand bring-up loops share (first-sync gate
-// probe loop, membership retry ladder) — injected by tests as a hand-cranked clock.
+// The timer seam the self-rescheduling loops share (membership retry ladder, the table
+// change schedule the first-sync gate probes on) — injected by tests as a hand-cranked clock.
 export { defaultTimeoutScheduler, type TimeoutScheduler } from './timeout-scheduler.js';
 
 // Hibernation
@@ -324,6 +325,7 @@ export {
   type FormationUsageRecorder,
   type FormationUsageParams,
   type AuthorizedFormationUsage,
+  type BoundHostStrand,
   type ResolvedHostStrand,
   type StrandProvisioner,
   type FormationResponseValidator,
@@ -420,6 +422,7 @@ export {
   SeedBootstrapService,
   SEED_PROTOCOL,
   mergeSeedPeers,
+  seedDialTargets,
   seedDigest,
   type SeedBootstrapConfig,
   type SeedEventCallbacks
@@ -532,11 +535,12 @@ export {
 } from './push-fanout.js';
 
 // Control-cohort dial selection (backbone-preferential, bounded out-degree) +
-// the cadence/degree defaults the proactive reconcile routine reads.
+// the backstop, redial and degree defaults the proactive reconcile routine reads.
 export {
   selectControlCohortDials,
   DEFAULT_CONTROL_COHORT_RECONCILE_MS,
   DEFAULT_CONTROL_COHORT_TARGET_DEGREE,
+  CONTROL_COHORT_REDIAL_MS,
   type ControlCohortSelection,
   type ControlCohortReconcileResult
 } from './control-cohort.js';
@@ -694,9 +698,16 @@ export {
   type FormationDialOptions,
   type FormationDialResult,
   type FormationRejection,
-  type FormationTokenCheck,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
+// A responder session's one read of its formation token, and the check made from it
+export {
+  classifyTokenRead,
+  isTokenReadSpent,
+  type FormationInviteFacts,
+  type FormationTokenRead,
+  type FormationTokenCheck
+} from './formation-token.js';
 // How a formation dial fails: a typed refusal (with a fixed code) or no answer at all
 export {
   FormationRejectedError,
@@ -736,6 +747,7 @@ export {
   type RedeemAtMembersOptions,
   type RedeemInPassesOptions,
   type RedeemSigner,
+  type RedeemSelfRecord,
   type CadreInviteRedemption
 } from './cadre-invite-protocol.js';
 // Owner grant redemption transport: the bundle an owner hands out, the wire messages, the
@@ -788,7 +800,7 @@ export {
   CADRE_INVITATION_ADDRS_PER_SIBLING
 } from './invitation-bootstrap.js';
 // The pending-join retry loop behind CadreNode.requestJoin (PendingJoinStatus is in types.ts)
-export { PENDING_JOIN_POLL_MS, PENDING_JOIN_MAX_BACKOFF_MS, MAX_PENDING_JOIN_MS } from './pending-join-runner.js';
+export { PENDING_JOIN_BACKSTOP_MS, PENDING_JOIN_MAX_BACKOFF_MS, MAX_PENDING_JOIN_MS } from './pending-join-runner.js';
 
 // Strand Formation manager (drives the native transport)
 export {

package/src/joined-strand-store.ts

@@ -2,7 +2,7 @@
  * 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
+ * `Strand` table holds their rows, the strand watcher reads it, and each row no sApp
  * config claims is offered as `strand:discovered`. A strand joined through formation with
  * 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):
@@ -17,7 +17,7 @@
  *    published". A machine that is not an owner never publishes; its joins stay here.
  *
  * {@link JoinedStrandSession} moves joins between the two and is what the strand watcher
- * polls beside the control rows.
+ * reads beside the control rows.
  *
  * Two store implementations:
  *  - {@link MemoryJoinedStrandStore} — joins die with the process. The default only for a
@@ -76,6 +76,10 @@ export function joinedStrandRow(record: JoinedStrandRecord): StrandRow {
 	return { Id: record.Id, Type: record.Type, MemberPrivateKey: record.MemberPrivateKey, FounderOwnerKey: null, FounderPeerId: null };
 }
 
+function isSameJoin(record: JoinedStrandRecord, row: StrandRow): boolean {
+	return record.Type === row.Type && record.MemberPrivateKey === row.MemberPrivateKey;
+}
+
 /**
  * Ephemeral store for a node without a `keyStore`. Warns once, at the first join it is
  * asked to remember, because a join held only here is not re-offered after a restart —
@@ -124,9 +128,9 @@ const SLOT_PREFIX = 'cadre/joined-strand/';
  * arbitrary text, and base64url never contains the `/` that ends the segment.
  *
  * Loads every slot once, at the first {@link list}, then answers from memory and writes
- * through, so the strand watcher's five-second poll does not read the enclave on every
- * pass. A load that fails — `KeyStoreAccessError` from a refused unlock prompt, say —
- * is rethrown rather than read as "no joins" and retried at the next call, exactly as
+ * through, so a strand watcher run does not read the enclave each time. A load that
+ * fails — `KeyStoreAccessError` from a refused unlock prompt, say — is rethrown rather
+ * than read as "no joins" and retried at the next call, exactly as
  * `loadOrCreateIdentityKey` treats the identity slot. A slot that does not parse as a
  * record for its own id is dropped with a log and its siblings kept: refusing to start
  * repairs nothing, and the other joins are still good.
@@ -176,9 +180,10 @@ export class KeyStoreJoinedStrandStore implements JoinedStrandStore {
 		return result;
 	}
 
-	// NOTE: a failed load is retried at the next list(), which is every strand-watcher poll;
-	// over a backend that gates reads behind an unlock prompt the user keeps declining, that
-	// is a prompt every five seconds. Every KeyStore shipped today is ungated for this reason
+	// NOTE: a failed load is retried at the next list(), which is every strand-watcher run (a
+	// change to `Strand` or `JoinedStrand`, a local join, a retry, the backstop); over a backend
+	// that gates reads behind an unlock prompt the user keeps declining, that is a prompt per
+	// run. Every KeyStore shipped today is ungated for this reason
 	// (see `SecureStoreKeyStoreOptions.requireAuthentication`); if one is ever gated, back
 	// off the retry here.
 	private async loaded(): Promise<Map<string, JoinedStrandRecord>> {
@@ -251,7 +256,7 @@ export interface PartyJoinedStrandLedger {
  * the moves between them. Rebuilt at every start, which is what ends the per-session state
  * below.
  *
- * The watcher reads a row missing from a poll as a removal and detaches the strand, so this
+ * The watcher reads a row missing from a run's read 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";
@@ -262,6 +267,8 @@ export interface PartyJoinedStrandLedger {
 export class JoinedStrandSession {
 	private lastUnpublished: JoinedStrandRecord[] = [];
 	private lastPartyWide: StrandRow[] = [];
+	/** Whether the last party-wide read in {@link withControlRows} succeeded; see {@link lastReadPartial}. */
+	private lastPartyWideFresh = true;
 	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>();
@@ -272,13 +279,23 @@ export class JoinedStrandSession {
 	 */
 	private exclusive: Promise<unknown> = Promise.resolve();
 
-	constructor(private readonly store: JoinedStrandStore, private readonly ledger: PartyJoinedStrandLedger) {}
+	/**
+	 * @param onLocalChange - Called after a move changes what {@link withControlRows} merges in
+	 *   from outside the control database (this machine's unpublished joins, the joins kept for
+	 *   this session), which no control-table change event reports. `CadreNode` wakes its strand
+	 *   watcher with it.
+	 */
+	constructor(
+		private readonly store: JoinedStrandStore,
+		private readonly ledger: PartyJoinedStrandLedger,
+		private readonly onLocalChange: () => void = () => {}
+	) {}
 
 	/**
 	 * `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
+	 * a read that succeeded this run 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.
@@ -289,7 +306,7 @@ export class JoinedStrandSession {
 		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
+		// founded AND joined it — contrived) is shadowed here, not deleted: a watcher run 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) {
@@ -317,10 +334,18 @@ export class JoinedStrandSession {
 		return [...offered.values()];
 	}
 
+	/**
+	 * True when the last {@link withControlRows} offered the party-wide joins from the last
+	 * list that answered, because its read of `JoinedStrand` failed.
+	 */
+	lastReadPartial(): boolean {
+		return !this.lastPartyWideFresh;
+	}
+
 	/**
 	 * This machine's unpublished joins, straight from the store (never the last-good list a
 	 * failed read stands in with). What a strand move exports beside the `JoinedStrand`
-	 * table: a machine publishes only while it holds a control connection, so until then its
+	 * table: a machine publishes only while a sibling is reachable, so until then its
 	 * joins live only here.
 	 */
 	unpublishedRecords(): Promise<JoinedStrandRecord[]> {
@@ -331,21 +356,32 @@ export class JoinedStrandSession {
 	async remember(record: JoinedStrandRecord): Promise<void> {
 		this.pendingRemovals.delete(record.Id);
 		await this.store.record(record);
+		this.onLocalChange();
 	}
 
 	/**
 	 * 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
+	 * (an app re-claiming a remembered join on every start, or `addStrand` right after
+	 * `formStrand`). The store is asked first: it answers from memory once loaded, so the
+	 * common re-claim reads no control row. Keeps the first `joinedAt`. Like
 	 * {@link remember}, cancels a queued removal.
 	 */
 	async rememberForeign(row: StrandRow): Promise<void> {
 		this.pendingRemovals.delete(row.Id);
+		const early = await this.storedRecord(row.Id).catch((error: unknown) => {
+			// Asked again below only when the party does not name the strand; a second failure throws.
+			log('joined strand %s: store lookup failed; asking the control database first: %o', row.Id, error);
+			return null;
+		});
+		if (early && isSameJoin(early, row)) {
+			return;
+		}
 		if (await this.namedByParty(row.Id)) {
 			return;
 		}
-		const existing = (await this.store.list()).find((record) => record.Id === row.Id);
-		if (existing?.Type === row.Type && existing.MemberPrivateKey === row.MemberPrivateKey) {
+		const existing = early === null ? await this.storedRecord(row.Id) : early;
+		if (existing && isSameJoin(existing, row)) {
 			return;
 		}
 		await this.store.record({
@@ -354,6 +390,7 @@ export class JoinedStrandSession {
 			MemberPrivateKey: row.MemberPrivateKey,
 			joinedAt: existing?.joinedAt ?? Date.now()
 		});
+		this.onLocalChange();
 	}
 
 	/**
@@ -367,6 +404,7 @@ export class JoinedStrandSession {
 			this.keptForSession.delete(strandId);
 			this.lastPartyWide = this.lastPartyWide.filter((row) => row.Id !== strandId);
 			await this.store.forget(strandId);
+			this.onLocalChange();
 		});
 	}
 
@@ -385,13 +423,14 @@ export class JoinedStrandSession {
 			if (!row) {
 				return;
 			}
-			// Kept BEFORE the store forgets, so no poll can union without it. Queued even for a
+			// Kept BEFORE the store forgets, so no watcher run 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);
 			}
+			this.onLocalChange();
 		});
 	}
 
@@ -423,15 +462,16 @@ export class JoinedStrandSession {
 	}
 
 	// 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`
+	// a leave, bringing the strand back party-wide. Needs a second device to have joined the
+	// strand and not yet run a connected reconcile pass when the leave lands (a join starts no
+	// pass, so up to the 2-minute backstop); 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
+				// fails before one succeeds would otherwise drop the strand from the watcher's read 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);
@@ -457,19 +497,20 @@ export class JoinedStrandSession {
 	private async partyWide(): Promise<{ rows: StrandRow[]; fresh: boolean }> {
 		try {
 			this.lastPartyWide = await this.ledger.list();
-			return { rows: this.lastPartyWide, fresh: true };
+			this.lastPartyWideFresh = 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 };
+			this.lastPartyWideFresh = false;
 		}
+		return { rows: this.lastPartyWide, fresh: this.lastPartyWideFresh };
 	}
 
 	/**
 	 * {@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.
+	 * the next watcher run that reads it, while a join with no record is not offered after a restart.
 	 */
 	private async namedByParty(strandId: string): Promise<boolean> {
 		try {
@@ -480,6 +521,10 @@ export class JoinedStrandSession {
 		}
 	}
 
+	private async storedRecord(strandId: string): Promise<JoinedStrandRecord | undefined> {
+		return (await this.store.list()).find((record) => record.Id === strandId);
+	}
+
 	/** 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);
@@ -502,7 +547,7 @@ export class JoinedStrandSession {
 			await this.store.forget(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);
+			log('forgetting superseded joined strand %s failed; the next watcher run retries: %o', strandId, error);
 		}
 	}
 }

package/src/link-budget.ts

@@ -392,13 +392,15 @@ export const PUSH_TRANSFER_ALLOWANCE_MS = 6000;
  *   every members-only protocol from the materialized snapshot, and unplaced
  *   relay reservations stay capped (`MAX_UNAUTHORIZED_RELAY_RESERVATIONS`).
  * - **The slow case is bring-up, not steady state.** A membership read consults
- *   the cohort only for a block this node does not hold, or before the
- *   `Revocation` ledger marker exists; once the marker exists every block the
- *   decision reads is held (`control-founding-consult-budget.spec.ts` pins both
- *   states). So the gate always fails open only on a node whose membership reads
- *   still consult: one consult costs about two link round trips, and asking a
- *   silent peer costs the per-peer read deadline ({@link cohortReadDeadlineMs}, 7 s
- *   at the default declaration).
+ *   the cohort only for a block this node does not hold: before a joining
+ *   machine has read it from the cohort, or for a table nobody has written on a
+ *   party founded before genesis created every control collection. Otherwise
+ *   every block the decision reads is held
+ *   (`control-founding-consult-budget.spec.ts` pins that). So the gate always
+ *   fails open only on a node whose membership reads still consult: one consult
+ *   costs about two link round trips, and asking a silent peer costs the
+ *   per-peer read deadline ({@link cohortReadDeadlineMs}, 7 s at the default
+ *   declaration).
  * - **The decision is spent on the dialing machine's clock.** libp2p's listener
  *   runs this gate before it answers the multiplexer negotiation the dialer is
  *   waiting on (`libp2p/dist/src/upgrader.js`), and the listener's own

package/src/member-redemption.ts

@@ -170,12 +170,16 @@ export interface MemberRedemptionHandlerOptions {
  * Registered only by a started `CadreNode`, after its control database is up, like the
  * formation responder; nothing here is reachable on a node without one.
  *
- * A subclass supplies the five credential-specific pieces: the request's shape, the checks after
- * it, the liveness read behind the push, the writes, and the two fixed refusals the base sends
- * on its own (`busy`, and `internal` for a frame it could not read or a failure it did not
- * expect).
+ * A subclass supplies the six credential-specific pieces: the request's shape, the checks after
+ * it, the read of the credential row this member holds, the liveness judgement behind the push,
+ * the writes, and the two fixed refusals the base sends on its own (`busy`, and `internal` for a
+ * frame it could not read or a failure it did not expect).
+ *
+ * The held row is read once, after the checks, and carried to the liveness judgement and the
+ * writes: the schema refuses every update and delete of an issued credential row, so the row
+ * read before the write lock is the row a read inside it would return.
  */
-export abstract class MemberRedemptionHandler<Request, Reply extends { accepted: boolean }> {
+export abstract class MemberRedemptionHandler<Request, Reply extends { accepted: boolean }, Held> {
   protected readonly partyId: string;
   private readonly admitDevice: MemberRedemptionHandlerOptions['admitDevice'];
   private readonly readTimeoutMs: number;
@@ -204,10 +208,12 @@ export abstract class MemberRedemptionHandler<Request, Reply extends { accepted:
   protected abstract isWellFormedRequest(value: unknown): value is Request;
   /** The checks after the shape that cost no database work; null to go on to the writes. */
   protected abstract checkRequest(request: Request, remotePeerId: string): Reply | null;
-  /** Is the credential the (checked) request carries still live on this member? Decides whether the holder is pushed the store (see {@link admitIfLive}). */
-  protected abstract isLive(request: Request): Promise<boolean>;
-  /** The protocol's writes under the admission, each answered by name when it fails. */
-  protected abstract redeemAdmitted(request: Request, remotePeerId: string): Promise<Reply>;
+  /** The credential row this member holds under the (checked) request's key, or null; a failed read is answered `internal`. */
+  protected abstract readHeld(request: Request): Promise<Held | null>;
+  /** Is the credential the request carries still live on this member, judged on `held` (else the bundle's copy)? Decides whether the holder is pushed the store (see {@link admitIfLive}). */
+  protected abstract isLive(request: Request, held: Held | null): Promise<boolean>;
+  /** The protocol's writes under the admission, each answered by name when it fails; `held` is {@link readHeld}'s row. */
+  protected abstract redeemAdmitted(request: Request, remotePeerId: string, held: Held | null): Promise<Reply>;
 
   /** In-flight inbound redemptions. */
   get activeCount(): number {
@@ -274,9 +280,10 @@ export abstract class MemberRedemptionHandler<Request, Reply extends { accepted:
     if (!this.isWellFormedRequest(request)) return this.malformedRefusal;
     const refused = this.checkRequest(request, remotePeerId);
     if (refused) return refused;
-    const release = await this.admitIfLive(request, remotePeerId);
+    const held = await this.readHeld(request);
+    const release = await this.admitIfLive(request, remotePeerId, held);
     try {
-      return await this.redeemAdmitted(request, remotePeerId);
+      return await this.redeemAdmitted(request, remotePeerId, held);
     } finally {
       release();
     }
@@ -299,11 +306,11 @@ export abstract class MemberRedemptionHandler<Request, Reply extends { accepted:
    * the ordinary catch-up reaches a member. Best-effort: a failed check or push is logged and
    * the writes go ahead without the holder admitted, then commit or are answered retryably.
    */
-  private async admitIfLive(request: Request, remotePeerId: string): Promise<() => void> {
+  private async admitIfLive(request: Request, remotePeerId: string, held: Held | null): Promise<() => void> {
     const notAdmitted = (): void => undefined;
     if (!this.admitDevice) return notAdmitted;
     try {
-      if (!await this.isLive(request)) {
+      if (!await this.isLive(request, held)) {
         log('%s: the credential is not live here; %s is not admitted before the write', this.label, remotePeerId);
         return notAdmitted;
       }