@serfab/cadre-core 0.11.0 → 0.13.0

package/dist/control-write-retry.js

@@ -1,6 +1,4 @@
-import debug from 'debug';
-import { unwrapError } from '@quereus/quereus';
-const log = debug('sereus:cadre:control-db');
+import { chainMessages, retryControlOperation } from './control-retry.js';
 /**
  * Bounded retry for TRANSIENT control-write failures — the classifier and loop behind
  * `ControlDatabase.lockedWithRetry`, the single funnel every local control write passes
@@ -27,7 +25,9 @@ const log = debug('sereus:cadre:control-db');
  * list must be safe for all ~19 callers.
  *
  * Lives outside `control-database.ts` so a spec can drive the classifier against real engine
- * errors without importing the whole database class.
+ * errors without importing the whole database class. The loop itself lives in
+ * `control-retry.ts`, shared with the READ policy (`control-read-retry.ts`) — this module
+ * owns the write policies: their classifiers, attempt counts, backoff and budget.
  */
 /**
  * Attempts allowed per control write: the first, plus two retries of a transiently-failed
@@ -154,8 +154,12 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED = /Failed to get super-majority: \d+\/
  * An aggregate whose details came out EMPTY (possible when `formatBatchStatuses` has no
  * batches to format) carries neither token, matches nothing here, and is not retried — an
  * unattributable failure is not a proven non-commit.
+ *
+ * Exported for the READ classifier (`control-read-retry.ts`), which reuses it verbatim: a
+ * `get` batch formats the same single-block `[block:` token, and a read can never produce
+ * the commit-phase `[blocks:` shape at all.
  */
