@serfab/cadre-core 0.9.0 → 0.11.0

package/dist/control-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-schema.js","sourceRoot":"","sources":["../src/control-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAkNH,CAAC"}
+{"version":3,"file":"control-schema.js","sourceRoot":"","sources":["../src/control-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAqxBH,CAAC"}

package/dist/control-stream.d.ts

@@ -9,6 +9,12 @@
  * abort-on-timeout read-to-EOF helper so a misbehaving peer that opens a stream
  * and never half-closes its write end cannot pin a receiver forever.
  *
+ * The sender side of all three protocols is the same exchange — dial under a
+ * 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.
+ *
  * Dependency-free by design: it imports nothing from the protocol modules, so
  * the import graph stays acyclic (`control-stream` ← `seed-bootstrap` ←
  * `strand-wake-protocol`). In particular it returns RAW bytes from
@@ -28,12 +34,40 @@ export interface ControlStream extends AsyncIterable<Uint8Array> {
 export declare function writeFrame(stream: ControlStream, obj: unknown): void;
 /**
  * Reject if `op` does not settle within `ms`. On timeout, invoke `onTimeout`
- * (used by the sender to abort the in-flight dial/stream so it does not leak)
- * before rejecting. A throwing `onTimeout` is swallowed so it cannot mask the
- * timeout rejection. The rejection message is exactly `<label> timed out after
- * <ms>ms`, so callers fold any domain prefix into `label`.
+ * before rejecting — a hook for releasing whatever the op is parked on. A
+ * throwing `onTimeout` is swallowed so it cannot mask the timeout rejection. The
+ * rejection message is exactly `<label> timed out after <ms>ms`, so callers fold
+ * any domain prefix into `label`.
+ *
+ * Senders want {@link withDeadline}, which wires `onTimeout` to an
+ * `AbortController` so the in-flight dial/stream is cancelled rather than leaked.
  */
 export declare function withTimeout<T>(ms: number, label: string, op: () => Promise<T>, onTimeout?: () => void): Promise<T>;
+/**
+ * Run `op` under a `withTimeout` deadline that also *cancels* it: the signal
+ * handed to `op` is aborted immediately before the timeout rejection, so a
+ * sender can pass it to `dialProtocol` (cancelling an in-flight connect) and to
+ * {@link exchangeFrame} (resetting a live stream) instead of leaking either.
+ */
+export declare function withDeadline<T>(ms: number, label: string, op: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * Send one request frame on an open stream, half-close the write end, and read
+ * the response through `readResponse`.
+ *
+ * `signal` is the caller's deadline (see {@link withDeadline}): an abort resets
+ * the stream, releasing the otherwise unbounded response read. If the deadline
+ * already fired while the stream was being dialed, the freshly-opened stream is
+ * reset here rather than left dangling. Every reset — deadline, response-decode
+ * failure, or a `readResponse` that rejects without aborting (the size-cap path
+ * of {@link readStreamToEnd}) — goes through one idempotent `abort`, so the
+ * deadline listener and the error path cannot double-reset a stream.
+ *
+ * `readResponse` owns its own read bound, which is a backstop rather than the
+ * primary one: the caller's deadline started first and therefore fires first.
+ * It matters only when an abort does not release the read (e.g. a stream double
+ * whose `abort()` is a no-op).
+ */
+export declare function exchangeFrame<T>(stream: ControlStream, signal: AbortSignal, request: unknown, readResponse: (stream: ControlStream) => Promise<T>, abortMessage: string): Promise<T>;
 /**
  * Read a stream to EOF, capped at `maxBytes`, bounded by `timeoutMs`, returning
  * the assembled bytes (the caller decodes via `decodeLengthPrefixedFrame`).

package/dist/control-stream.js

@@ -9,6 +9,12 @@
  * abort-on-timeout read-to-EOF helper so a misbehaving peer that opens a stream
  * and never half-closes its write end cannot pin a receiver forever.
  *
+ * The sender side of all three protocols is the same exchange — dial under a
+ * 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.
+ *
  * Dependency-free by design: it imports nothing from the protocol modules, so
  * the import graph stays acyclic (`control-stream` ← `seed-bootstrap` ←
  * `strand-wake-protocol`). In particular it returns RAW bytes from
@@ -25,10 +31,13 @@ export function writeFrame(stream, obj) {
 }
 /**
  * Reject if `op` does not settle within `ms`. On timeout, invoke `onTimeout`
- * (used by the sender to abort the in-flight dial/stream so it does not leak)
- * before rejecting. A throwing `onTimeout` is swallowed so it cannot mask the
- * timeout rejection. The rejection message is exactly `<label> timed out after
- * <ms>ms`, so callers fold any domain prefix into `label`.
+ * before rejecting — a hook for releasing whatever the op is parked on. A
+ * throwing `onTimeout` is swallowed so it cannot mask the timeout rejection. The
+ * rejection message is exactly `<label> timed out after <ms>ms`, so callers fold
+ * any domain prefix into `label`.
+ *
+ * Senders want {@link withDeadline}, which wires `onTimeout` to an
+ * `AbortController` so the in-flight dial/stream is cancelled rather than leaked.
  */
 export function withTimeout(ms, label, op, onTimeout) {
     return new Promise((resolve, reject) => {
@@ -44,6 +53,63 @@ export function withTimeout(ms, label, op, onTimeout) {
         op().then(resolve, reject).finally(() => clearTimeout(timer));
     });
 }
+/**
+ * Run `op` under a `withTimeout` deadline that also *cancels* it: the signal
+ * handed to `op` is aborted immediately before the timeout rejection, so a
+ * sender can pass it to `dialProtocol` (cancelling an in-flight connect) and to
+ * {@link exchangeFrame} (resetting a live stream) instead of leaking either.
+ */
+export function withDeadline(ms, label, op) {
+    const controller = new AbortController();
+    return withTimeout(ms, label, () => op(controller.signal), () => controller.abort());
+}
+/**
+ * Send one request frame on an open stream, half-close the write end, and read
+ * the response through `readResponse`.
+ *
+ * `signal` is the caller's deadline (see {@link withDeadline}): an abort resets
+ * the stream, releasing the otherwise unbounded response read. If the deadline
+ * already fired while the stream was being dialed, the freshly-opened stream is
+ * reset here rather than left dangling. Every reset — deadline, response-decode
+ * failure, or a `readResponse` that rejects without aborting (the size-cap path
+ * of {@link readStreamToEnd}) — goes through one idempotent `abort`, so the
+ * deadline listener and the error path cannot double-reset a stream.
+ *
+ * `readResponse` owns its own read bound, which is a backstop rather than the
+ * primary one: the caller's deadline started first and therefore fires first.
+ * It matters only when an abort does not release the read (e.g. a stream double
+ * whose `abort()` is a no-op).
+ */
+export async function exchangeFrame(stream, signal, request, readResponse, abortMessage) {
+    let reset = false;
+    const resetStream = (err) => {
+        if (reset)
+            return;
+        reset = true;
+        stream.abort(err);
+    };
+    const abortErr = new Error(abortMessage);
+    const onAbort = () => resetStream(abortErr);
+    if (signal.aborted) {
+        onAbort();
+        throw abortErr;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        writeFrame(stream, request);
+        // close() half-closes the write end (EOF) while the read end stays open for
+        // the response — the libp2p 3.x request/response pattern.
+        await stream.close();
+        return await readResponse(stream);
+    }
+    catch (err) {
+        resetStream(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
 /** Normalize a libp2p chunk (Uint8Array or Uint8ArrayList) to a flat Uint8Array. */
 function toBytes(chunk) {
     return chunk instanceof Uint8Array ? chunk : chunk.subarray();

package/dist/control-stream.js.map

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

package/dist/control-write-retry.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Bounded retry for TRANSIENT control-write failures — the classifier and loop behind
+ * `ControlDatabase.lockedWithRetry`, the single funnel every local control write passes
+ * through.
+ *
+ * Why this exists: the control database replicates every block to the whole party, so a
+ * three-machine party commits control writes unanimously (`ceil(3 × 0.75) = 3` approvals) —
+ * and no `superMajorityThreshold` can lower that bar without violating Optimystic's
+ * partition-safety condition at the shipped admission fraction (the arithmetic lives in
+ * `docs/architecture.md` → "Replication cluster size"). Cadre therefore accepts unanimity
+ * and absorbs the transient half of its cost here: a write that failed because the cohort
+ * did not ANSWER (a stream reset mid-connection-formation, zero approvals) is re-presented
+ * a moment later, which the degraded-cohort-member scenario measured as safe (a failed
+ * write rolls back, nothing half-commits) and effective (the next write commits in ~1 s).
+ *
+ * A write somebody actually REJECTED is never retried — re-presenting it would re-present
+ * a spent signature against a cohort that already said no.
+ *
+ * TWO policies ship from here, and the split is deliberate: the default
+ * ({@link isRetriableControlWriteFailure}, {@link CONTROL_WRITE_ATTEMPTS}) sits under every
+ * control write, and {@link SCHEMA_INIT_RETRY_POLICY} is opted into by
+ * `ControlDatabase.loadSchema` alone. The widened one absorbs one extra failure class whose
+ * re-run safety holds for schema DDL and NOT for writes in general; anything added to the default
+ * 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.
+ */
+/**
+ * Attempts allowed per control write: the first, plus two retries of a transiently-failed
+ * cluster commit. Bounded so a genuinely unreachable cohort terminates in the transactor's
+ * own error rather than spinning; two retries covers the observed failure (a stream still
+ * forming when the write fired) with margin.
+ */
+export declare const CONTROL_WRITE_ATTEMPTS = 3;
+/**
+ * Attempts allowed for {@link SCHEMA_INIT_RETRY_POLICY}, the one call site that also absorbs a
+ * self-coordination refusal.
+ *
+ * Two more than {@link CONTROL_WRITE_ATTEMPTS} because what this retry buys is wall-clock for a
+ * cold-starting node's bootstrap dials to land, and because the refusal is cheap to re-provoke
+ * relative to a cluster round-trip: `findCoordinator` already spends its own bounded wait before
+ * raising (3 attempts, 500 ms apart, `db-p2p/src/libp2p-key-network.ts` ~422) and then decides
+ * LOCALLY that it may not elect itself, so no peer is contacted and no cohort deadline is
+ * consumed.
+ *
+ * Note that the ~1 s `findCoordinator` spends internally is real, on top of this policy's own
+ * backoff — which is exactly why {@link CONTROL_WRITE_RETRY_BUDGET_MS} and not this count is what
+ * actually terminates the loop in the worst case.
+ */
+export declare const SCHEMA_INIT_ATTEMPTS = 5;
+/**
+ * Elapsed-time ceiling on the whole retry loop, measured from the START of the first
+ * attempt and checked after a failed attempt BEFORE sleeping.
+ *
+ * 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
+ * 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.
+ */
+export declare const CONTROL_WRITE_RETRY_BUDGET_MS = 10000;
+/**
+ * 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} —
+ * 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
+ * that is not an `Error` is never retried.
+ *
+ * {@link reportsIndeterminateCommit} vetoes the whole chain before any matcher runs, so a
+ * failure that reports a commit-phase batch anywhere is never retried on the strength of some
+ * other level looking transient.
+ *
+ * NOTE: this depends on engine/transactor error TEXT. The messages producible without a
+ * network are driven from the REAL engine in `control-formation-seat-budget.spec.ts`, so
+ * a rewording reddens a spec rather than silently disabling the retry. The two RETRIABLE
+ * messages need a real multi-node cluster to produce; the degraded-cohort scenario
+ * (`control-write-degraded-cohort-member.integration.ts`) asserts this classifier against
+ * both LIVE — the super-majority shortfall from a real silent member, and the transactor
+ * aggregate from a real stream reset, which the retry there absorbs end to end.
+ */
+export declare function isRetriableControlWriteFailure(error: unknown): boolean;
+/**
+ * {@link isRetriableControlWriteFailure} widened by exactly one class — the self-coordination
+ * grace refusal ({@link RETRIABLE_SCHEMA_INIT_MATCHERS}) — for `ControlDatabase.loadSchema`.
+ *
+ * Opt-in per call site, via {@link SCHEMA_INIT_RETRY_POLICY}. Every other control write keeps the
+ * default classifier untouched.
+ */
+export declare function isRetriableSchemaInitFailure(error: unknown): boolean;
+/**
+ * Policy and pacing for {@link retryControlWrite}. Production callers pass nothing (or a named
+ * policy such as {@link SCHEMA_INIT_RETRY_POLICY}); specs inject a recorded `sleep`, a shorter
+ * delay list, or a fake clock so no test ever waits out a real backoff.
+ *
+ * Every field defaults to the shipped control-write policy, so an omitted field is byte-identical
+ * to the behaviour before per-call-site policies existed.
+ */
+export interface ControlWriteRetryOptions {
+    /**
+     * Total attempts, first included. Default {@link CONTROL_WRITE_ATTEMPTS}, floored at 1 —
+     * below that the loop would run the body zero times and rethrow a `lastError` nobody set.
+     */
+    attempts?: number;
+    /** Backoff base before retry N (last entry repeats). Default {@link CONTROL_WRITE_RETRY_DELAYS_MS}. */
+    delaysMs?: readonly number[];
+    /**
+     * Which failures are transient enough to re-present. Default
+     * {@link isRetriableControlWriteFailure}; the only other shipped value is
+     * {@link isRetriableSchemaInitFailure}, via {@link SCHEMA_INIT_RETRY_POLICY}.
+     */
+    isRetriable?: (error: unknown) => boolean;
+    /**
+     * Operation label stamped into every log line this loop emits (rendered as
+     * `Control write [<label>] …`), and NOTHING else — no behavioural effect. The debug
+     * log is the only surface where the loop's decisions are observable (the rethrown
+     * error is unchanged and no attempt counter is exposed), and several writes retry
+     * CONCURRENTLY in a real party, so an unlabelled line cannot be attributed to a
+     * write. The degraded-cohort scenario asserts on these lines per-operation.
+     */
+    label?: string;
+    /** The sleep primitive. Default: `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Clock for the elapsed-budget check. Default: `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The one non-default retry policy: `ControlDatabase.loadSchema`'s distributed DDL, which
+ * additionally absorbs optimystic's self-coordination grace refusal and gets more attempts over a
+ * longer backoff to do it (see {@link SCHEMA_INIT_ATTEMPTS} and
+ * {@link SCHEMA_INIT_RETRY_DELAYS_MS}). Still bounded by the shared
+ * {@link CONTROL_WRITE_RETRY_BUDGET_MS}.
+ *
+ * NOTE: exactly one call site opts in today, and the re-run safety this policy assumes is that
+ * site's, not a general property — `apply schema` is a diff and a failed `create table` leaves the
+ * catalog clean. A second opt-in must re-derive that argument for its own write body first; if this
+ * policy ever grows a third consumer, rename it for what the callers share rather than widening it
+ * by default.
+ */
+export declare const SCHEMA_INIT_RETRY_POLICY: Readonly<ControlWriteRetryOptions>;
+/**
+ * Run `attempt` up to {@link CONTROL_WRITE_ATTEMPTS} times (or `options.attempts`), retrying only
+ * failures the policy's classifier — {@link isRetriableControlWriteFailure} by default —
+ * calls transient, and only while {@link CONTROL_WRITE_RETRY_BUDGET_MS} has not elapsed.
+ *
+ * `attempt` must be atomic and re-runnable: a failed cluster write rolls back (nothing is
+ * half-applied), and re-running the body re-runs its reads too — `ControlDatabase`'s
+ * locked write bodies all satisfy this (see the contract on
+ * `ControlDatabase.withWriteLock`). The backoff sleeps happen with NO lock held; the caller
+ * takes and releases its lock inside `attempt`.
+ *
+ * On exhaustion (attempts or budget) the LAST error is rethrown unchanged — never wrapped,
+ * 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 declare function retryControlWrite<T>(attempt: () => Promise<T>, options?: ControlWriteRetryOptions): Promise<T>;