@serfab/cadre-core 1.6.0 → 1.8.0

package/src/control-read-retry.ts

@@ -14,7 +14,7 @@ import { isUncommittedTransactorAggregate } from './control-write-retry.js';
  * was absorbed). This module gives reads the same bounded re-presentation with a SHORTER
  * deadline and a NARROWER failure set, because the tightest caller deadline over a control
  * read is the inbound admission gate's 2 s fail-open timeout
- * (`ADMISSION_DECISION_TIMEOUT_MS`, `membership-connection-gater.ts`) — a read budget that
+ * (`ADMISSION_DECISION_TIMEOUT_MS`, `link-budget.ts`) — a read budget that
  * does not fit inside it with headroom spends its retries after the gate has already
  * admitted.
  *
@@ -67,18 +67,20 @@ export const CONTROL_READ_RETRY_DELAYS_MS: readonly number[] = [100, 400];
  * 2 s only because each stays well under it. Do not raise these numbers without
  * re-checking against `ADMISSION_DECISION_TIMEOUT_MS`.
  *
- * NOTE: the obligation runs the other way too, and the number that dominates this budget is
- * declared in another package. One attempt whose cohort consult finds a silent peer costs
- * `clusterPolicy.cohortQueryTimeoutMs`, which sereus declares at 5000 ms
- * (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`) for relayed phone
- * links — more than three times this budget, so such an attempt is never retried and the
- * admission gate above it has already fail-opened. That is a widened cost of a deliberate
- * choice, not a hole (the stream gates still decide), and the whole ladder of cadre-core
- * deadlines against Optimystic's is audited by
- * `backlog/debt-cadre-deadlines-sized-against-old-optimystic-bounds`. What this budget still
- * buys is the failure it was built for: the ~25 ms transactor read-phase aggregate off a
- * stream still forming, which retries twice well inside 1500 ms.
+ * It cuts the loop off by design, so it does not grow with the link or with the number that
+ * dominates a slow attempt: an attempt whose cohort consult finds a silent peer costs
+ * `clusterPolicy.cohortQueryTimeoutMs`, two link round trips at the declared link
+ * (`cohortReadDeadlineMs` in `link-budget.ts`, 7 000 ms at the default declaration; the plugin's
+ * `COHORT_READ_DEADLINE_MS` is the same number). That is more than four times this budget, so
+ * such an attempt is never retried and the caller gets its error unchanged. That is deliberate:
+ * the caller this budget is sized for, the admission gate, has
+ * already taken its fail-open answer by then, and a retry would only spend time after it. What
+ * the budget still buys is the fast failures it was built for: the ~25 ms transactor read-phase
+ * aggregate off a stream still forming, and a `cohort-unreachable` read during bring-up, which
+ * fails fast because there is no connection to ask. Both retry twice well inside 1500 ms. See
+ * `docs/cadre-consistency.md` → "Deadlines Over Optimystic's Reads and Commits".
  */
+// eslint-disable-next-line no-restricted-syntax -- cuts off by design: a slow attempt is not retried, because the admission gate this budget is sized for has already failed open by then; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
 export const CONTROL_READ_RETRY_BUDGET_MS = 1_500;
 
 /**

package/src/control-schema.ts

@@ -365,6 +365,65 @@ declare schema CadreControl {
         )
     ) with context (OwnerKey text, Signature text);
 
+    -- A strand THIS party joined from ANOTHER party. The founding party's control database
+    -- holds its Strand row, so without this table only the machine that joined would know of
+    -- it. Every machine of the party reads it (the strand watcher offers each row like a
+    -- Strand row), so a replica host keeps a copy and the party's other machines can attach.
+    -- A separate table rather than a Strand row with a provenance marker: Strand means "this
+    -- party's own strand" to every reader of it (founder derivation, FormationUsage.StrandExists,
+    -- unpublish, the consent branch of Strand.AuthorizedInsert), and each would need a
+    -- provenance check. MemberPrivateKey is the closed strand's shared read secret the
+    -- formation delivered — replicated in plaintext to every machine the party owns, under the
+    -- same accepted risk as Strand.MemberPrivateKey (docs/strands.md → "Closed-Strand Member
+    -- Key Handling"). Unlike that column it is not held only here: the founding party and
+    -- every member hold it, so a removed row is recoverable by re-forming, which is why this
+    -- table (unlike Strand) carries a REAP branch.
+    table JoinedStrand (
+        Id text primary key,            -- the joined strand's id (the founder's Strand.Id)
+        Type text not null,             -- 'o' | 'c', as Strand.Type
+        MemberPrivateKey text null,     -- closed strand's shared read secret; null for open
+        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).
+        -- The approval that seated a removed row can never re-seat it. Same rationale as
+        -- OwnerKey.NotRevoked, stated in full there.
+        constraint NotRevoked check on insert (
+            not exists (select 1 from Revocation R where R.TableName = 'JoinedStrand' and R.StampId = new.StampId)
+        ),
+        -- A delete must file its correctly named tombstone in the same transaction. Same
+        -- rationale as StrandPartyKey.RevocationRecorded.
+        constraint RevocationRecorded check on delete (
+            exists (select 1 from Revocation R where R.TableName = 'JoinedStrand' and R.StampId = old.StampId and R.RowKey = old.Id)
+        ),
+        -- Insert + delete only: neither Authorized rule below covers update, so an in-place
+        -- rewrite would swap the read secret unsigned. Mirrors StrandPartyKey.NoUpdate.
+        constraint NoUpdate check on update (false),
+        -- Readers cast Type to 'o' | 'c' (ControlDatabase.queryJoinedStrands).
+        constraint KnownType check (new.Type = 'o' or new.Type = 'c'),
+        -- An open strand has no read gate, so no read secret. Same rule as Strand.MemberKeyClosedOnly.
+        constraint MemberKeyClosedOnly check (new.MemberPrivateKey is null or new.Type = 'c'),
+        constraint AuthorizedInsert check on insert (
+            -- Owners authorize by signing over THIS row (Id, Type, MemberPrivateKey, StampId),
+            -- MemberPrivateKey signing as '' when null, so a captured approval can only reproduce
+            -- the exact secret it approved. Owner-signed, deliberately NOT self-signable by an
+            -- enrolled CadrePeer: every always-on machine of the party downloads the strands this
+            -- table names, so a non-owner machine could otherwise make them all host an arbitrary
+            -- strand. A machine that is not an owner keeps its joins machine-local.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.JoinedStrand', 'add', new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
+        ),
+        constraint AuthorizedDelete check on delete (
+            -- 'remove'-tagged digest over the STORED row (Id, StampId), so the add approval can
+            -- never be replayed as a removal.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.JoinedStrand', 'remove', old.Id, old.StampId), context.Signature, A.Key, 'ed25519'))
+
+                -- or REAP: a COMMITTED tombstone already retires this exact row incarnation.
+                -- Why committed.* and why the stamp is bound: stated in full on
+                -- CadrePeer.AuthorizedDelete. Allowed here, unlike Strand / StrandPartyKey,
+                -- because MemberPrivateKey is recoverable (see the table comment).
+                or exists (select 1 from committed.Revocation R where R.TableName = 'JoinedStrand' and R.RowKey = old.Id and R.StampId = old.StampId)
+        )
+    ) with context (OwnerKey text, Signature text);
+
     -- A peer (node) that is part of the cadre, carrying a self-published,
     -- freshness-stamped, self-signed address record (see PeerAddressRecord in cadre-core).
     -- The row IS the peer-address record: a resolver reads it, re-verifies Sig against
@@ -785,8 +844,8 @@ declare schema CadreControl {
     -- thing to suspect.
     index FormationUsageByToken on FormationUsage (Token);
 
-    -- Append-only retirement record for the one-off StampId nonces of removed OwnerKey /
-    -- CadrePeer / ValidationKey / Strand rows. Without it a removal was undoable: the add
+    -- Append-only retirement record for the one-off StampId nonces of removed rows of every
+    -- guarded table (listed on TableName below). Without it a removal was undoable: the add
     -- approval is a signature over
     -- (row key, stamp) that never expires, and deleting the row freed the stamp, so anyone who
     -- kept a copy of the approval could resurrect the row.
@@ -815,10 +874,12 @@ declare schema CadreControl {
     -- its own guarded TableName, 'Revocation' is not one, and ControlDatabase.queryRevocations
     -- skips the marker, so nothing reaps or re-issues it.
     table Revocation (
-        TableName text,             -- 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'DeviceToken',
-                                    -- or 'Revocation' for the ledger marker only (all confined by RowIsGone below)
+        TableName text,             -- 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' |
+                                    -- 'JoinedStrand' | 'DeviceToken', or 'Revocation' for the ledger marker only
+                                    -- (all confined by RowIsGone below)
         RowKey text not null,       -- primary key of the removed row: OwnerKey.Key / ValidationKey.Key /
-                                    -- CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id / StrandPartyKey.Id
+                                    -- CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id / StrandPartyKey.Id /
+                                    -- JoinedStrand.Id
                                     -- Every guarded table's RevocationRecorded CHECK requires the
                                     -- accompanying tombstone to carry the removed row's key here, so
                                     -- a REMOVAL cannot file a misnamed tombstone. A tombstone with no
@@ -869,6 +930,7 @@ declare schema CadreControl {
                 or (new.TableName = 'ValidationKey' and not exists (select 1 from ValidationKey V where V.StampId = new.StampId))
                 or (new.TableName = 'Strand' and not exists (select 1 from Strand S where S.StampId = new.StampId))
                 or (new.TableName = 'StrandPartyKey' and not exists (select 1 from StrandPartyKey K where K.StampId = new.StampId))
+                or (new.TableName = 'JoinedStrand' and not exists (select 1 from JoinedStrand J where J.StampId = new.StampId))
                 or (new.TableName = 'DeviceToken' and not exists (select 1 from DeviceToken D where D.StampId = new.StampId))
                 or (new.TableName = 'Revocation' and new.RowKey = 'ledger' and new.StampId = 'opened')
         ),

package/src/control-stream.ts

@@ -13,7 +13,8 @@
  * deadline, write one frame, half-close, read one response, reset the stream on
  * any failure — so that shape lives here too, as {@link withDeadline} +
  * {@link exchangeFrame}; each protocol supplies only its dial options, its
- * request object, and its response decoder.
+ * request object, and its response decoder. The receiver's half — one reply
+ * frame, then close — is {@link replyAndClose}.
  *
  * Dependency-free by design: it imports nothing from the protocol modules, so
  * the import graph stays acyclic (`control-stream` ← `seed-bootstrap` ←
@@ -22,6 +23,10 @@
  * `decodeLengthPrefixedFrame` guard.
  */
 
+import debug from 'debug';
+
+const log = debug('sereus:cadre:control-stream');
+
 /**
  * Minimal libp2p 3.x stream surface: AsyncIterable for reads, `send()` for
  * writes, `close()` to half-close the write end (EOF), `abort()` to reset.
@@ -41,6 +46,25 @@ export function writeFrame(stream: ControlStream, obj: unknown): void {
   stream.send(body);
 }
 
+/**
+ * Receiver side: write one reply frame and close the stream, best-effort on both and never
+ * throwing. A peer that has already gone away cannot be answered, and nothing the receiver
+ * decided depends on whether it heard. The close is what releases the sender, which reads the
+ * reply to end-of-stream ({@link exchangeFrame}).
+ */
+export async function replyAndClose(stream: ControlStream, reply: unknown, label: string): Promise<void> {
+  try {
+    writeFrame(stream, reply);
+  } catch (error) {
+    log('%s: failed to write reply: %o', label, error);
+  }
+  try {
+    await stream.close();
+  } catch (error) {
+    log('%s: failed to close stream: %o', label, error);
+  }
+}
+
 /**
  * Reject if `op` does not settle within `ms`. On timeout, invoke `onTimeout`
  * before rejecting — a hook for releasing whatever the op is parked on. A

package/src/control-write-retry.ts

@@ -77,11 +77,21 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * This budget — not the attempt count — is what makes the policy safe to sit under every
  * control write. A transient failure (stream reset while a connection is still forming)
  * surfaces in well under a second, so it is retried and the loop adds at most ~2.2 s. A
- * genuinely silent cohort member fails at ~20 s (two 10 s `ClusterClient` response-deadline
- * attempts, measured in `control-write-degraded-cohort-member.integration.ts`), which
+ * genuinely silent cohort member fails at ~21 s per pend round (two `ClusterClient`
+ * response-deadline attempts, 10.5 s each at the default declared link; a two-round write
+ * measured 42.2 s in `control-write-degraded-cohort-member.integration.ts`), which
  * already exceeds this budget when attempt 1 returns — so that case is surfaced immediately
  * and retry adds ZERO latency to the case where it cannot help.
  *
+ * It cuts the loop off by design, so it does not grow with the link: its job is to end the
+ * retries of slow attempts, and the caller gets the last attempt's error unchanged. An attempt
+ * whose read phase consulted a silent peer ends at about one per-peer read deadline
+ * (`cohortReadDeadlineMs` in `link-budget.ts`: 7 s at the default declared link, 5 s before it
+ * was derived, 1 s at Optimystic's own default), so it still gets one retry inside this budget
+ * where it once got two; an attempt that runs into the `ClusterClient` response deadline
+ * (10.5 s at the default declared link) still gets none. See `docs/cadre-consistency.md` →
+ * "Deadlines Over Optimystic's Reads and Commits".
+ *
  * NOTE: a failed commit attempt now also pays a cancel discharge before its error returns
  * (optimystic `TransactorSource.transact`'s catch, added by upstream
  * `1-a-failed-attempt-must-discharge-its-own-pend`) — bounded by six rounds and
@@ -93,6 +103,7 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * to do: if that case ever starts failing with `failed after 2/3 attempt(s)`, the cancel
  * discharge is where the time went.
  */
+// eslint-disable-next-line no-restricted-syntax -- cuts off by design: it ends the retries of slow attempts rather than waiting them out; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
 export const CONTROL_WRITE_RETRY_BUDGET_MS = 10_000;
 
 /**

package/src/delegate-admission.ts

@@ -35,7 +35,7 @@
  * The receiver side is {@link DelegateAdmissionStore}. The announcer side keeps
  * its own throttle state (a "last announced at" map that `CadreNode` owns) and
  * decides from it, per reconcile pass, which relays are due a re-announce —
- * {@link dueRelayAnnounces} and {@link pruneStoppedStrandAnnounces} are that
+ * {@link dueRelayAnnounces} and {@link prunePeerStrandKeys} are that
  * decision, pure and testable, kept here beside the TTL they are derived from.
  */
 
@@ -71,14 +71,20 @@ interface DelegateGrant {
 }
 
 /**
- * Composite map key for the per-(peer, strand) state on both sides: the
- * receiver's replace-per-(announcer, strand) grant, and the announcer's
- * per-(target, strand) throttle timestamp.
+ * Composite map key for per-(peer, strand) state: the receiver's
+ * replace-per-(announcer, strand) grant, the announcer's per-(target, strand)
+ * throttle timestamp, and `CadreNode`'s per-(sibling, strand) strand-addr ask
+ * due time.
  */
 export function peerStrandKey(peerId: string, strandId: string): string {
   return `${peerId}\n${strandId}`;
 }
 
+/** The `peerId` half of a {@link peerStrandKey} (a peer id never contains a newline). */
+function peerIdOfKey(key: string): string {
+  return key.slice(0, key.indexOf('\n'));
+}
+
 /** The `strandId` half of a {@link peerStrandKey}. */
 function strandIdOfKey(key: string): string {
   return key.slice(key.indexOf('\n') + 1);
@@ -233,17 +239,21 @@ export function dueRelayAnnounces(
 }
 
 /**
- * Drop `announceAt` entries whose strand is no longer running — a stopped
- * strand needs no refresh, and without this the map grows for the node's
- * lifetime. Mutates in place.
+ * Drop the entries of a {@link peerStrandKey}-keyed map whose strand is no longer
+ * running, and — when `livePeerIds` is given — whose peer is not among them. A
+ * stopped strand needs no refresh, a departed peer is owed a fresh start when it
+ * returns, and without this the map grows for the node's lifetime. Mutates in
+ * place.
  */
-export function pruneStoppedStrandAnnounces(
-  announceAt: Map<string, number>,
-  runningStrandIds: ReadonlySet<string>
+export function prunePeerStrandKeys(
+  byKey: Map<string, number>,
+  runningStrandIds: ReadonlySet<string>,
+  livePeerIds?: ReadonlySet<string>
 ): void {
-  for (const key of announceAt.keys()) {
-    if (!runningStrandIds.has(strandIdOfKey(key))) {
-      announceAt.delete(key);
+  for (const key of byKey.keys()) {
+    const peerGone = livePeerIds !== undefined && !livePeerIds.has(peerIdOfKey(key));
+    if (peerGone || !runningStrandIds.has(strandIdOfKey(key))) {
+      byKey.delete(key);
     }
   }
 }

package/src/diagnostics/connection-path.ts

@@ -3,13 +3,6 @@
  * (`/p2p-circuit`) vs direct, tag its transport, and summarise counts plus a
  * "stuck on relay" condition.
  *
- * This is the **canonical** implementation. The web reference app keeps a
- * deliberate, documented duplicate at
- * `packages/reference-app-web/src/lib/connection-path.ts` (it does not depend on
- * `@serfab/cadre-core`). Keep the function signatures and classification table
- * identical across both copies so a future shared micro-package would be a
- * drop-in.
- *
  * The whole signal is a pure function over `node.getConnections()` + a settle
  * window + `Date.now()`. A connection's path is derivable from its `remoteAddr`
  * multiaddr string alone — no I/O, no events, no stateful observer.