@serfab/cadre-core 1.3.0 → 1.5.0

package/README.md

@@ -236,9 +236,11 @@ A **scope key** is what the factory receives. It is the strand id for each stran
 which holds one party's own records and must not be shared between parties. Every key is
 opaque and already safe as a file, directory or database name (always within
 `[A-Za-z0-9._-]`): use it verbatim, do not parse it. `isControlStorageScope(scope)` tells
-the two kinds apart. Caveat, until `bug-strand-scope-key-charset-unenforced` lands: the
-charset is enforced for the control key but only *conventional* for a strand id, which
-reaches the factory verbatim even when the strand row replicated in from another node.
+the two kinds apart. The control key holds the charset by base64url encoding; a strand
+id holds it by check — `assertStrandScopeKey` runs on every strand launch, so a strand
+whose row replicated in from another node with an unusable id is refused rather than
+handed to the factory, and on `publishStrand`, so this node never writes such an id into
+the party's control database to begin with.
 
 Available storage implementations:
 | Package | Environment | Description |

package/dist/cadre-node.d.ts

@@ -279,8 +279,10 @@ export declare class CadreNode implements SAppIdLookup {
      * dead entry behind; recovery today is a fresh invitation.
      *
      * NOTE: entries are kept for the node's lifetime, including across a
-     * {@link stopStrand} — a stopped strand may be rediscovered by the watcher and must
-     * still get its seed. Each strand's list is capped at `MAX_STRAND_ADDRS`, but the
+     * {@link stopStrand} — a stopped strand may be claimed again with {@link addStrand}
+     * (the watcher itself will not re-offer it: the stop suppresses the id for the rest of
+     * the session) and must still get its seed. Each strand's list is capped at
+     * `MAX_STRAND_ADDRS`, but the
      * number of KEYS is bounded only by the strands this node has ever formed as an
      * initiator (not by time); if a node ever forms strands at scale, evict on
      * `unpublishStrand` or cap the map.
@@ -306,8 +308,10 @@ export declare class CadreNode implements SAppIdLookup {
      * (`strand-membership-reconciler.ts`, wired via `StartStrandConfig.pendingMembershipInvite`
      * in {@link launchStrand}): it deletes the entry once the invitation is redeemed, burned
      * against an already-seated member, or found dead (expired / cancelled / consumed
-     * elsewhere / the strand sealed). Until the strand is actually launched here the entry
-     * just waits.
+     * elsewhere / the strand sealed) — naming the invitation it settled, so a re-formation
+     * that replaced the entry meanwhile keeps its fresh one
+     * ({@link unstageMembershipInvite}). Until the strand is actually launched here the entry
+     * just waits; once launched, staging notifies the manager, which re-arms a finished loop.
      *
      * NOTE: entries live for the node's lifetime (one small pair per formed closed
      * strand), the same unbounded-keys tripwire {@link crossPartyStrandAddrs} documents —
