@serfab/cadre-core 0.12.0 → 0.13.0

package/src/control-database.ts

@@ -17,6 +17,7 @@ import { retryControlWrite, SCHEMA_INIT_RETRY_POLICY } from './control-write-ret
 import type { ControlWriteRetryOptions } from './control-write-retry.js';
 import { retryControlRead } from './control-read-retry.js';
 import type { ControlReadRetryOptions } from './control-read-retry.js';
+import { chainMessages } from './control-retry.js';
 
 export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
 
@@ -293,6 +294,38 @@ const GUARDED_KEY_COLUMN: Readonly<Record<RevocableTable, GuardedKeyColumn>> = {
   DeviceToken: 'PeerId',
 };
 
+/**
+ * The rejection a second insert of an already-seated strand id produces, as the optimystic
+ * vtab words it (`uniqueConstraintMessage`, qualified by table name only — no schema
+ * prefix, matching `test/control-constraint-helpers.ts`'s `expectUniqueViolation`).
+ *
+ * `Strand.StampId` is unique too, but a fresh stamp is minted per insert attempt, so only
+ * the primary key can collide on a repeat publish. Matching the column explicitly keeps
+ * any OTHER uniqueness failure out of the idempotency branch.
+ */
+const STRAND_ID_CONFLICT = /UNIQUE constraint failed: Strand\.Id\b/i;
+
+/**
+ * Did this write fail because the strand id is already seated?
+ *
+ * {@link CadreNode.publishStrand} uses this to tell "my own earlier publish already
+ * landed" (re-read, and no-op when the row matches) apart from every other rejection —
+ * an unauthorized signer, a retired stamp — which must keep surfacing.
+ *
+ * Matched by TEXT, not by type: the typed engine error does not survive the trip out of
+ * optimystic (same constraint the retry classifiers in `control-write-retry.ts` document).
+ * Fails CLOSED — a rewording upstream turns the idempotent branch back into the raw
+ * uniqueness error the caller saw before, never into a silent overwrite. The
+ * `publish-strand.spec.ts` repeat-publish cases assert against the live engine error, so a
+ * reword reddens there.
+ */
+export function isStrandIdConflict(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return chainMessages(error).some(message => STRAND_ID_CONFLICT.test(message));
+}
+
 /**
  * Guarded tables a node may reap locally once their tombstone has committed — the
  * tables whose `AuthorizedDelete` carries the REAP branch (see the constraint comment on
@@ -690,11 +723,12 @@ export class ControlDatabase {
   async queryStrands(): Promise<StrandRow[]> {
     this.ensureInitialized();
     const results: StrandRow[] = [];
-    for (const row of await this.readRows('select Id, MemberPrivateKey, Type from CadreControl.Strand', undefined, 'strands')) {
+    for (const row of await this.readRows('select Id, MemberPrivateKey, Type, FounderOwnerKey from CadreControl.Strand', undefined, 'strands')) {
       results.push({
         Id: row.Id as string,
         MemberPrivateKey: row.MemberPrivateKey as string | null,
         Type: row.Type as 'o' | 'c',
+        FounderOwnerKey: row.FounderOwnerKey as string | null,
       });
     }
     return results;
@@ -709,7 +743,7 @@ export class ControlDatabase {
   async queryStrand(strandId: string): Promise<StrandRow | null> {
     this.ensureInitialized();
     for (const row of await this.readRows(
-      'select Id, MemberPrivateKey, Type from CadreControl.Strand where Id = ?',
+      'select Id, MemberPrivateKey, Type, FounderOwnerKey from CadreControl.Strand where Id = ?',
       [strandId],
       'strand'
     )) {
@@ -717,6 +751,7 @@ export class ControlDatabase {
         Id: row.Id as string,
         MemberPrivateKey: row.MemberPrivateKey as string | null,
         Type: row.Type as 'o' | 'c',
+        FounderOwnerKey: row.FounderOwnerKey as string | null,
       };
     }
     return null;
@@ -1144,6 +1179,10 @@ export class ControlDatabase {
   /**
    * Insert a strand into the control database using an owner signature.
    *
+   * Fails with a `Strand.Id` uniqueness violation when the id is already seated — the
+   * caller decides whether that is a duplicate of its own earlier write (idempotent) or a
+   * genuine conflict; see {@link isStrandIdConflict} and `CadreNode.publishStrand`.
+   *
    * The owner signs the canonical row-bound authorization message (see
    * {@link buildAuthorizationMessage}) — NOT a bare stamp — so the signature is bound to
    * this strand's contents and cannot be transplanted onto an attacker-chosen row. The
@@ -1171,16 +1210,19 @@ export class ControlDatabase {
     const stampId = generateStampId(peerId);
 
     // Field order MUST match the schema's Strand `AuthorizedInsert` verify:
-    // Id, Type, MemberPrivateKey ('' when null), StampId.
+    // Id, Type, MemberPrivateKey ('' when null), StampId. FounderOwnerKey is
+    // deliberately NOT in the digest — the schema binds it by equality to the
+    // verified context.OwnerKey instead (see the constraint's comment).
     const message = buildAuthorizationMessage('CadreControl.Strand', 'add', [strandId, type, memberPrivateKey ?? '', stampId]);
     const signature = signMessage(message);
 
     // StampId is a real, unique column (single-use anti-replay), no longer a context value.
+    // FounderOwnerKey must equal the signing owner or the constraint rejects the row.
     await this.execWrite(`
-      insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
+      insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId, FounderOwnerKey)
         with context OwnerKey = ?, Signature = ?
-        values (?, ?, ?, ?)
-    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId], 'strand-insert');
+        values (?, ?, ?, ?, ?)
+    `, [ownerKey, signature, strandId, type, memberPrivateKey ?? null, stampId, ownerKey], 'strand-insert');
 
     log('Strand inserted: %s', strandId);
   }
@@ -2235,11 +2277,13 @@ export class ControlDatabase {
       await this.inTransaction('redemption', async () => {
         // 1. Strand row — authorised by the FormationUsage branch (no owner sig),
         //    still carrying a fresh unique StampId for the anti-replay column.
-        //    Hard-coded open + keyless: the consent branch admits no other shape.
+        //    Hard-coded open + keyless + explicit null FounderOwnerKey: the
+        //    consent branch admits no other shape (no signature means no
+        //    trustworthy founder machine to record — see the schema's NOTE).
         await this.db!.exec(`
-          insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId)
+          insert into CadreControl.Strand (Id, Type, MemberPrivateKey, StampId, FounderOwnerKey)
             with context OwnerKey = null, Signature = null
-            values (?, 'o', null, ?)
+            values (?, 'o', null, ?, null)
         `, [strandId, strandStampId]);
 
         // 2. FormationUsage row — authorised by the matching FormationInvite, and

package/src/control-schema.ts

@@ -142,6 +142,17 @@ declare schema CadreControl {
         Id text primary key,    -- UUID
         MemberPrivateKey text null unique,   -- Our private key as a member of this strand
         Type text, -- Types: 'o' = Open, 'c' = Closed -- Open can still control writes in the sApp, but only Closed controls reads
+        FounderOwnerKey text null,  -- ed25519 (base64url) owner key of the MACHINE that published this row
+                                    -- (== insert context.OwnerKey; in the reference model each machine's
+                                    -- owner key is the key behind its PeerId, so this names the founding
+                                    -- machine — the one machine that runs the strand's one-time founder
+                                    -- bootstrap). cadre-core derives "am I the founder?" at launch by
+                                    -- comparing it to the node's own owner key (cadre-node.ts
+                                    -- launchStrand). Null on a consent-seated strand — the consent branch
+                                    -- of AuthorizedInsert carries no signature, so there is no
+                                    -- trustworthy signer to record (see the NOTE on that branch below).
+                                    -- Provenance, not content: cadre-node.ts strandRowMismatches
+                                    -- deliberately excludes it from the identical-content comparison.
         StampId text not null unique,   -- single-use authorization nonce (anti-replay).
                                         -- \`unique\` holds over LIVE rows only; a removed row's stamp is retired
                                         -- permanently into Revocation (NotRevoked below).
@@ -172,8 +183,16 @@ declare schema CadreControl {
         -- Mirrors OwnerKey.NoUpdate / FormationInvite.Immutable.
         constraint NoUpdate check on update (false),
         constraint AuthorizedInsert check on insert (
-            -- Authorized by an owner signing over THIS row (Id, Type, MemberPrivateKey, StampId); single-use via unique StampId
-            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.Strand', 'add', new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
+            -- Authorized by an owner signing over THIS row (Id, Type, MemberPrivateKey, StampId); single-use via unique StampId.
+            -- FounderOwnerKey persists WHO published the row, so the founding machine can later
+            -- recognise its own strand (founder derivation, cadre-node.ts launchStrand). The
+            -- equality pins the stored column to the VERIFIED signer — same shape as
+            -- CadrePeer.VouchOwner — so a writer cannot record a founder it is not. Deliberately
+            -- NOT added to the signed digest: the equality already binds it to the signature's
+            -- context.OwnerKey, and widening the digest would churn every existing
+            -- insertStrand field-order contract for nothing.
+            (exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.Strand', 'add', new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
+                and new.FounderOwnerKey = context.OwnerKey)
 
                 -- or authorized WITHOUT a signature by a redemption record naming THIS EXACT ROW: a
                 -- FormationUsage row carrying both this strand's Id and its one-off StampId
@@ -240,6 +259,15 @@ declare schema CadreControl {
                 or (
                     new.Type = 'o'
                     and new.MemberPrivateKey is null
+                    -- NOTE: a consent-seated strand records NO founder machine — this branch
+                    -- carries no signature, so there is no trustworthy signer to persist.
+                    -- Consequence: the restart-before-founding orphan shape (a relaunch cannot
+                    -- derive founder-ness from the row) persists for consent-formed strands
+                    -- only; the responder that provisions one must keep passing an explicit
+                    -- founder flag at launch. Revisit if consent-formed strands ever hit the
+                    -- empty-Header symptom in practice: FormationUsage names the redeeming
+                    -- peer (PeerKey), which is the candidate derivation source.
+                    and new.FounderOwnerKey is null
                     and exists (
                         select 1 from FormationUsage FU
                             where FU.StrandId = new.Id

package/src/enrolled-machine-store-file.ts

@@ -0,0 +1,43 @@
+/**
+ * Node-only file-backed {@link EnrolledMachineStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated count of
+ * machines this party had enrolled the last time this node looked.
+ *
+ * Nothing but the file itself lives here: the envelope, the cold-start-on-anything
+ * load policy (deliberately NOT the throw-on-unreadable policy its two sibling
+ * records use — see the `enrolled-machine-store.ts` module comment) and the
+ * serialised writes are cross-platform in `PersistentEnrolledMachineStore`, and the
+ * file is a `FileDurableSlot`. This module exists only so the `node:fs` edge stays
+ * out of the package's cross-platform default entry (`./index.js`) — import it from
+ * the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileEnrolledMachineStore } from '@serfab/cadre-core/enrolled-machine-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the `node:fs`
+ * edge never reaches a bundler that cannot satisfy it (same isolation pattern as
+ * `bootstrap-peer-store-file.ts` / `trusted-owner-store-file.ts` / `key-store-file.ts`).
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentEnrolledMachineStore } from './enrolled-machine-store.js';
+import type { EnrolledMachineStore } from './enrolled-machine-store.js';
+
+/** Base name of the store file: `<dir>/enrolled-machines.<encoded partyId>.json`. */
+const SLOT_NAME = 'enrolled-machines';
+
+/**
+ * File-backed {@link EnrolledMachineStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it. An absent, corrupt,
+ * wrong-party, junk-valued **or unreadable** file is a cold start (`count()` is
+ * `undefined`, the node declares no repair yardstick and runs at the base control
+ * policy) — `open` never rejects, unlike the sibling stores' file backends. That
+ * divergence and its reasoning live on `enrolled-machine-store.ts`.
+ */
+export const FileEnrolledMachineStore = {
+	/** Load (or cold-start) the party's last recorded machine count from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<EnrolledMachineStore> {
+		return PersistentEnrolledMachineStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};

package/src/enrolled-machine-store.ts

@@ -0,0 +1,280 @@
+/**
+ * Node-local, NON-replicated record of how many machines this party had enrolled
+ * the last time this node looked — the block-repair corroboration yardstick the
+ * CONTROL network declares when its libp2p node is built.
+ *
+ * ## Why the number has to be remembered rather than read
+ *
+ * `resolveRepairYardstick` (in `@serfab/quereus-plugin-sereus`'s `cluster-size.ts`
+ * — read it first; the arithmetic and both clamps are explained there and are not
+ * repeated here) derives the yardstick from the machines that SERVE the network being
+ * configured. For the CONTROL network that is the machines enrolled in the party, and
+ * exactly so: every enrolled machine runs the control node by construction. (It is NOT
+ * the right number for a strand, which runs on a subset — see
+ * `StartStrandConfig.servingMachines`. This store is control-network-only, and that
+ * scope is a safety property, not an accident.) Optimystic freezes a network's
+ * `clusterPolicy` when its libp2p node is built and offers no runtime setter, so the
+ * number has to be known at construction time.
+ *
+ * The control node cannot read it when it needs it. `CadreNode.buildControlNodeOptions`
+ * runs inside `start()` BEFORE `createControlNode()`, which is before the
+ * `ControlDatabase` holding the `CadrePeer` rows exists — so at the one moment the
+ * number is needed, nothing can answer. That deadlock is why the control network
+ * declared no yardstick at all and ran at `CONTROL_CLUSTER_POLICY`'s
+ * `assumedClusterSize` of 2.
+ *
+ * This store breaks it the only way a chicken-and-egg is broken: by remembering
+ * across the restart. `CadreNode.refreshAuthorizedControlPeers` records the count
+ * every time membership is recomputed; `CadreNode.start()` reads it back before the
+ * control node is built. A node therefore declares what it last knew, and a party
+ * that grows applies the larger number on each node's NEXT launch. Raising the
+ * yardstick is the safe direction and a node still holding the old value is running
+ * at exactly today's behaviour, so the next natural restart is soon enough — there
+ * is deliberately no forced rebuild.
+ *
+ * ## Why this is NOT a `NodeLocalSnapshot` like its two siblings
+ *
+ * The trusted-owner anchor (`trusted-owner-store.ts`) and the cold-start
+ * bootstrap-peer store (`bootstrap-peer-store.ts`) are the same `{ version,
+ * partyId, ... }` envelope over a {@link DurableSlot} this record is, and this
+ * module is deliberately symmetrical with them — same injected-backend shape, same
+ * `Memory*` / `Persistent*` / `File*` split, same party scoping. It does NOT share
+ * their `NodeLocalSnapshot` machinery, for two reasons:
+ *
+ *  - **Shape.** `NodeLocalSnapshot` is a `key -> entry` map with no delete. This
+ *    record is one integer that must be able to go DOWN after a machine is removed.
+ *  - **Load policy — the important one.** `NodeLocalSnapshot.open` THROWS when the
+ *    slot is present but unreadable. That is right for the anchor (a record that
+ *    cannot be read in full is not a trust anchor) and right for the peer store (a
+ *    failed read reported as absent would let the next snapshot write destroy a
+ *    stranded node's only way home). It is WRONG here. Nothing in this record is
+ *    trust-bearing, it holds nothing that is not recomputed the moment the control
+ *    database is up, and refusing to start a node over an unreadable *repair hint*
+ *    is strictly worse than declaring today's 2. So every unreadable, unparsable,
+ *    foreign-party or junk slot LOGS and COLD-STARTS, yielding `undefined`, which
+ *    declares nothing, which is byte-for-byte today's behaviour.
+ *
+ * Do not "unify" the three modules by routing this one through `NodeLocalSnapshot`:
+ * that would quietly import the throw, and turn an unreadable hint into a node that
+ * will not start.
+ *
+ * NOTE: writes are serialised in-process only, the same caveat `NodeLocalSnapshot`
+ * carries. Two processes (or two browser tabs) sharing ONE slot for ONE party each
+ * write their own view and the loser's count is lost. Two same-origin tabs of
+ * `reference-app-web` do exactly that — its slot is one key of a shared IndexedDB
+ * database, the same last-writer-wins caveat its `node-local-slots.ts` already
+ * records for the other two records. Harmless here, unlike there: this value is one
+ * integer both tabs re-derive from the same membership rows on their next refresh,
+ * so the views reconverge rather than losing an entry nobody rewrites.
+ */
+import debug from 'debug';
+import type { DurableSlot } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:enrolled-machine-store');
+
+/** Envelope version. Guards future migrations; an unknown version cold-starts. */
+const ENVELOPE_VERSION = 1;
+
+/** Envelope property holding the count. */
+const PAYLOAD_KEY = 'enrolledMachines';
+
+export interface EnrolledMachineStore {
+	/** Party this store is scoped to. */
+	readonly partyId: string;
+
+	/**
+	 * Machines last recorded for this party, or `undefined` when nothing usable was
+	 * ever recorded — a brand-new node, or a slot that could not be read. Callers
+	 * pass this straight to `controlClusterPolicy`, whose `undefined` branch returns
+	 * the frozen base policy unchanged, so "this node does not know" and "this node
+	 * has never run" are the same declaration: none.
+	 */
+	count(): number | undefined;
+
+	/**
+	 * Record the current count. Reflected by {@link count} SYNCHRONOUSLY; the
+	 * returned promise resolves once the persist attempt has settled.
+	 *
+	 * **Never rejects.** Its sole caller is
+	 * `CadreNode.refreshAuthorizedControlPeers`, whose contract is never-rejects and
+	 * which leaves the promise un-awaited (`void`) — so a rejection here would
+	 * surface as an unhandled rejection in the embedder's process, over a hint that
+	 * re-lands on the next refresh anyway. A failed persist is LOGGED, and the
+	 * in-memory count stays correct for this session.
+	 *
+	 * A count that is not a positive integer is a caller bug: it is logged and
+	 * IGNORED rather than persisted, so a degenerate value can never reach the slot
+	 * and be read back as a declaration nobody chose.
+	 */
+	record(count: number): Promise<void>;
+}
+
+/**
+ * Ephemeral in-memory store — the default when no store is injected via
+ * `CadreNodeConfig.enrolledMachines`. A node using this cold-starts on every
+ * launch: `count()` is `undefined` at `start()`, so its control node declares
+ * nothing and runs at today's behaviour, exactly as before this record existed.
+ */
+export class MemoryEnrolledMachineStore implements EnrolledMachineStore {
+	private current: number | undefined;
+
+	constructor(readonly partyId: string) {}
+
+	count(): number | undefined {
+		return this.current;
+	}
+
+	async record(count: number): Promise<void> {
+		const accepted = asMachineCount(count);
+		if (accepted === undefined) {
+			log('refusing to record a non-positive-integer count %o for party %s', count, this.partyId);
+			return;
+		}
+		this.current = accepted;
+	}
+}
+
+/**
+ * Durable {@link EnrolledMachineStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileEnrolledMachineStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load policy is the module comment's: every failure
+ * mode cold-starts, and `open` never rejects.
+ */
+export class PersistentEnrolledMachineStore implements EnrolledMachineStore {
+	/** Serialises persists so the last count recorded is the last one written. */
+	private writeChain: Promise<void> = Promise.resolve();
+	/** Last count accepted, whether or not it has reached the slot yet. */
+	private current: number | undefined;
+	/** Last count believed to BE in the slot; drives the unchanged-write skip. */
+	private persisted: number | undefined;
+
+	private constructor(
+		private readonly slot: DurableSlot,
+		readonly partyId: string,
+		loaded: number | undefined
+	) {
+		this.current = loaded;
+		this.persisted = loaded;
+	}
+
+	/** Load (or cold-start) the party's last recorded machine count from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentEnrolledMachineStore> {
+		return new PersistentEnrolledMachineStore(slot, partyId, await loadCount(slot, partyId));
+	}
+
+	count(): number | undefined {
+		return this.current;
+	}
+
+	/**
+	 * 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
+	 * {@link current}, so a write that FAILED is retried by the next refresh instead
+	 * of being suppressed as "unchanged".
+	 */
+	record(count: number): Promise<void> {
+		const accepted = asMachineCount(count);
+		if (accepted === undefined) {
+			log('refusing to record a non-positive-integer count %o for party %s', count, this.partyId);
+			return Promise.resolve();
+		}
+		this.current = accepted;
+		if (this.persisted === accepted) {
+			return Promise.resolve();
+		}
+		this.writeChain = this.writeChain.then(() => this.persistCurrent());
+		return this.writeChain;
+	}
+
+	/**
+	 * Write whatever {@link current} holds when this link of the chain runs — so a
+	 * burst of records collapses into one write of the latest value — and never
+	 * throw (see {@link EnrolledMachineStore.record}).
+	 */
+	private async persistCurrent(): Promise<void> {
+		const pending = this.current;
+		if (pending === undefined || pending === this.persisted) {
+			return;
+		}
+		const envelope = {
+			version: ENVELOPE_VERSION,
+			partyId: this.partyId,
+			[PAYLOAD_KEY]: pending
+		};
+		try {
+			await this.slot.save(JSON.stringify(envelope, null, '\t'));
+			this.persisted = pending;
+			log('recorded %d enrolled machine(s) for party %s', pending, this.partyId);
+		} catch (error) {
+			log(
+				'persisting %d enrolled machine(s) for party %s failed (in-memory count stands, retried on the next refresh): %o',
+				pending, this.partyId, error
+			);
+		}
+	}
+}
+
+/**
+ * A usable machine count, or `undefined`. Anything that is not a positive integer
+ * is unknown rather than coerced — `'3'`, `0`, `-1`, `2.5`, `null` and a missing key
+ * all cold-start. Coercing here would be the beginning of a parser, and Optimystic
+ * itself treats a degenerate declaration as absent, so a rounded value would be a
+ * number nobody chose.
+ */
+function asMachineCount(value: unknown): number | undefined {
+	return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : undefined;
+}
+
+/**
+ * Read the slot into the initial count. EVERY failure — unreadable slot, unparsable
+ * JSON, wrong envelope version, foreign `partyId`, junk payload — logs and returns
+ * `undefined` (see the module comment for why this record, unlike its two siblings,
+ * must not throw on an unreadable slot).
+ */
+async function loadCount(slot: DurableSlot, partyId: string): Promise<number | undefined> {
+	let text: string | undefined;
+	try {
+		text = await slot.load();
+	} catch (error) {
+		// The deliberate divergence from `NodeLocalSnapshot.open`, which throws here.
+		log('slot for party %s is present but unreadable (cold start — this node declares no yardstick): %o', partyId, error);
+		return undefined;
+	}
+	if (text === undefined) {
+		return undefined;
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		log('corrupt slot for party %s (cold start): %o', partyId, error);
+		return undefined;
+	}
+
+	if (!isRecord(parsed) || parsed.version !== ENVELOPE_VERSION || parsed.partyId !== partyId) {
+		// A non-string partyId cannot equal the requested one, so this covers both a
+		// malformed envelope and a slot reused for another party.
+		log('slot for party %s has an unknown shape or a foreign partyId (cold start)', partyId);
+		return undefined;
+	}
+
+	const count = asMachineCount(parsed[PAYLOAD_KEY]);
+	if (count === undefined) {
+		log('slot for party %s holds an unusable %s value %o (cold start)', partyId, PAYLOAD_KEY, parsed[PAYLOAD_KEY]);
+		return undefined;
+	}
+	log('loaded %d enrolled machine(s) for party %s', count, partyId);
+	return count;
+}
+
+/** A plain JSON object. Arrays excluded: an array envelope is not an envelope. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/file-durable-slot.ts

@@ -5,9 +5,11 @@
  * parties without cross-party leakage.
  *
  * This is the whole platform-specific part of the file-backed node-local
- * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`); the
- * load policy, envelope and write chain are cross-platform in
- * `node-local-snapshot.ts`. Like its two importers, this module imports
+ * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`,
+ * `enrolled-machine-store-file.ts`); the load policy, envelope and write chain
+ * are cross-platform — in `node-local-snapshot.ts` for the first two, and in
+ * `enrolled-machine-store.ts` for the third, which deliberately does not share
+ * that machinery. Like its three importers, this module imports
  * `node:fs/promises`, so it is kept OUT of the package's cross-platform
  * default entry and is not itself an exported subpath.
  */

package/src/index.ts

@@ -94,6 +94,20 @@ export {
   type BootstrapPeerEntry
 } from './bootstrap-peer-store.js';
 
+// Node-local enrolled-machine count: the machines this party had enrolled the
+// last time this node looked, remembered across restarts so the CONTROL node can
+// declare a block-repair yardstick at bring-up — which is before the database
+// holding the membership rows exists. Same cross-platform split as the two
+// records above; Node-only file backend behind the subpath
+// '@serfab/cadre-core/enrolled-machine-store-file'. Its load policy deliberately
+// DIVERGES from theirs (an unreadable slot cold-starts rather than throwing) —
+// see the module comment before unifying the three.
+export {
+  MemoryEnrolledMachineStore,
+  PersistentEnrolledMachineStore,
+  type EnrolledMachineStore
+} from './enrolled-machine-store.js';
+
 // Strand database
 export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
 
@@ -112,17 +126,36 @@ export {
   getStrandStoragePath
 } from './strand-instance-manager.js';
 
-// Strand peer-join block catch-up (push this strand's own blocks to each newly
-// connected strand peer, so a late joiner physically holds pre-join blocks).
+// Peer-join block catch-up (push this network's own blocks to each newly
+// connected peer, so a late joiner physically holds pre-join blocks). Shared
+// by the strand networks (ungated) and the control network (membership-gated).
 export {
-  StrandBackfill,
-  DEFAULT_STRAND_BACKFILL,
+  PeerJoinBackfill,
+  DEFAULT_PEER_JOIN_BACKFILL,
   MAX_BLOCK_MESSAGE_BYTES,
-  type StrandBackfillConfig,
-  type StrandBackfillDeps,
-  type StrandBackfillResult,
-  type StrandBackfillPushClient
-} from './strand-backfill.js';
+  type PeerJoinBackfillConfig,
+  type PeerJoinBackfillDeps,
+  type PeerJoinBackfillResult,
+  type PeerJoinBackfillPushClient
+} from './peer-join-backfill.js';
+
+// Closed-strand revoked-peer enforcement (deny the network nodes of removed
+// members at the stream and connection layers, and hang up the sessions they
+// already hold — see the module doc for the settled deny-list design, the
+// teardown seam, and the fail directions).
+export {
+  StrandRevocationEnforcer,
+  createRevocationConnectionGater,
+  readStrandRevocationRows,
+  DEFAULT_REVOCATION_POLL_INTERVAL_MS,
+  type StrandRevocationEnforcementConfig,
+  type StrandRevocationEnforcerDeps,
+  type StrandRevocationRows,
+  type StrandMemberPeerBinding,
+  type StrandRevocationJudge,
+  type StrandRevocationNetwork,
+  type RevocationRefreshScheduler
+} from './strand-revocation-enforcer.js';
 
 // Hibernation
 export {
@@ -363,6 +396,7 @@ export {
   FormationListener,
   dialFormation,
   isValidResponderCreatesResult,
+  sanitizeStrandAddrs,
   FORMATION_PROTOCOL,
   type FormationParty,
   type FormationContactMessage,
@@ -372,6 +406,7 @@ export {
   type FormationDbConnectionInfo,
   type FormationListenerOptions,
   type FormationDialOptions,
+  type FormationDialResult,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
 
@@ -400,7 +435,14 @@ export {
 // Thrown out of `CadreNode.start()` when a `network.relayAddrs` reservation does
 // not land on its first attempt — the fail-fast posture of that config field now
 // that the control node reserves AFTER control-database bring-up (relay-addrs.ts).
-export { RelayReservationFailedError, RELAY_SEARCH_LISTEN_ADDR } from './relay-addrs.js';
+// `UnbindableListenAddressError` is the same posture for the OTHER half of the listen
+// config: a `network.listenAddrs` entry whose transport the node will not have refuses
+// start instead of being silently dropped by libp2p's transport manager.
+export {
+  RelayReservationFailedError,
+  UnbindableListenAddressError,
+  RELAY_SEARCH_LISTEN_ADDR
+} from './relay-addrs.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/membership-connection-gater.ts

@@ -367,7 +367,11 @@ export class UnauthorizedReservationBudget {
  * dialer sees its "open" connection close moments later.
  *
  * Control node only: strand cohort nodes legitimately connect cross-party
- * peers, so `CadreNode` threads the raw configured gater to them unchanged.
+ * peers, so cadre membership never gates them. An OPEN strand's node receives
+ * the raw configured gater unchanged; a CLOSED strand's node composes its own
+ * revoked-peer denial onto it instead — a deny-list on positive revocation
+ * evidence, not this module's membership admission — see
+ * `strand-revocation-enforcer.ts`.
  */
 export function createMembershipConnectionGater(
   policy: InboundAdmissionPolicy,
@@ -440,9 +444,11 @@ export function createMembershipConnectionGater(
  * fail-open outcome) if it has not settled in time — see
  * {@link ADMISSION_DECISION_TIMEOUT_MS} for why an unbounded await is not safe
  * on the connection hook. The timer is always cleared so a decided call never
- * holds the event loop open.
+ * holds the event loop open. Exported for the strand revoked-peer gate
+ * (`strand-revocation-enforcer.ts`), which bounds its connection hooks with the
+ * same fail-open contract.
  */
-async function decideWithinDeadline<T>(
+export async function decideWithinDeadline<T>(
   decide: () => Promise<T> | T,
   fallback: T,
   timeoutMs: number,