@serfab/cadre-core 1.18.0 → 1.19.1

package/src/control-read-retry.ts

@@ -1,5 +1,5 @@
 import { BlockUnavailableError } from '@optimystic/db-core';
-import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
+import { causeChain, chainMessages, reportsUnreachableCohort, retryControlOperation } from './control-retry.js';
 import type { ControlRetryOptions } from './control-retry.js';
 import { isUncommittedTransactorAggregate } from './control-write-retry.js';
 
@@ -21,16 +21,14 @@ import { isUncommittedTransactorAggregate } from './control-write-retry.js';
  * This is deliberately NOT "the write classifier minus its commit veto" — the retriable
  * set differs in both directions (see {@link isRetriableControlReadFailure}). The loop
  * lives in `control-retry.ts`, shared with the write policy; this module owns only the
- * read policy. And like the write side, the retry classifies by TEXT. That was forced when
- * it was written — optimystic's scan path used to rethrow `new Error('Query failed: ' +
- * message)` with no `cause` — and is no longer: `OptimysticVirtualTable` now rethrows
- * through `rewrapAsQueryError` (`quereus-plugin-optimystic/src/optimystic-module.ts`),
- * which keeps the typed `BlockUnavailableError` on `cause`, and Quereus wraps that as
+ * read policy. A block-unavailability failure is matched by TYPE: `OptimysticVirtualTable`
+ * rethrows a scan failure through `rewrapAsQueryError`
+ * (`quereus-plugin-optimystic/src/optimystic-module.ts`), which keeps the typed
+ * `BlockUnavailableError` on `cause`, and Quereus wraps that as
  * `Error during query on table '<T>': …`, again preserving `cause`
- * (`quereus/src/runtime/emit/scan.ts`). The text matchers still work because every wrap
- * embeds the inner message. Every matcher fails CLOSED — an upstream rewording stops the
- * retry engaging, it never makes it unsafe. {@link isCohortUnreachableRead}, which is not a
- * retry classifier, matches by type.
+ * (`quereus/src/runtime/emit/scan.ts`). The transactor's aggregate is matched by TEXT, since
+ * upstream raises it as a plain `Error`. Every matcher fails CLOSED — an upstream rewording or
+ * a lost `cause` stops the retry engaging, it never makes it unsafe.
  */
 
 /**
@@ -83,45 +81,6 @@ export const CONTROL_READ_RETRY_DELAYS_MS: readonly number[] = [100, 400];
 // 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;
 
-/**
- * The block-unavailability reasons a repeat read can actually improve on, matched against
- * upstream's exact template `Block <id> is unavailable (<reason>): …`
- * (`BlockUnavailableError`, `db-core/src/network/struct.ts`):
- *
- * - **`peers-unreachable`** — part of the cohort answered and part could not be asked, and
- *   OTHER coordinators are reachable, so asking one of them can still settle it. Upstream's
- *   own definition invites the second attempt.
- * - **`cohort-unreachable`** — the marginal member of the set. Upstream says the answer
- *   will not improve until this node's connectivity does — but during bring-up connectivity
- *   DOES improve within a second (the boot-time failure shape recorded in
- *   `tickets/blocked/control-read-over-fresh-edge-stream-resets`), and the cost of being
- *   wrong is bounded by {@link CONTROL_READ_RETRY_BUDGET_MS}, which is the whole reason it
- *   is safe to include.
- *
- * Deliberately NOT matched:
- *
- * - **`claimed-elsewhere`** — a cohort peer positively claims the block exists and nobody
- *   could corroborate or acquire it. MEASURED not to clear: reissuing the same call every
- *   second for 60 s returned the identical error every time (2026-08-20, recorded in the
- *   fix ticket). Retrying spends the whole budget and fails anyway. The measured cause (a
- *   block only one machine held) was fixed upstream by the solo-commit proof in
- *   `@optimystic/db-p2p` 0.28.0 (`tickets/complete/block-held-by-only-one-machine-is-unreadable`),
- *   so a `claimed-elsewhere` that surfaces now is a new defect — this retry must not hide it.
- * - **`unmaterializable`** — records are held locally but cannot be reassembled. A local
- *   data problem; a second read reads the same records.
- * - **`Block <id> may be stale`** (`BlockPossiblyStaleError`) — about currency, not
- *   existence: a cohort claim no reachable coordinator could confirm or refute will not
- *   resolve inside a few hundred milliseconds of backoff.
- * - Anything unmatched. The default is no retry.
- */
-const RETRIABLE_BLOCK_UNAVAILABLE =
-	/Block \S+ is unavailable \((?:peers-unreachable|cohort-unreachable)\)/;
-
-/** A block-unavailable read failure whose reason a repeat read can improve on. */
-function isRetriableBlockUnavailable(message: string): boolean {
-	return RETRIABLE_BLOCK_UNAVAILABLE.test(message);
-}
-
 /**
  * Pacing overrides for {@link retryControlRead} — the read twin of
  * `ControlWriteRetryOptions`. Every field defaults to the shipped read policy
@@ -141,18 +100,20 @@ export type ControlReadRetryOptions = ControlRetryOptions;
  *   `[block:` token, and a read can never produce the commit-phase `[blocks:` token, so
  *   the write side's indeterminate-commit veto has nothing to veto here (a read commits
  *   nothing and re-running it is always safe);
- * - the block-unavailability reasons in {@link RETRIABLE_BLOCK_UNAVAILABLE} (and only
- *   those — see its comment for the measured exclusions).
+ * - a block read the cohort could not answer ({@link reportsUnreachableCohort}, the
+ *   predicate the write classifier shares — see it for the reasons and the measured
+ *   exclusions).
  *
- * Classifies by MESSAGE, walking the `cause` chain with the shared `chainMessages` (why
- * text, in the module comment). Anything that is not an `Error` is never retried.
+ * The aggregate is matched by message at any depth of the `cause` chain (`chainMessages`),
+ * the unavailability by type on the same chain. Anything that is not an `Error` is never
+ * retried, and anything unmatched is not retried either.
  */
 export function isRetriableControlReadFailure(error: unknown): boolean {
 	if (!(error instanceof Error)) {
 		return false;
 	}
-	return chainMessages(error).some(message =>
-		isUncommittedTransactorAggregate(message) || isRetriableBlockUnavailable(message));
+	return reportsUnreachableCohort(causeChain(error))
+		|| chainMessages(error).some(isUncommittedTransactorAggregate);
 }
 
 /**
@@ -165,9 +126,12 @@ export function isRetriableControlReadFailure(error: unknown): boolean {
  * never-received `Revocation` block as "no revocations known" (the reasoning is in the NOTE
  * there). Upstream names this the one reason a caller may treat permissively
  * (`db-core/src/transactor/network-transactor.ts`). The other reasons do NOT match:
- * `peers-unreachable` means part of the cohort answered, and `claimed-elsewhere` /
- * `unmaterializable` mean the block is known to exist, so an empty answer could hide a
- * real revocation.
+ * `peers-unreachable` means part of the cohort answered (or no coordinator did), and
+ * `claimed-elsewhere` / `unmaterializable` mean the block is known to exist, so an empty
+ * answer could hide a real revocation. NOTE: narrower than upstream's same-named
+ * `isCohortUnreachableRead` (`@optimystic/db-core`), which also matches `peers-unreachable`
+ * and is what the retry classifiers use ({@link reportsUnreachableCohort}); do not swap one
+ * for the other.
  *
  * Matched by TYPE, since the typed error survives upstream's rewraps (module comment).
  * Fails CLOSED: a non-`Error`, a text-only copy of the message, and an error built by a

package/src/control-retry.ts

@@ -1,4 +1,5 @@
 import debug from 'debug';
+import { isCohortUnreachableRead } from '@optimystic/db-core';
 import { unwrapError } from '@quereus/quereus';
 
 const log = debug('sereus:cadre:control-db');
@@ -232,10 +233,10 @@ function notifyAbandoned(
 }
 
 /**
- * Every message in the failure's `cause` chain — the shared substrate both retry classifiers
- * match against. They match text (why, in `control-read-retry.ts`'s module comment); every
- * wrap on the way out of optimystic and Quereus embeds the inner message, so the text of
- * the deepest failure is visible at every level.
+ * Every message in the failure's `cause` chain — the substrate both retry classifiers match
+ * their text matchers against (the transactor's aggregate and the coordinator's shortfall are
+ * plain `Error`s, recognisable only by text); every wrap on the way out of optimystic and
+ * Quereus embeds the inner message, so the text of the deepest failure is visible at every level.
  *
  * `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
@@ -256,8 +257,8 @@ export function chainMessages(error: Error): string[] {
 
 /**
  * `error` and every `cause` below it, outermost first — the substrate for the classifiers that
- * match by TYPE rather than text (the read side's cohort-unreachable check, the write side's
- * possibly-stored veto). Stops at a non-`Error` link (it can carry no further `cause` worth
+ * match by TYPE rather than text ({@link reportsUnreachableCohort}, the read side's isolated-node
+ * check, the write side's possibly-stored veto). Stops at a non-`Error` link (it can carry no further `cause` worth
  * trusting) and at a repeat, so a cyclic chain terminates.
  */
 export function causeChain(error: unknown): Error[] {
@@ -270,6 +271,53 @@ export function causeChain(error: unknown): Error[] {
 	return links;
 }
 
+/**
+ * Does any link of the `cause` chain report a block read that failed because the cohort could not
+ * be asked — a `BlockUnavailableError` whose reason is `peers-unreachable` or `cohort-unreachable`?
+ * The one block-unavailability test both retry classifiers share, so the read and write policies
+ * cannot disagree on which reasons a repeat can improve on:
+ *
+ * - **`peers-unreachable`** — part of the cohort answered and part could not be asked, or no
+ *   coordinator answered the read at all (`NetworkTransactor.get` flags such a block rather than
+ *   failing the whole read). Another attempt can reach one that answers; upstream's own definition
+ *   invites the second attempt.
+ * - **`cohort-unreachable`** — the marginal member of the set. Upstream says the answer will not
+ *   improve until this node's connectivity does — but during bring-up connectivity DOES improve
+ *   within a second (the boot-time failure shape recorded in
+ *   `tickets/blocked/control-read-over-fresh-edge-stream-resets`), and each policy's elapsed budget
+ *   bounds the cost of being wrong, which is the whole reason it is safe to include.
+ *
+ * Deliberately NOT matched:
+ *
+ * - **`claimed-elsewhere`** — a cohort peer positively claims the block exists and nobody could
+ *   corroborate or acquire it. MEASURED not to clear: reissuing the same call every second for 60 s
+ *   returned the identical error every time (2026-08-20, recorded in the fix ticket). Retrying spends
+ *   the whole budget and fails anyway. The measured cause (a block only one machine held) was fixed
+ *   upstream by the solo-commit proof in `@optimystic/db-p2p` 0.28.0
+ *   (`tickets/complete/block-held-by-only-one-machine-is-unreadable`), so a `claimed-elsewhere` that
+ *   surfaces now is a new defect — a retry must not hide it.
+ * - **`unmaterializable`** — records are held locally but cannot be reassembled. A local data
+ *   problem; a second read reads the same records.
+ * - **`BlockPossiblyStaleError`** (`Block <id> may be stale`) — about currency, not existence: a
+ *   cohort claim no reachable coordinator could confirm or refute will not resolve inside a few
+ *   hundred milliseconds of backoff.
+ *
+ * The reason set is upstream's (`isCohortUnreachableRead`, `db-core/src/transaction/commit-failure-class.ts`),
+ * the rule its commit-failure sort and the plugin's offline reads use for "the cohort could not be
+ * reached". NOTE: a reason upstream adds to that set is therefore retried here with no change in
+ * this repo — the right default for a set defined as unreachability; if it ever grows, re-check it
+ * against the exclusions above.
+ *
+ * Matched by TYPE. Upstream builds this error only on the node doing the read, from the
+ * `unavailable` flag a get result carries (`TransactorSource.tryGet`, `NetworkTransactor.getStatus`),
+ * never from a peer's error, and every rewrap on the way to either funnel keeps `cause`. NOTE: an
+ * error built by a second loaded copy of `@optimystic/db-core`, or one rebuilt as a plain `Error`
+ * from its text, fails `instanceof` and is not retried — the safe side.
+ */
+export function reportsUnreachableCohort(links: readonly Error[]): boolean {
+	return links.some(link => isCohortUnreachableRead(link));
+}
+
 /**
  * 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

package/src/control-write-retry.ts

@@ -1,6 +1,6 @@
 import { CoordinatorPartialCommitError, SyncRetryExhaustedError, TornActionError } from '@optimystic/db-core';
 import { ConcurrentModificationError, PartialCommitError } from '@optimystic/quereus-plugin-optimystic';
-import { causeChain, chainMessages, retryControlOperation } from './control-retry.js';
+import { causeChain, chainMessages, reportsUnreachableCohort, retryControlOperation } from './control-retry.js';
 import type { ControlRetryOptions } from './control-retry.js';
 
 /**
@@ -159,11 +159,17 @@ const SINGLE_BLOCK_BATCH_TOKEN = '[block:';
 const COMMIT_BATCH_TOKEN = '[blocks:';
 
 /**
- * The cluster coordinator's super-majority shortfall (`db-p2p/src/repo/cluster-coordinator.ts`),
- * matched ONLY with a ZERO rejection count. The same message with a non-zero count means a
- * member actually voted no (that branch carries `membership-not-admitted` rejections), and
- * retrying it would re-present a spent signature to a cohort that already refused it. This one
- * is raised while collecting PROMISES, before any commit, so re-presenting it is safe.
+ * The cluster coordinator's super-majority shortfall (`PromiseShortfallError`, db-core), matched
+ * ONLY with a ZERO rejection count. The same message with a non-zero count means a member actually
+ * voted no (that branch carries `membership-not-admitted` rejections), and retrying it would
+ * re-present a spent signature to a cohort that already refused it. A pend's shortfall reaches this
+ * funnel as that error on its own, before any commit, so re-presenting it is safe; a commit's
+ * arrives inside the `[blocks:` aggregate, which {@link reportsIndeterminateCommit} vetoes (both
+ * seen live in `control-write-degraded-cohort-member`).
+ *
+ * NOTE: matched by TEXT although the error is typed. Upstream keeps this sentence byte for byte as a
+ * downstream contract, so the regex is stable; moving to `instanceof PromiseShortfallError` with
+ * `rejections === 0` is backlog `debt-control-write-retry-matches-the-shortfall-by-type`.
  *
  * This regex itself never matches a decisive rejection (`ValidatorRejectionError`, `Transaction
  * rejected by validators`) — that text carries no `Failed to get super-majority:` prefix. But the
@@ -183,7 +189,9 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED =
  * re-present:
  *
  * - `get` (a block read, which a write body also performs) and `pend` (phase 1) fail before
- *   anything commits, so the write is known not to have landed;
+ *   anything commits, so the write is known not to have landed. `get` raises it only when a
+ *   coordinator answered and left a block out; a block nobody answered for fails typed
+ *   instead, which {@link matchesRetriableFailure} claims ({@link reportsUnreachableCohort});
  * - `commitBlocks` (phase 2) is REACHABLE here and NOT safe. `commitBlock` throws the
  *   aggregate when a header/tail commit got NO response at all — precisely the transient
  *   class this retry targets — and that escapes `commit()`, survives `TransactorSource`'s
@@ -206,10 +214,12 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED =
  * NOTE: the discriminator is a formatting detail of another repo. If Optimystic ever reformats
  * those per-batch details, this fails CLOSED — the aggregate stops matching and control writes
  * simply stop being retried, silently losing the absorption rather than doing anything unsafe.
- * The guard against that is live: `control-write-degraded-cohort-member.integration.ts` asserts
- * this classifier against the real degraded-cohort failure object and asserts the `[block:`
- * token on the live aggregate; if it reddens there, an upstream reformat is the first thing to
- * check.
+ * The guard is `control-write-degraded-cohort-member.integration.ts`, which asserts the `[block:`
+ * token on any live aggregate a degraded case produces; if it reddens there, an upstream reformat
+ * is the first thing to check. NOTE: on Optimystic 1.20.0 none of its cases produced this form
+ * (2026-10-28: the injected reset failed the write's read typed, and a pend's shortfall arrives on
+ * its own), so the guard can pass without seeing it; if the form is ever needed live again, inject
+ * the reset at the pend's batch rather than the read's.
  *
  * NOTE: the discriminator is the prefix AND the token within ONE message — never relax it to
  * "contains `[block:`". Beyond the `get` and `pend` sites above, Optimystic renders `[block:` in
@@ -234,12 +244,14 @@ const SUPER_MAJORITY_SHORTFALL_UNANSWERED =
  *    have left its log entry standing), and its collection sync has already spent ten retries on
  *    the race. The torn-write rule beside it: a `TornActionError` is re-presented only when
  *    `final` is true; any other torn write is declined.
- *  - What remains rejectable at the promise phase is stale revision, block-unavailable,
- *    membership-not-admitted, and a configured validator's refusal. Only the first is worth a
- *    retry — and it is worth one: this loop re-runs the WHOLE write body, reads included
+ *  - What remains rejectable at the promise phase is stale revision, membership-not-admitted, an
+ *    expired transaction, and a configured validator's refusal (`ClusterMember.evaluatePromise`).
+ *    A block whose revision a member cannot establish is approved, not refused: the member logs
+ *    `validation-block-unavailable` and votes on (`judgeStaleRevisions`). Stale revision is worth
+ *    a retry: this loop re-runs the WHOLE write body, reads included
  *    (`ControlDatabase.withWriteLock`'s contract), so attempt 2 presents a pend against the
  *    revision that made attempt 1 stale. A blanket "decline any chain reporting a validator
- *    rejection" rule would remove that retry to save two wasted attempts on the other three.
+ *    rejection" rule would remove that retry to save two wasted attempts on the others.
  *
  * Revisit if a re-presentation ever becomes expensive relative to what it buys — a rejection class
  * that costs a full cohort round-trip to re-present, or a write body whose reads are no longer
@@ -404,7 +416,9 @@ function isSelfCoordinationGraceRefusal(message: string): boolean {
 /**
  * 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:
- * a read/pend-phase transactor aggregate with `cause=The stream has been reset`.
+ * a read/pend-phase transactor aggregate with `cause=The stream has been reset`. When none of
+ * the cohort answers the read at all, that failure arrives typed instead, and is claimed by
+ * type in {@link matchesRetriableFailure} ({@link reportsUnreachableCohort}), not here.
  *
  * Deliberately NOT matched: every constraint / authorization failure
  * (`CHECK constraint failed:`, `UNIQUE constraint failed:`) — those reach the same funnel
@@ -471,16 +485,18 @@ const RETRIABLE_SCHEMA_INIT_MATCHERS: readonly ((message: string) => boolean)[]
  * Two vetoes run over the whole chain before any matcher: {@link reportsPossiblyStoredWrite}
  * (by type — a spent sync budget, a non-final torn write, a partial commit) and
  * {@link reportsIndeterminateCommit} (by text — a commit-phase batch). A chain either veto flags,
- * at any level, is never retried on the strength of some other level looking transient. The one
- * typed failure claimed as retriable is a final torn write ({@link isFinalTornWrite}).
+ * at any level, is never retried on the strength of some other level looking transient. Two typed
+ * failures are claimed as retriable: a block read the cohort could not answer
+ * ({@link reportsUnreachableCohort}, shared with the read classifier) and a final torn write
+ * ({@link isFinalTornWrite}).
  *
  * 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.
+ * a rewording reddens a spec rather than silently disabling the retry. The RETRIABLE failures
+ * need a real multi-node cluster to produce; the degraded-cohort scenario
+ * (`control-write-degraded-cohort-member.integration.ts`) asserts this classifier against the
+ * super-majority shortfall from a real silent member, and absorbs a real stream reset end to end
+ * (on Optimystic 1.20.0 the reset fails the write's read as an unanswered block, claimed by type).
  */
 export function isRetriableControlWriteFailure(error: unknown): boolean {
 	return matchesRetriableFailure(error, RETRIABLE_CONTROL_WRITE_MATCHERS);
@@ -511,12 +527,13 @@ export function isRetriableLostUpdateFailure(error: unknown): boolean {
 /**
  * Shared body of the three classifiers: walk the `cause` chain, let
  * {@link reportsPossiblyStoredWrite} and then {@link reportsIndeterminateCommit} veto it, then claim
- * a final torn write ({@link isFinalTornWrite}) or any link `claimsLink` names, then ask `matchers`.
- * The vetoes run BEFORE any claim for every policy — a chain reporting a possibly-stored write or a
- * commit-phase batch is never retried, however transient some other level looks, and a final torn
- * write or a lost update carried by a partial commit is still declined because a sibling collection
- * landed. `claimsLink` is the one typed claim a policy may add; it sits here beside the torn-write
- * claim so the vetoes stay in one place above both.
+ * a block read the cohort could not answer ({@link reportsUnreachableCohort}), a final torn write
+ * ({@link isFinalTornWrite}) or any link `claimsLink` names, then ask `matchers`. The vetoes run
+ * BEFORE any claim for every policy — a chain reporting a possibly-stored write or a commit-phase
+ * batch is never retried, however transient some other level looks, and a final torn write or a
+ * lost update carried by a partial commit is still declined because a sibling collection landed.
+ * `claimsLink` is the one typed claim a policy may add; it sits here beside the shared typed claims
+ * so the vetoes stay in one place above all of them.
  */
 function matchesRetriableFailure(
 	error: unknown,
@@ -534,7 +551,18 @@ function matchesRetriableFailure(
 	if (reportsIndeterminateCommit(messages)) {
 		return false;
 	}
-	if (links.some(link => isFinalTornWrite(link) || claimsLink?.(link) === true)) {
+	// NOTE: an unanswered read can fail AFTER this write's log entry is stored: the refresh between
+	// commit attempts reads the collection's log ends, and finishing the write's own entry
+	// (`Collection.completeOwnEntry`) asks `getStatus` when no attempt is retained at the entry's
+	// revision (a forked lineage — both commit paths retain the failed attempt before refreshing).
+	// Either throw escapes the refresh loop unwrapped. Claimed anyway, because the `[block:`
+	// aggregate those same reads raise is already claimed by the text matcher, so the typed form
+	// adds no new case: the re-run is a new transaction whose body re-reads the blocks, so it diffs
+	// to nothing or fails on `UNIQUE` where the earlier write landed, and writes it once where it did
+	// not. A refresh that already saved a sibling collection arrives as
+	// `CoordinatorPartialCommitError`, which the veto above declines.
+	if (reportsUnreachableCohort(links)
+		|| links.some(link => isFinalTornWrite(link) || claimsLink?.(link) === true)) {
 		return true;
 	}
 	return messages.some(message => matchers.some(matches => matches(message)));

package/src/edge-node/config.ts

@@ -13,7 +13,7 @@ import type { BootstrapPeerStore } from '../bootstrap-peer-store.js';
 import type { EnrolledMachineStore } from '../enrolled-machine-store.js';
 import type { StrandNetworkStateStore } from '../strand-network-state.js';
 import type { TrustedOwnerStore } from '../trusted-owner-store.js';
-import type { IRawStorage, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
+import type { IKVStore, IRawStorage, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
 import type { EdgeNodeOptions } from './options.js';
 
 /** What {@link buildEdgeNodeConfig} takes: one start's options plus what the platform built. */
@@ -31,6 +31,11 @@ export interface EdgeNodeConfigInputs extends EdgeNodeOptions {
 	 * segment — use it verbatim, do not parse it.
 	 */
 	storageProvider: (scope: string) => IRawStorage;
+	/**
+	 * A strand's offline journal (`EdgeNodeStorage.offlineJournal`). Absent: no offline mode, and
+	 * {@link EdgeNodeOptions.strandOfflineMode} is ignored.
+	 */
+	offlineJournal?: (scope: string) => Promise<IKVStore>;
 	/** libp2p transport factories: what the node dials with, and what listens on `listenAddrs`. */
 	transports: Libp2pTransports;
 	/**
@@ -50,7 +55,8 @@ export interface EdgeNodeConfigInputs extends EdgeNodeOptions {
  * The edge node's config: transaction profile (Ring Zulu only, intermittent connectivity), no
  * listen address unless the platform names one, reachability through the configured relays (if
  * any) but never a hard requirement for one, every strand the control network lists, and no
- * automatic hibernation (the app's lifecycle runner hibernates on background). Schema signing is
+ * automatic hibernation (the app's lifecycle runner hibernates on background), and offline mode
+ * on strands when the platform keeps an offline journal. Schema signing is
  * left at cadre-core's fail-closed default; an app with unsigned schemas relaxes it in
  * `EdgeNodePlatform.configure`.
  */
@@ -102,6 +108,9 @@ export function buildEdgeNodeConfig(inputs: EdgeNodeConfigInputs): CadreNodeConf
 			// gated by `denyDialPeer` and the inbound hooks. cadre-core hands this gater to strand nodes too.
 			...(inputs.allowPrivateDial ? { connectionGater: { denyDialMultiaddr: () => false } } : {}),
 		},
+		...(inputs.offlineJournal && {
+			strandOffline: { journal: inputs.offlineJournal, initialMode: inputs.strandOfflineMode ?? 'online' },
+		}),
 		strandFilter: { mode: 'all' },
 		hibernation: { enabled: false },
 		trustedOwners: { store: inputs.trustedOwnerStore },

package/src/edge-node/edge-join.ts

@@ -140,6 +140,7 @@ async function switchParty(
 	};
 	const noiseCryptoMode = options.noiseCryptoMode ?? leaving?.noiseCryptoMode;
 	if (noiseCryptoMode !== undefined) joined.noiseCryptoMode = noiseCryptoMode;
+	if (leaving?.strandOfflineMode !== undefined) joined.strandOfflineMode = leaving.strandOfflineMode;
 	if (formerPartyId !== undefined) joined.formerPartyId = formerPartyId;
 	const movingFrom = founded ? await recordStrandMove(runtime, founded, credential) : undefined;
 	try {

package/src/edge-node/edge-node.ts

@@ -38,6 +38,7 @@ import type {
 	RemoveOwnerOptions,
 } from '../types.js';
 import type { Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
+import type { StrandOfflineMode } from '../strand-offline.js';
 import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
 import { webSockets } from '@libp2p/websockets';
 import { buildEdgeNodeConfig, requireOwnerKeyLabel, runOwnerGenesis, wireJoinedOwnerKey, type OwnerGenesisResult } from './config.js';
@@ -167,6 +168,15 @@ export interface EdgeNode {
 	 * is built. `autoStart` is not cleared on the way, so a crash mid-restart still starts again.
 	 */
 	restart(options: EdgeNodeOptions): Promise<CadreNode>;
+	/**
+	 * Change the app's offline mode ({@link EdgeNodeOptions.strandOfflineMode}) without a restart:
+	 * every strand the running node runs takes it at once (`CadreNode.setStrandOfflineMode`), so
+	 * does each strand it starts later, and the saved start keeps it, so the next start, a
+	 * background restart and a push wake start every strand in it. In turn with start, stop and
+	 * join. Throws while no node runs, and on a platform with no offline journal
+	 * (`EdgeNodeStorage.offlineJournal`).
+	 */
+	setStrandOfflineMode(mode: StrandOfflineMode): Promise<void>;
 	/**
 	 * Join the cadre `credential` names: this app's one node moves to that party, keeping its
 	 * identity, so the peer id an owner targeted is the one that redeems. A machine invitation
@@ -362,6 +372,8 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 	 */
 	private transitions: Promise<unknown> = Promise.resolve();
 	private currentStatus: EdgeNodeStatus = { state: 'stopped' };
+	/** The mode {@link setStrandOfflineMode} set on the running node, which it was not built with; null until then. */
+	private changedOfflineMode: { node: CadreNode; mode: StrandOfflineMode } | null = null;
 	private lastUnfinishedRemoval: UnfinishedRemoval | null = null;
 	private readonly subscriptions = new Set<Subscription>();
 	private readonly statusListeners = new Set<(status: EdgeNodeStatus) => void>();
@@ -424,6 +436,19 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 		});
 	}
 
+	setStrandOfflineMode(mode: StrandOfflineMode): Promise<void> {
+		return this.inTurn(async () => {
+			const node = this.node;
+			const running = this.options;
+			if (!node || !running) throw new Error('Cannot set the offline mode: the edge node is not running');
+			if (!this.platform.storage.offlineJournal) throw new Error('Cannot set the offline mode: this platform keeps no offline journal');
+			for (const strandId of node.getStrands().keys()) node.setStrandOfflineMode(strandId, mode);
+			this.changedOfflineMode = { node, mode };
+			this.runningOptions = { ...running, strandOfflineMode: mode };
+			await this.saveRunningStart(this.runningOptions);
+		});
+	}
+
 	joinCadre(credential: JoinCredential, options: JoinCadreOptions = {}): Promise<JoinCadreResult> {
 		// A start called from here on runs after this join rather than joining a start it replaces.
 		this.starting = null;
@@ -670,6 +695,7 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 		this.current = node;
 		for (const subscription of this.subscriptions) subscription.attach(node);
 		this.watchRemoval(node);
+		this.followOfflineMode(node);
 		await node.start();
 		return { node, resolved };
 	}
@@ -740,19 +766,22 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 	 * build's default does not change a device that already ran. Options naming no `origin`
 	 * take the saved start's `origin` and `formerPartyId` when it is for the same party, so a
 	 * party this app joined, started again from a hand-typed party id, does not run owner genesis.
+	 * Options naming no `strandOfflineMode` take the saved start's, whatever its party: the mode is
+	 * the app's choice ({@link setStrandOfflineMode}), and a start built from a form or from options
+	 * held since before that choice would otherwise drop it.
 	 */
 	private async resolveOptions(options: EdgeNodeOptions): Promise<EdgeNodeOptions> {
 		requireOwnerKeyLabel(options.ownerKeyLabel);
 		const resolved = { ...options };
 		const defaultMode = this.platform.noiseCrypto?.defaultMode;
 		if (resolved.noiseCryptoMode === undefined && defaultMode !== undefined) resolved.noiseCryptoMode = defaultMode;
-		if (resolved.origin === undefined) {
-			const saved = (await this.readSavedStart())?.options;
-			if (saved?.partyId === resolved.partyId) {
-				if (saved.origin !== undefined) resolved.origin = saved.origin;
-				if (saved.formerPartyId !== undefined) resolved.formerPartyId = saved.formerPartyId;
-			}
+		if (resolved.origin !== undefined && resolved.strandOfflineMode !== undefined) return resolved;
+		const saved = (await this.readSavedStart())?.options;
+		if (resolved.origin === undefined && saved?.partyId === resolved.partyId) {
+			if (saved.origin !== undefined) resolved.origin = saved.origin;
+			if (saved.formerPartyId !== undefined) resolved.formerPartyId = saved.formerPartyId;
 		}
+		if (resolved.strandOfflineMode === undefined && saved?.strandOfflineMode !== undefined) resolved.strandOfflineMode = saved.strandOfflineMode;
 		return resolved;
 	}
 
@@ -770,6 +799,7 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 			noiseCrypto: this.buildNoiseCrypto(options.noiseCryptoMode),
 			keyStore: this.keyStore,
 			storageProvider: (scope) => platform.storage.rawStorage(scope),
+			offlineJournal: platform.storage.offlineJournal?.bind(platform.storage),
 			transports: (platform.transports ?? defaultTransports)(relayAddrs),
 			listenAddrs: platform.listenAddrs?.(relayAddrs) ?? [],
 			allowPrivateDial: platform.allowPrivateDial ?? true,
@@ -861,6 +891,24 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 		});
 	}
 
+	/**
+	 * A strand that starts after {@link setStrandOfflineMode} changed the mode takes the new one:
+	 * the node applies the mode it was built with (`strandOffline.initialMode`) to every launch.
+	 */
+	// NOTE: this, and setStrandOfflineMode's loop, override a mode an app set on one strand with
+	// `CadreNode.setStrandOfflineMode`; if an app ever mixes per-strand modes with this call, keep the per-strand ones.
+	private followOfflineMode(node: CadreNode): void {
+		node.on('strand:started', ({ strandId }) => {
+			const changed = this.changedOfflineMode;
+			if (changed?.node !== node) return;
+			try {
+				node.setStrandOfflineMode(strandId, changed.mode);
+			} catch (err) {
+				console.warn(`[cadre-core/edge-node] strand ${strandId} started in the mode the node was built with, not ${changed.mode}:`, err);
+			}
+		});
+	}
+
 	/**
 	 * In turn with start, stop and join: stop the removed party's node, point the saved start away
 	 * from that party, delete its local storage and report `removed`. A node of another party, started
@@ -944,6 +992,7 @@ class EdgeNodeRuntime implements EdgeNode, JoinRuntime, OwnerGrantRuntime {
 		const stopping = this.current;
 		this.current = null;
 		this.runningOptions = null;
+		this.changedOfflineMode = null;
 		try {
 			if (stopping) {
 				for (const subscription of this.subscriptions) subscription.detach(stopping);

package/src/edge-node/options.ts

@@ -9,6 +9,8 @@
  * start the node unattended.
  */
 
+import type { StrandOfflineMode } from '../strand-offline.js';
+
 /**
  * How much of Noise's crypto the platform replaces (`EdgeNodePlatform.noiseCrypto`): none, the
  * per-frame hash and cipher, or those and the handshake's key exchange too. Named here, apart from
@@ -47,6 +49,13 @@ export interface EdgeNodeOptions {
 	 * stays on disk under its own names, for moving its strands and dissolving the old cadre.
 	 */
 	formerPartyId?: string;
+	/**
+	 * The offline mode every strand starts in (`CadreNodeConfig.strandOffline.initialMode`); absent,
+	 * the saved start's, else `'online'`. Read only on a platform with an offline journal (`EdgeNodeStorage.offlineJournal`).
+	 * `EdgeNode.setStrandOfflineMode` changes it while running, and saves it; `CadreNode.setStrandOfflineMode`
+	 * changes one strand's mode until the process exits.
+	 */
+	strandOfflineMode?: StrandOfflineMode;
 }
 
 /** Whether this app founded its party, or joined it by invitation. */
@@ -73,10 +82,11 @@ export interface SavedStart {
  * store, which every start reads.
  */
 export function startAfterRemoval(saved: SavedStart): SavedStart | undefined {
-	const { partyId, formerPartyId, relayAddrs, noiseCryptoMode } = saved.options;
+	const { partyId, formerPartyId, relayAddrs, noiseCryptoMode, strandOfflineMode } = saved.options;
 	if (formerPartyId === undefined || formerPartyId === partyId) return undefined;
 	const options: EdgeNodeOptions = { partyId: formerPartyId, bootstrapAddrs: [], relayAddrs, origin: 'founded' };
 	if (noiseCryptoMode !== undefined) options.noiseCryptoMode = noiseCryptoMode;
+	if (strandOfflineMode !== undefined) options.strandOfflineMode = strandOfflineMode;
 	return { options, autoStart: false, ...(saved.writtenBy !== undefined && { writtenBy: saved.writtenBy }) };
 }
 
@@ -99,12 +109,13 @@ interface StartRecord {
 	origin?: EdgeNodeOrigin;
 	formerPartyId?: string;
 	ownerKeyLabel?: string;
+	strandOfflineMode?: StrandOfflineMode;
 	autoStart: boolean;
 	writtenBy?: string;
 }
 
 export function serializeSavedStart(saved: SavedStart): string {
-	const { partyId, bootstrapAddrs, relayAddrs, noiseCryptoMode, origin, formerPartyId, ownerKeyLabel } = saved.options;
+	const { partyId, bootstrapAddrs, relayAddrs, noiseCryptoMode, origin, formerPartyId, ownerKeyLabel, strandOfflineMode } = saved.options;
 	const record: StartRecord = {
 		version: RECORD_VERSION,
 		partyId,
@@ -114,6 +125,7 @@ export function serializeSavedStart(saved: SavedStart): string {
 		origin,
 		formerPartyId,
 		ownerKeyLabel,
+		strandOfflineMode,
 		autoStart: saved.autoStart,
 		writtenBy: saved.writtenBy,
 	};
@@ -125,8 +137,9 @@ export function serializeSavedStart(saved: SavedStart): string {
  *
  * Only the party id is worth discarding a record over. A malformed optional field falls back to
  * its default — `[]` for an address list, the build default for the Noise mode, absent for
- * `origin`, `formerPartyId` and `ownerKeyLabel`, `false` for `autoStart` — so a damaged record still keeps the
- * app in its party, at worst needing the user to start the node by hand.
+ * `origin`, `formerPartyId`, `ownerKeyLabel` and `strandOfflineMode` (which is `'online'`), `false`
+ * for `autoStart` — so a damaged record still keeps the app in its party, at worst needing the
+ * user to start the node by hand.
  */
 export function parseSavedStart(text: string | undefined): SavedStart | undefined {
 	if (text === undefined) return undefined;
@@ -148,6 +161,9 @@ export function parseSavedStart(text: string | undefined): SavedStart | undefine
 		options.formerPartyId = record.formerPartyId;
 	}
 	if (typeof record.ownerKeyLabel === 'string') options.ownerKeyLabel = record.ownerKeyLabel;
+	if (record.strandOfflineMode === 'online' || record.strandOfflineMode === 'offline') {
+		options.strandOfflineMode = record.strandOfflineMode;
+	}
 	const saved: SavedStart = { options, autoStart: record.autoStart === true };
 	if (typeof record.writtenBy === 'string') saved.writtenBy = record.writtenBy;
 	return saved;