-function isUncommittedTransactorAggregate(message) {
+export function isUncommittedTransactorAggregate(message) {
     return TRANSACTOR_AGGREGATE.test(message) && message.includes(SINGLE_BLOCK_BATCH_TOKEN);
 }
 /**
@@ -202,24 +206,6 @@ const SELF_COORDINATION_GRACE_REFUSAL = /Self-coordination blocked: grace-period
 function isSelfCoordinationGraceRefusal(message) {
     return SELF_COORDINATION_GRACE_REFUSAL.test(message);
 }
-/**
- * Every message in the failure's `cause` chain.
- *
- * `unwrapError` declares its `message` as `string`, but it follows `.cause` without checking what
- * that holds — a chain link that is not an `Error` (a stream rejected with a bare string reason,
- * an `AbortSignal.reason` that is a plain object) yields `undefined` there, and calling
- * `.includes` on it would throw a `TypeError` out of this classifier, INSIDE `retryControlWrite`'s
- * catch, replacing the real control-write failure with a confusing one. Non-strings are dropped:
- * a link nobody can read is a link that matches nothing, which is already the conservative answer.
- *
- * NOTE: a cause chain with a CYCLE would spin forever inside `unwrapError` itself. No error in
- * this repo builds one; if a hang ever localises to a control-write failure path, look there.
- */
-function chainMessages(error) {
-    return unwrapError(error)
-        .map(({ message }) => message)
-        .filter(message => typeof message === 'string');
-}
 /**
  * The error messages that mean "the cohort did not answer AND nothing committed", and nothing
  * else. The observed one-shot failure was `registerSelf()` racing a connection still forming:
@@ -260,7 +246,8 @@ const RETRIABLE_SCHEMA_INIT_MATCHERS = [
  * Did this control write fail because the cluster cohort did not ANSWER — i.e. is
  * re-presenting the SAME signed write a moment later the right response?
  *
- * Classifies by MESSAGE, walking the `cause` chain with Quereus' own {@link unwrapError} —
+ * Classifies by MESSAGE, walking the `cause` chain with the shared {@link chainMessages}
+ * (Quereus' own `unwrapError` underneath) —
  * the failure surface is not recognisable by type. The transactor and the coordinator both throw bare `Error`s, and by
  * the time one reaches `ControlDatabase` it is wrapped in a `QuereusError` (the real chain
  * is `QuereusError` → `Error` → `Error`), so the match must work at any depth. Anything
@@ -340,73 +327,15 @@ export const SCHEMA_INIT_RETRY_POLICY = {
  * so the exact messages downstream code and the degraded-cohort-member scenario assert on
  * survive. A non-retriable failure propagates from the attempt that raised it.
  */
-export async function retryControlWrite(attempt, options = {}) {
-    const attempts = Math.max(1, options.attempts ?? CONTROL_WRITE_ATTEMPTS);
-    const delays = options.delaysMs ?? CONTROL_WRITE_RETRY_DELAYS_MS;
-    const isRetriable = options.isRetriable ?? isRetriableControlWriteFailure;
-    const sleep = options.sleep ?? defaultSleep;
-    const now = options.now ?? Date.now;
-    // Empty when unlabelled, so an unlabelled line is byte-identical to what this loop
-    // logged before labels existed.
-    const tag = options.label ? ` [${options.label}]` : '';
-    const start = now();
-    let lastError;
-    let attemptsMade = 0;
-    for (let attemptNumber = 1; attemptNumber <= attempts; attemptNumber++) {
-        attemptsMade = attemptNumber;
-        try {
-            const result = await attempt();
-            if (attemptNumber > 1) {
-                log('Control write%s committed on attempt %d/%d', tag, attemptNumber, attempts);
-            }
-            return result;
-        }
-        catch (error) {
-            if (!isRetriable(error)) {
-                // The ONLY trace that this funnel saw a failure and declined it. Without it the
-                // log is silent either way, so "the classifier vetoed this one" is
-                // indistinguishable from "the retry is not wired into this path at all".
-                log('Control write%s failed non-transiently on attempt %d/%d, not retried here: %s', tag, attemptNumber, attempts, error);
-                throw error;
-            }
-            lastError = error;
-            if (attemptNumber === attempts) {
-                break;
-            }
-            const elapsed = now() - start;
-            if (elapsed >= CONTROL_WRITE_RETRY_BUDGET_MS) {
-                break;
-            }
-            const delay = jitteredDelay(delays, attemptNumber);
-            log('Control write%s failed transiently (attempt %d/%d), retrying in %d ms: %s', tag, attemptNumber, attempts, delay, error);
-            await sleep(delay);
-        }
-    }
-    log('Control write%s failed after %d/%d attempt(s): %s', tag, attemptsMade, attempts, lastError);
-    throw lastError;
-}
-/**
- * Backoff for the retry that follows attempt `attemptNumber`: the matching base delay
- * (last entry repeats), jittered ±50%, then capped at the list's largest base so no single
- * sleep exceeds it (see {@link CONTROL_WRITE_RETRY_DELAYS_MS} for why). `Math.random` is
- * fine here — the jitter only de-synchronizes concurrent retriers, nothing is derived
- * from it.
- *
- * NOTE: the cap bites on the LAST delay, whose base IS the largest, so ~half of those sleeps
- * land exactly on the cap rather than spread — de-synchronization is only partial there.
- * Harmless while retriers are a handful of party nodes whose attempts already start seconds
- * apart; if a party ever retries in a tight synchronized herd, raise the cap above the
- * largest base instead of jittering about it.
- */
-function jitteredDelay(delays, attemptNumber) {
-    if (delays.length === 0) {
-        return 0;
-    }
-    const base = delays[Math.min(attemptNumber - 1, delays.length - 1)];
-    const jittered = base * (0.5 + Math.random());
-    return Math.min(jittered, Math.max(...delays));
-}
-function defaultSleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+export function retryControlWrite(attempt, options = {}) {
+    return retryControlOperation(attempt, {
+        attempts: CONTROL_WRITE_ATTEMPTS,
+        delaysMs: CONTROL_WRITE_RETRY_DELAYS_MS,
+        budgetMs: CONTROL_WRITE_RETRY_BUDGET_MS,
+        isRetriable: isRetriableControlWriteFailure,
+        // The default prefix, named anyway: the degraded-cohort scenario asserts on
+        // `Control write [<label>] …` lines byte-for-byte.
+        logPrefix: 'Control write',
+    }, options);
 }
 //# sourceMappingURL=control-write-retry.js.map

package/dist/control-write-retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-write-retry.js","sourceRoot":"","sources":["../src/control-write-retry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"control-write-retry.js","sourceRoot":"","sources":["../src/control-write-retry.ts"],"names":[],"mappings":"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"}