@@ -732,6 +736,12 @@ export declare class CadreNode implements SAppIdLookup {
      * derivation from it (`db-p2p` namespaces all of the node's protocol ids as
      * `/optimystic/<networkName>/...`), so the node options and the block-transfer
      * protocol prefix the control backfill dials can never drift apart.
+     *
+     * NOTE: the party id goes in UNENCODED here, unlike in `controlStorageScope`. Safe
+     * today because a party id is locally configured rather than replicated in, and both
+     * ends of a connection derive this string identically — an odd party id yields an odd
+     * but consistent protocol id, not a mismatch or an escaped name. If a party id ever
+     * arrives from the network, encode it here as the storage scope key already does.
      */
     private controlNetworkName;
     /**
@@ -1349,9 +1359,14 @@ export declare class CadreNode implements SAppIdLookup {
      * {@link SeedBootstrapService} this node builds — `applySeed`'s owner dials and
      * `dialInvite`.
      *
-     * See {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} for why a peer's dial is
-     * bounded as a whole, and {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}
-     * for why each address is bounded as well.
+     * See `peer-dial.ts`'s `DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS` for why a peer's dial is
+     * bounded as a whole, and `DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS` for why each
+     * address is bounded as well.
+     *
+     * Both are DERIVED from `network.linkRoundTripMs` rather than fixed, because the slowest
+     * address either has to cover is a relayed dial and that costs a fixed number of exchanges —
+     * `link-budget.ts` has the counts. A host's explicit `controlCohort` values still win, so a
+     * test that drives dead addresses on purpose keeps the duration it chose.
      */
     private controlDialBudget;
     /**
@@ -1862,17 +1877,17 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * A rejected call leaves nothing running but DOES leave the sApp config
      * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
-     * automatic relaunch need it. That background relaunch covers only a strand the
-     * WATCHER launched: it forgets a row whose `onStrandAdded` threw and re-attempts it
-     * on a later poll (each failure re-emitting `strand:error`) until it succeeds. A
-     * strand claimed here after it was DISCOVERED gets no such retry — the watcher
-     * already recorded it in its `knownStrands` when it offered it as
-     * `strand:discovered`, and no later poll re-offers a strand it knows. This call has
-     * also already dropped it from {@link getDiscoveredStrands}, so a failed claim
-     * leaves the strand dormant until the caller retries or the node restarts (see
-     * `backlog/bug-discovered-strand-lost-when-claim-fails`).
-     * {@link detachStrand} (reached via {@link stopStrand}) is what abandons a strand
-     * for good.
+     * automatic relaunch need it. A failed launch here hands the strand back to that
+     * relaunch — `StrandWatcher.forgetStrand` drops the id from the watcher's
+     * `knownStrands` and records the backoff, so a later poll re-attempts it on the same
+     * `pollInterval * 2^(failures-1)` ladder a watcher-driven failure gets. Because the
+     * config stays registered, the retry takes `handleStrandAdded`'s auto-launch branch:
+     * what the app sees is `strand:error` per failed retry and `strand:started` when one
+     * succeeds, never a second `strand:discovered`. {@link detachStrand} (reached via
+     * {@link stopStrand}) is what abandons a strand for good, and its stop suppresses the
+     * strand in the watcher so this retry cannot resurrect it — a call to THIS method lifts
+     * that suppression again, since an explicit claim is a deliberate reversal of the
+     * deliberate stop.
      */
     addStrand(config: StrandConfig): Promise<StrandInstance>;
     /**
@@ -1945,7 +1960,8 @@ export declare class CadreNode implements SAppIdLookup {
      * @returns The live `Strand` row — the one just inserted, or the matching one already
      *   there. A closed strand's caller should carry THIS row's `MemberPrivateKey` forward:
      *   on a repeat it is the stored key, not the argument.
-     * @throws if the node is not started, exposes no owner signing key, the id is blank, a
+     * @throws if the node is not started, exposes no owner signing key, the id is blank or
+     *   unusable as a storage scope key (`InvalidStrandIdError` — see `storage-scope.ts`), a
      *   row with the same id holds different content, or the control DB rejects the
      *   (unauthorized) insert.
      */
@@ -2372,8 +2388,10 @@ export declare class CadreNode implements SAppIdLookup {
      * caller runs the drive regardless).
      *
      * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
-     * timeouts (10 s each: dial by peer id, then by addr) before the 10 s drive even
-     * starts, so one failed re-drive can hold the supervisor `driving` for ~30 s.
+     * timeouts (10 s each: dial by peer id, then by addr) before the reservation drive even
+     * starts, so one failed re-drive holds the supervisor `driving` for those 20 s plus the
+     * drive's own deadline — 28 s at the default declared link round trip, and longer on a host
+     * that declared a slower one (`link-budget.ts`).
      * Bounded and harmless while the relay is unreachable anyway; if recovery
      * latency after a relay comes back ever matters, skip the announce when the
      * control node holds no connection to the relay (the drive's own dial fails
@@ -2465,11 +2483,11 @@ export declare class CadreNode implements SAppIdLookup {
      * Stop a strand on THIS node only: untrack it from hibernation, drop its sApp config,
      * stop the local instance, and emit `strand:stopped`. The shared `Strand` row is left
      * intact, so on the next node RESTART the strand is rediscovered and surfaces as
-     * `strand:discovered` again — not on the next watcher poll, which never re-offers a
-     * strand it has already seen (`StrandWatcher.knownStrands` retains the id for the life
-     * of the process). The stop also drops the strand from {@link getDiscoveredStrands},
-     * so a drain cannot undo a deliberate stop. Party-wide removal is
-     * {@link unpublishStrand}.
+     * `strand:discovered` again — but never again in THIS session: the stop suppresses the
+     * id in the watcher (`StrandWatcher.suppressStrand`) and drops it from
+     * {@link getDiscoveredStrands}, so neither a later poll nor a drain can undo a
+     * deliberate stop. Only an explicit {@link addStrand} does, which is the caller
+     * reversing its own decision. Party-wide removal is {@link unpublishStrand}.
      */
     stopStrand(strandId: string): Promise<void>;
     /**
@@ -2490,6 +2508,10 @@ export declare class CadreNode implements SAppIdLookup {
      * readings are the intended one: `handleStrandRemoved` arrives because the control row
      * is gone, and an explicit {@link stopStrand} is a deliberate abandonment — neither
      * strand may be re-offered to a later `getDiscoveredStrands()` drain.
+     *
+     * The watcher-level suppression that makes a stop permanent is deliberately NOT here,
+     * only in {@link stopStrand}: the two callers diverge on it. A vanished control row
+     * that reappears is a fresh strand and must be offered again.
      */
     private detachStrand;
     /**
@@ -2589,13 +2611,15 @@ export declare class CadreNode implements SAppIdLookup {
      * local), and only then does it reach out. Everything above in {@link start}
      * has completed by the time this runs.
      *
-     * BUDGET: the supervisor's first attempt — `relay-reservation.ts`'s
-     * `DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, 10 s — is what `start()` waits on — deliberately the module default rather
-     * than a boot-specific one. A healthy dial-plus-reserve is sub-second even over
-     * a WAN, so 10 s is slack for a slow link; going much longer would make a dead
-     * relay indistinguishable from a hung start, and much shorter would fail nodes
-     * on links that were merely slow. The retries carry on in the background after
-     * this resolves, exactly as they do for a {@link reserveRelays} caller.
+     * BUDGET: the supervisor's first attempt is what `start()` waits on — deliberately the drive's
+     * ordinary deadline rather than a boot-specific one. That deadline is now COUNTED, four link
+     * round trips at the declared `network.linkRoundTripMs` (8 s at its default, where it was a
+     * fixed 10 s): a healthy dial-plus-reserve is sub-second even over a WAN, so this is slack for
+     * a slow link, while going much longer would make a dead relay indistinguishable from a hung
+     * start and much shorter would fail nodes on links that were merely slow. A host that declares
+     * a slower link lengthens it without touching this path — `link-budget.ts`. The retries carry
+     * on in the background after this resolves, exactly as they do for a {@link reserveRelays}
+     * caller.
      *
      * `network.requireRelay === false` softens only the outcome below: a first
      * attempt that lands no `/p2p-circuit` address is logged instead of thrown, and
@@ -3044,7 +3068,11 @@ export declare class CadreNode implements SAppIdLookup {
      *    an intact control DB) and mints + persists a fresh one otherwise. The invitation
      *    will admit THIS key's public half as the `Strand.Member`.
      * 2. Stage the invitation in {@link pendingMembershipInvites} for the strand
-     *    bring-up flow (`strand-node-binds-member-peer`) to redeem via `consumeInvite`.
+     *    bring-up flow (`strand-node-binds-member-peer`) to redeem via `consumeInvite`,
+     *    and tell the instance manager, which re-arms an already-finished membership
+     *    reconciler so a RE-formation against a launched strand is attempted at once — the
+     *    removed-party case, where the loop finished long before the removal. A strand not
+     *    launched here yet has no loop to re-arm, and its bring-up finds the entry.
      *
      * Throws — failing the whole {@link formStrand} — when the identity cannot be
      * persisted: a joiner "joined" without a persistable identity could never become a
@@ -3054,6 +3082,14 @@ export declare class CadreNode implements SAppIdLookup {
      * rejected) and redeeming a FRESH invitation.
      */
     private adoptFormationMembershipInvite;
+    /**
+     * The reconciler's half of the {@link pendingMembershipInvites} seam: drop `settled`
+     * (spent, burned, or dead) only while it is still the staged entry. A re-formation
+     * replaces the entry between a pass's read and its settle, and the fresh invitation it
+     * staged is the one the re-armed loop is about to redeem — deleting it here would lose
+     * it silently, the very outcome the re-arm exists to prevent.
+     */
+    private unstageMembershipInvite;
     /**
      * The pending single-use membership invitation a closed-strand formation carried back
      * for `strandId`, or `undefined` when none is staged — the seam the strand bring-up