package/dist/delegate-admission.d.ts

@@ -5,24 +5,26 @@
  * A strand node runs as its own libp2p instance with its own transport peerId,
  * derived from the cadre identity key + strandId (`strand-transport-key.ts`).
  * That derivation uses the member's PRIVATE seed by design, so no third party —
- * including a co-cadre relay — can recompute it. When a NAT'd member's strand
- * node tries to reserve a circuit-relay slot on a sibling's control node, the
- * relay's membership connection gater sees an unknown peerId and denies the
- * connection, which kills the reservation and fails the strand's
- * `libp2p.start()` outright.
+ * including a co-cadre relay — can recompute it: a sibling's relay sees an
+ * unknown peerId it has no way to place as a member.
  *
- * The resolution (docs/strands.md → "Relays and admission"): a party control
+ * The resolution (docs/strands.md → "Relay willingness"): a party control
  * node running a relay is party-private infrastructure — it relays for its own
  * party's nodes, including the extra transport identities its members' strand
- * nodes run as, and for nobody else. The mechanism is a **member-announced
- * delegate grant**: before a member's control node starts a strand node, it
- * tells its siblings (over the already-authenticated `/sereus/strand-addr/1.0.0`
- * RPC) the derived peerId that strand node will use, and the receiver holds a
- * short-lived, in-memory admission grant for exactly that peerId. The grant is
- * consulted ONLY by the connection-level gate
- * (`CadreNode.admitInboundControlConnection`); the fail-closed per-stream gate
- * (`authorizeInboundControlStream`) never honors it, so a delegate gets the
- * connection (all a circuit-relay `hop` reservation needs) and nothing more.
+ * nodes run as. The mechanism is a **member-announced delegate grant**: before
+ * a member's control node starts a strand node, it tells its siblings (over the
+ * already-authenticated `/sereus/strand-addr/1.0.0` RPC) the derived peerId
+ * that strand node will use, and the receiver holds a short-lived, in-memory
+ * admission grant for exactly that peerId. The grant is consulted by the
+ * connection-level gate (`CadreNode.admitInboundControlConnection`) and by the
+ * relay-reservation admission (`CadreNode.admitControlRelayReservation`) — a
+ * granted delegate is admitted outright, never drawing on the small
+ * unauthorized-reservation budget that unplaced peers share
+ * (`membership-connection-gater.ts` → "The relay-reservation seam") and never
+ * racing its not-reserving connection deadline. The fail-closed per-stream gate
+ * (`authorizeInboundControlStream`) never honors a grant, so a delegate gets
+ * the connection and its reservation (all a circuit-relay `hop` needs) and
+ * nothing more.
  *
  * A grant is a delegation of trust to an already-trusted member: the receiver
  * cannot verify that the announced peerId really is the member's strand node,

package/dist/delegate-admission.js

@@ -5,24 +5,26 @@
  * A strand node runs as its own libp2p instance with its own transport peerId,
  * derived from the cadre identity key + strandId (`strand-transport-key.ts`).
  * That derivation uses the member's PRIVATE seed by design, so no third party —
- * including a co-cadre relay — can recompute it. When a NAT'd member's strand
- * node tries to reserve a circuit-relay slot on a sibling's control node, the
- * relay's membership connection gater sees an unknown peerId and denies the
- * connection, which kills the reservation and fails the strand's
- * `libp2p.start()` outright.
+ * including a co-cadre relay — can recompute it: a sibling's relay sees an
+ * unknown peerId it has no way to place as a member.
  *
- * The resolution (docs/strands.md → "Relays and admission"): a party control
+ * The resolution (docs/strands.md → "Relay willingness"): a party control
  * node running a relay is party-private infrastructure — it relays for its own
  * party's nodes, including the extra transport identities its members' strand
- * nodes run as, and for nobody else. The mechanism is a **member-announced
- * delegate grant**: before a member's control node starts a strand node, it
- * tells its siblings (over the already-authenticated `/sereus/strand-addr/1.0.0`
- * RPC) the derived peerId that strand node will use, and the receiver holds a
- * short-lived, in-memory admission grant for exactly that peerId. The grant is
- * consulted ONLY by the connection-level gate
- * (`CadreNode.admitInboundControlConnection`); the fail-closed per-stream gate
- * (`authorizeInboundControlStream`) never honors it, so a delegate gets the
- * connection (all a circuit-relay `hop` reservation needs) and nothing more.
+ * nodes run as. The mechanism is a **member-announced delegate grant**: before
+ * a member's control node starts a strand node, it tells its siblings (over the
+ * already-authenticated `/sereus/strand-addr/1.0.0` RPC) the derived peerId
+ * that strand node will use, and the receiver holds a short-lived, in-memory
+ * admission grant for exactly that peerId. The grant is consulted by the
+ * connection-level gate (`CadreNode.admitInboundControlConnection`) and by the
+ * relay-reservation admission (`CadreNode.admitControlRelayReservation`) — a
+ * granted delegate is admitted outright, never drawing on the small
+ * unauthorized-reservation budget that unplaced peers share
+ * (`membership-connection-gater.ts` → "The relay-reservation seam") and never
+ * racing its not-reserving connection deadline. The fail-closed per-stream gate
+ * (`authorizeInboundControlStream`) never honors a grant, so a delegate gets
+ * the connection and its reservation (all a circuit-relay `hop` needs) and
+ * nothing more.
  *
  * A grant is a delegation of trust to an already-trusted member: the receiver
  * cannot verify that the announced peerId really is the member's strand node,

package/dist/delegate-admission.js.map

@@ -1 +1 @@
-{"version":3,"file":"delegate-admission.js","sourceRoot":"","sources":["../src/delegate-admission.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"delegate-admission.js","sourceRoot":"","sources":["../src/delegate-admission.ts"],"names":[],"mappings":"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"}

package/dist/enrolled-machine-store-file.d.ts

@@ -0,0 +1,13 @@
+import type { EnrolledMachineStore } from './enrolled-machine-store.js';
+/**
+ * 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 declare const FileEnrolledMachineStore: {
+    /** Load (or cold-start) the party's last recorded machine count from a file in `dir`. */
+    open(dir: string, partyId: string): Promise<EnrolledMachineStore>;
+};

package/dist/enrolled-machine-store-file.js

@@ -0,0 +1,41 @@
+/**
+ * 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';
+/** 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, partyId) {
+        return PersistentEnrolledMachineStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+    }
+};
+//# sourceMappingURL=enrolled-machine-store-file.js.map

package/dist/enrolled-machine-store-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrolled-machine-store-file.js","sourceRoot":"","sources":["../src/enrolled-machine-store-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAG7E,qFAAqF;AACrF,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACvC,yFAAyF;IACzF,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,OAAe;QACtC,OAAO,8BAA8B,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IACnG,CAAC;CACD,CAAC"}

package/dist/enrolled-machine-store.d.ts

@@ -0,0 +1,81 @@
+import type { DurableSlot } from './node-local-snapshot.js';
+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 declare class MemoryEnrolledMachineStore implements EnrolledMachineStore {
+    readonly partyId: string;
+    private current;
+    constructor(partyId: string);
+    count(): number | undefined;
+    record(count: number): Promise<void>;
+}
+/**
+ * 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 declare class PersistentEnrolledMachineStore implements EnrolledMachineStore {
+    private readonly slot;
+    readonly partyId: string;
+    /** Serialises persists so the last count recorded is the last one written. */
+    private writeChain;
+    /** Last count accepted, whether or not it has reached the slot yet. */
+    private current;
+    /** Last count believed to BE in the slot; drives the unchanged-write skip. */
+    private persisted;
+    private constructor();
+    /** Load (or cold-start) the party's last recorded machine count from `slot`. */
+    static open(slot: DurableSlot, partyId: string): Promise<PersistentEnrolledMachineStore>;
+    count(): number | undefined;
+    /**
+     * 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>;
+    /**
+     * 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 persistCurrent;
+}