crypto-aio 0.0.2 → 0.1.0

package/dist/core/lifecycle/engine.d.ts

@@ -0,0 +1,500 @@
+import type { AssetService } from '../assets/service';
+import type { ResolvedSelection } from '../config/types';
+import type { PooledDriver } from '../container/pool';
+import type { BroadcastResult, BuildContext, SequenceSource } from '../driver/types';
+import { ChainError, type CryptoAioError } from '../errors/error';
+import type { EventBus } from '../events/bus';
+import type { Logger } from '../events/logger';
+import { type StoredIntent, type TransferIntent } from '../model/intent';
+import type { FeeOverride, FeeSpeed } from '../model/fee';
+import { type OrderingData } from '../model/ordering';
+import type { AttemptRef, UnsignedTx } from '../model/transaction';
+import { type LeaseHandle, type SequenceCoordinator } from '../ordering/sequence';
+import type { SigningOrchestrator } from '../signing/orchestrator';
+import type { SignatureBundle, SignerTicket, SigningContext, SigningPurpose, SigningRequest } from '../signing/types';
+import type { ResolvedWallet } from '../signing/wallet';
+import { type AttemptPurpose, type AttemptRecord, type ExecutionContext, type Fence, type OperationPatch, type OperationRecord, type OperationState, type Stores } from '../store/types';
+import { type Clock } from '../util/clock';
+import { type ResolvedLifecycle, type RestorePoint } from './engine-rules';
+import { type ObservationDeps } from './observations';
+import * as reconcile from './reconcile';
+/** What read-only lifecycle work (monitoring, waiting) needs: no wallet required. */
+export interface ReadTarget {
+    readonly selection: ResolvedSelection;
+    readonly pooled: PooledDriver;
+}
+export interface OperationTarget extends ReadTarget {
+    readonly wallet: ResolvedWallet;
+    readonly assets: AssetService;
+}
+export interface TransferOptions {
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export { LIFECYCLE_DEFAULTS, PRE_SIGNING_STATES, errorCode, rehydrateError, serializeError, withLifecycleDefaults, type ResolvedLifecycle, } from './engine-rules';
+export interface EngineDeps {
+    readonly namespace: string;
+    readonly stores: Stores;
+    readonly events: EventBus;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly orchestrator: SigningOrchestrator;
+    readonly sequences: SequenceCoordinator;
+    readonly lifecycle: () => ResolvedLifecycle;
+}
+export declare class OperationEngine {
+    protected readonly deps: EngineDeps;
+    constructor(deps: EngineDeps);
+    get namespace(): string;
+    /** Builds and persists the unsigned transaction; runs the policy hook. Idempotent per key. */
+    prepare(target: OperationTarget, intent: TransferIntent, options?: TransferOptions): Promise<OperationRecord>;
+    /**
+     * Idempotent transfer: prepare → sign → persist the Attempt (write-ahead) → broadcast.
+     * A repeat resumes where the Operation stopped and never signs an Attempt twice.
+     */
+    transfer(target: OperationTarget, intent: TransferIntent, options?: TransferOptions): Promise<OperationRecord>;
+    /**
+     * Adds externally produced signatures (cold, offline, MPC); completes and broadcasts once
+     * every request is signed. Under the address lease, and the `beforeSign` policy is
+     * asked again first (defence in depth): a veto fails the Operation, releases its nonce and
+     * cancels its signer tickets, as a veto before signing does.
+     */
+    submitSignatures(target: OperationTarget, operationId: string, signatures: readonly SignatureBundle[]): Promise<OperationRecord>;
+    /**
+     * Resends the SAME stored raw bytes of the active Attempt (never builds or signs), under
+     * the address lease. A refused replacement or cancel gives the active role back
+     * to the Attempt it superseded (`resendActive`).
+     */
+    rebroadcast(target: OperationTarget, operationId: string, signal?: AbortSignal): Promise<OperationRecord>;
+    /**
+     * Only before any signed bytes exist. Under the address lease: re-reads the
+     * Operation, renews the lease (a lost lease fails before any write), marks it
+     * `abandoned` and releases its reservation. Pending signer tickets are cancelled after
+     * the lease is dropped, even when the release failed.
+     */
+    abandon(target: OperationTarget, operationId: string): Promise<OperationRecord>;
+    /** Best effort, through the signer that issued each ticket; failures log codes only. */
+    protected cancelTickets(target: OperationTarget, operationId: string, tickets: readonly SignerTicket[]): Promise<void>;
+    /**
+     * A new Attempt paying a higher fee for the same slot (same nonce or seqno,
+     * or conflicting inputs). Needs the `replace-fee` capability, the driver's
+     * ReplacementPolicy and a synchronous signer; `submitted` or `stalled` only. See
+     * `createConflicting`.
+     *
+     * Idempotent per fee spec. While the active Attempt is a replacement made for the
+     * same spec (the same `FeeSpeed` name, or a canonically equal `FeeOverride`), a repeat
+     * signs nothing and returns it, resending its stored bytes when their broadcast was never
+     * recorded or was ambiguous. A replacement for the same spec that was refused (the
+     * superseded Attempt active again) is resent, never signed again; a refusal is thrown,
+     * never a success. To bump again, pass another spec (e.g. a higher override).
+     *
+     * While the active replacement is persisted but unsent (`signed`), another fee spec
+     * is refused with INVALID_TRANSITION; repeat the same spec (it is resent) or call
+     * `rebroadcast` first.
+     */
+    replace(target: OperationTarget, operationId: string, fee: FeeSpeed | FeeOverride): Promise<OperationRecord>;
+    /**
+     * "Cancel" is a conflicting transaction for the same slot (e.g. a self-transfer), not a
+     * protocol primitive: the outcome is `cancelled` only when the cancel Attempt reaches
+     * proven finality, and the original may still win. Capability `cancel`; `submitted` or
+     * `stalled` only. It pays the driver's minimum bump over the highest-fee earlier cancel
+     * (or over the active Attempt when there is none), or `fee` when given (refused below
+     * that bump). See `createConflicting`.
+     *
+     * A repeat while a cancel is the active Attempt resends its stored bytes when their
+     * broadcast was never recorded or was ambiguous, and returns it unchanged while a node
+     * holds it (`pending`, `mempool`) or once it is on chain; concurrent and retried cancels
+     * are idempotent. Only a cancel recorded `refused` or `dropped` is bumped by a repeat
+     * (each bump climbs one step from the highest-fee cancel), so a cancel that cannot land
+     * never leaves the nonce stuck. When the node's floor is more than one bump away, pass
+     * `fee`: an explicit fee always builds a new cancel while none is on chain.
+     *
+     * While the active replacement is persisted but unsent (`signed`), a cancel is refused
+     * with INVALID_TRANSITION; repeat that replacement's fee spec (it is resent) or call
+     * `rebroadcast` first.
+     */
+    cancel(target: OperationTarget, operationId: string, fee?: FeeSpeed | FeeOverride): Promise<OperationRecord>;
+    /**
+     * Expiry and seqno chains only: once every earlier Attempt is provably dead (re-proved
+     * here from finalized state, `assertAttemptsDead`), an `expired` Operation gets a fresh
+     * Attempt and is live again. It is the one explicit exception to "a terminal Operation
+     * never moves" (see `appendSigned`). Under the Operation's lease (the op lock on expiry
+     * chains, the address lease on seqno chains); signed once, persisted before its
+     * broadcast, and a repeat resends a persisted rebuild instead of signing another. On a
+     * seqno chain it takes the wallet's next seqno (SEQUENCE_BUSY while another live
+     * Operation holds it), and the Operation's `reservation` is refreshed to the rebuilt
+     * Attempt's ordering in the same write as the Attempt. A refusal of the rebuilt
+     * Attempt leaves the Operation `stalled`, never `expired` again: only the monitor's proof
+     * can end it.
+     */
+    rebuild(target: OperationTarget, operationId: string): Promise<OperationRecord>;
+    get(operationId: string): Promise<OperationRecord | null>;
+    require(operationId: string): Promise<OperationRecord>;
+    /**
+     * The Operation, checked to belong to this handle's chain, network and wallet
+     * before anything reads its payload (e.g. `submitSignatures` with a signed payload), so
+     * another wallet's Operation never reaches the driver.
+     */
+    requireOwned(target: OperationTarget, operationId: string): Promise<OperationRecord>;
+    protected open(target: OperationTarget, intent: TransferIntent, options: TransferOptions): Promise<{
+        record: OperationRecord;
+        stored: StoredIntent;
+    }>;
+    protected executionContext(target: OperationTarget): ExecutionContext;
+    /**
+     * Rejects an Operation of another chain, network or sending address: its reservation
+     * lives under a different sequence key, which this target's lease must never touch.
+     */
+    protected assertOwnedBy(target: OperationTarget, op: OperationRecord): void;
+    /**
+     * The address lease of `op`'s own sending address (keyed on the Operation, never on
+     * the target's wallet, so a write for a stored Operation needs no signer). Any snapshot
+     * of the Operation will do: its chain, network and sender never change. Every
+     * transition of an Operation that holds a reservation runs under it, and so does the
+     * release of that reservation (see `releaseReservation`).
+     */
+    protected withAddressLease<T>(target: ReadTarget, op: OperationRecord, fn: (lease: LeaseHandle | undefined) => Promise<T>, signal?: AbortSignal, options?: {
+        readonly acquireTimeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Serializes one Operation's signing transitions: the wallet's address lease where the
+     * ordering needs one, otherwise (expiry ordering) a short per-Operation lock, so two
+     * same-key repeats can never both sign it. Its handle is passed down (renewed,
+     * heartbeat) exactly like the address lease; it never guards a sequence write.
+     */
+    protected withOperationLease<T>(target: ReadTarget, op: OperationRecord, fn: (lease: LeaseHandle | undefined) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** The sequence key of the Operation's own chain, network and sending address. */
+    protected sequenceKeyOf(op: Pick<OperationRecord, 'context' | 'intent'>): string;
+    protected walletOperations(op: OperationRecord): Promise<OperationRecord[]>;
+    protected prepareStage(target: OperationTarget, op: OperationRecord, stored: StoredIntent, lease: LeaseHandle | undefined, signal?: AbortSignal): Promise<OperationRecord>;
+    /**
+     * `prepare()`'s policy check. Bounded like signing, by `lifecycle.signTimeoutMs` and
+     * the caller's `signal` (`signingDeadline`), but with no heartbeat: a hook that outlives
+     * the lease loses it, and its veto then writes nothing. Only a veto fails the
+     * Operation; a timeout or an abort leaves it `prepared` for a repeat to authorize again.
+     */
+    protected authorizeOrFail(target: OperationTarget, op: OperationRecord, lease?: LeaseHandle, signal?: AbortSignal): Promise<void>;
+    /**
+     * Takes an Operation as far as one call can, all under its lease (`withOperationLease`:
+     * the address lease, or a per-Operation lock on expiry chains): `created`
+     * is prepared, `prepared` is signed into the write-ahead Attempt, and a `signed` (or
+     * ambiguously `submitted`) Operation resends its stored raw bytes; it is never signed
+     * again. Any other state is returned as it is (`settle` rethrows a stored failure).
+     */
+    protected drive(target: OperationTarget, op: OperationRecord, stored: StoredIntent, signal?: AbortSignal): Promise<OperationRecord>;
+    /**
+     * Runs the policy hook and the signer(s) over the stored unsigned payload, bounded by the
+     * lease (`signingDeadline`). A veto or a mismatching signature fails the Operation before
+     * signing. A pending result is persisted as `awaiting-signature` with every ticket;
+     * a signed one becomes the write-ahead Attempt.
+     */
+    protected signStage(target: OperationTarget, op: OperationRecord, lease?: LeaseHandle, signal?: AbortSignal): Promise<OperationRecord>;
+    /**
+     * Bounds a signer or policy call (they have no deadline of their own) by
+     * `lifecycle.signTimeoutMs` and the caller's `signal`, and keeps the held lease alive
+     * meanwhile (renewed every `leaseMs / 3`). On timeout, abort or a lost lease nothing
+     * is written: the Operation keeps its state and reservation (a late signature may still
+     * appear), and a repeat asks again. A lost lease is logged by code, like
+     * `failAfterPrepare`. A result that arrives after the wait ended goes to `late` (a
+     * pending answer's tickets are cancelled there); otherwise it is dropped.
+     */
+    protected signingDeadline<T>(op: OperationRecord, lease: LeaseHandle | undefined, signal: AbortSignal | undefined, work: () => Promise<T>, late?: (result: T) => Promise<void>): Promise<T>;
+    /**
+     * Renews `lease` every `max(1, leaseMs / 3)` ms until `stop` aborts. Rejects (after a
+     * code-only log) when a renewal fails: the lease was lost to another worker.
+     */
+    protected heartbeat(op: OperationRecord, lease: LeaseHandle, stop: AbortSignal): Promise<never>;
+    /**
+     * The persisted partial signatures that still verify. A corrupt entry is
+     * dropped (its request is signed or submitted again) instead of making `sign()` or
+     * `accept()` throw SIGNATURE_MISMATCH on every call, which would strand the Operation.
+     */
+    protected usablePartials(op: OperationRecord, requests: readonly SigningRequest[]): SignatureBundle[];
+    /**
+     * Assembles and persists an immutable Attempt BEFORE any broadcast (write-ahead). `lease`
+     * is renewed right before the write: signing may have outlived it, and then
+     * nothing is written. When the append loses its compare-and-set to a writer that took the
+     * Operation to `signed` or beyond (or ended it), the stored Operation is returned
+     * instead, and callers continue from its state; a still pre-signing one rethrows the
+     * VERSION_CONFLICT, and an abandoned one is INVALID_TRANSITION. The `signed` Operation is
+     * scheduled (`nextCheckAt: now`), like every engine transition after signing.
+     *
+     * A new Attempt (`supersedes` set: replace, cancel, rebuild) has a stricter lost-CAS
+     * contract: the stored Operation is returned only when it shows this very Attempt;
+     * otherwise the VERSION_CONFLICT is rethrown (`signNewAttempt` may retry it).
+     *
+     * The store does not guard transitions, so appending to a terminal Operation is refused
+     * here, with one explicit exception: a `rebuild` Attempt reopens an `expired` Operation
+     * (`rebuild` re-proves every earlier Attempt dead under the lease first). It is
+     * the only way out of a terminal state; `update` refuses every other.
+     *
+     * An Attempt whose ref another Operation of the namespace holds is never appended
+     * (`withRefFree`); an original one fails its Operation and keeps its nonce.
+     */
+    protected appendSigned(target: OperationTarget, op: OperationRecord, unsigned: UnsignedTx, signatures: readonly SignatureBundle[], purpose: SigningPurpose, supersedes?: string, lease?: LeaseHandle): Promise<OperationRecord>;
+    /**
+     * Runs `append` only when no other Operation of this namespace holds `ref`, live or
+     * terminal (a terminal holder's bytes are already on chain): a second Operation
+     * recording the same bytes would inherit their outcome, reporting success for a payment
+     * that never moved. The check and the append run under a short lease on the ref, so two
+     * processes sharing the lock manager cannot both pass it; it is always the innermost
+     * lease, so it cannot deadlock with the address or Operation lease held around it. This
+     * also needs `findByRef` to be read-your-writes consistent across those processes (no
+     * read replica or eventually consistent index) and the append to finish within
+     * `leaseMs`. The held `lease` is renewed inside it, right before the write. A ref lease
+     * still held elsewhere after `leaseMs / 3`, a bound that keeps the wait within the held
+     * lease, is `SEQUENCE_BUSY` with its own fixed text (the coordinator's text names the
+     * address lease).
+     */
+    protected withRefFree<T>(op: OperationRecord, ref: AttemptRef, lease: LeaseHandle | undefined, append: () => Promise<T>): Promise<T>;
+    protected activeAttempt(op: OperationRecord): AttemptRecord;
+    /**
+     * Replace and cancel, under the Operation's lease (the address lease; the op lock on
+     * expiry chains). The new Attempt is built from the active one and must be mutually
+     * exclusive with every earlier Attempt (checked before signing; for inputs, exclusion is
+     * not transitive) and use the slot `assertBuiltOrdering` expects. It is signed once and
+     * persisted before its broadcast (`signNewAttempt`), never re-signed: a repeat whose
+     * Attempt was persisted but never, or ambiguously, sent resends its stored bytes
+     * (`resumeNewAttempt`). When the node refuses the fresh Attempt, the one it superseded is
+     * still live: the Operation goes back to its previous state and active Attempt
+     * (`restoreAfterRefusal`) and the node's error is thrown. That refusal is never terminal.
+     *
+     * A repeat of an earlier request (`fee` is the requested spec): the same
+     * replacement spec is answered by that replacement (`repeatReplacement`); a cancel is
+     * resent, returned, or bumped when refused or dropped (`repeatCancel`). See `replace` and
+     * `cancel`.
+     */
+    protected createConflicting(target: OperationTarget, operationId: string, purpose: 'replacement' | 'cancel', fee: FeeSpeed | FeeOverride | undefined, build: (previous: UnsignedTx, ctx: BuildContext) => Promise<UnsignedTx>): Promise<OperationRecord>;
+    /**
+     * The replacement a repeat of this fee spec refers to: the active one made for it,
+     * or the latest Attempt when it was made for it and, refused, gave the active role back to
+     * the Attempt it superseded. `undefined`: a new request.
+     */
+    protected priorReplacement(op: OperationRecord, fee: FeeSpeed | FeeOverride | undefined): AttemptRecord | undefined;
+    /**
+     * A repeat of the request `prior` was made for signs nothing. Its stored bytes are
+     * resent when their broadcast was never recorded, was ambiguous, or was refused or
+     * rejected: the node's current answer decides, and a refusal restores the
+     * superseded Attempt and is thrown (`resendActive`), never reported as a success. A
+     * `prior` that already gave the active role back is resent first and made active again
+     * only once the node accepted it (`resendRestoredAway`). An active `prior` the node holds,
+     * or one on chain, is returned as it is. `undefined` (a refused `prior` of an Operation
+     * that moved on): the caller goes on as for a new request.
+     */
+    protected repeatReplacement(target: OperationTarget, op: OperationRecord, prior: AttemptRecord, lease: LeaseHandle | undefined): Promise<OperationRecord | undefined>;
+    /**
+     * Resends the stored bytes of a replacement that gave the active role back after a
+     * refusal, while the Attempt it superseded stays active. Only once a node accepted them
+     * (or they are already seen) is it made active again (`reactivate`) and the acceptance
+     * recorded, so a crash in between leaves the superseded Attempt active and never an
+     * unaccepted one. A refusal or rejection is thrown and changes nothing; an ambiguous
+     * failure leaves the may-be-live marker (`recordAmbiguous`).
+     */
+    protected resendRestoredAway(target: OperationTarget, op: OperationRecord, prior: AttemptRecord, lease: LeaseHandle | undefined): Promise<OperationRecord>;
+    /**
+     * Makes a refused new Attempt active again, only while the Attempt it superseded is still
+     * the active one and nothing was appended since (compare-and-set, re-derived after a lost
+     * one). Otherwise VERSION_CONFLICT (retryable).
+     */
+    protected reactivate(op: OperationRecord, attempt: AttemptRecord, lease: LeaseHandle | undefined): Promise<OperationRecord>;
+    /**
+     * A cancel while a cancel is the active Attempt. Its stored bytes are resent when
+     * their broadcast was never recorded or was ambiguous; it is returned unchanged while a
+     * node holds it (`pending`, `mempool`) and once it is on chain (chain evidence), so
+     * concurrent and retried cancels are idempotent. `undefined` asks the caller for a new,
+     * bumped cancel: only when the cancel is recorded `refused`, `rejected` or
+     * `dropped`, or for an explicit `fee` while it is not on chain. A refused or rejected one
+     * first gives the active role back to the Attempt it superseded, so it is never
+     * reported as a success.
+     */
+    protected repeatCancel(target: OperationTarget, op: OperationRecord, active: AttemptRecord, fee: FeeSpeed | FeeOverride | undefined, lease: LeaseHandle | undefined): Promise<OperationRecord | undefined>;
+    /**
+     * A repeat of a replace, cancel or rebuild whose Attempt was persisted but never sent (no
+     * broadcast recorded: a crash after `appendAttempt`) or sent with an unknown outcome
+     * (ambiguous): its stored bytes are resent, never signed again, so a retry creates no
+     * second new Attempt. `undefined` when there is nothing to resume.
+     *
+     * The resend goes through `resendActive`: a refusal restores the superseded Attempt.
+     */
+    protected resumeNewAttempt(target: OperationTarget, op: OperationRecord, purpose: Exclude<AttemptPurpose, 'original'>, lease: LeaseHandle | undefined): Promise<OperationRecord | undefined>;
+    /**
+     * Resends the active Attempt's stored bytes (`broadcastActive`) for every resend path:
+     * `rebroadcast` (and so recovery), a same-key `transfer` and a repeated replace, cancel or
+     * rebuild. When the node refuses a resent replacement or cancel, the Attempt it
+     * superseded becomes active again (`undoRefusedResend`) and the refusal is thrown, so it is
+     * never reported as a success. A refused rebuild stays `stalled` (see `rebuild`).
+     */
+    protected resendActive(target: OperationTarget, op: OperationRecord, signal: AbortSignal | undefined, lease: LeaseHandle | undefined): Promise<OperationRecord>;
+    /**
+     * After a resend of a replacement or cancel was refused, the Attempt it superseded
+     * becomes active again. The state it was appended over is not recorded, so it is derived
+     * from the superseded Attempt's observation: when that one may still be live (`pending`,
+     * `mempool`, `included`), the Operation returns to `submitted`; otherwise (e.g. the
+     * original was itself refused) only the active Attempt is swapped and the Operation keeps
+     * its `stalled` state and stored error. Nothing for an original or a rebuild.
+     */
+    protected undoRefusedResend(operationId: string, refused: AttemptRecord, lease: LeaseHandle | undefined): Promise<void>;
+    /**
+     * Signs a new Attempt once and persists it (write-ahead) before any broadcast. The policy
+     * hook and the signer are bounded by `lifecycle.signTimeoutMs`, with the lease renewed
+     * meanwhile (`signingDeadline`). A pending answer is refused, since new Attempts need a
+     * synchronous signer, and its tickets are cancelled through their issuers, as are
+     * those of a pending answer that arrives after the deadline. A veto, a timeout or a bad
+     * signature writes nothing.
+     *
+     * A lost compare-and-set (e.g. a worker's claim bumped the version) is retried with the
+     * same signatures under the same lease while the re-read Operation is still `eligible`
+     * with the same Attempts. Otherwise the VERSION_CONFLICT is rethrown and these bytes,
+     * never persisted or sent, are dropped. Success is returned only when the stored
+     * Operation shows the new Attempt (`appendSigned`): `signed`, together with `before`, the
+     * snapshot the successful append was made over (what a refusal restores).
+     */
+    protected signNewAttempt(target: OperationTarget, op: OperationRecord, unsigned: UnsignedTx, purpose: Exclude<AttemptPurpose, 'original'>, eligible: ReadonlySet<OperationState>, lease: LeaseHandle | undefined): Promise<{
+        readonly signed: OperationRecord;
+        readonly before: OperationRecord;
+    }>;
+    /**
+     * The node refused a replacement or cancel, so the Attempt it superseded is
+     * still the live one and keeps its nonce. While the refused Attempt is still the active
+     * one and the Operation is not terminal (an ended Operation is left alone),
+     * the superseded one becomes active again. When the Operation still shows the refusal
+     * (`stalled`, or `signed` after a rejection) and `point` names a state, it also returns
+     * to `point`'s state, error and ambiguity; any other state (`included`, `submitted` or
+     * later) is the monitor's and is kept. The refused Attempt stays recorded and monitored.
+     * The lease is renewed first. A failure is only logged: the caller gets the node's error
+     * either way, and the Operation stays safely `stalled`.
+     */
+    protected restoreAfterRefusal(operationId: string, refusedId: string | undefined, point: RestorePoint, lease: LeaseHandle | undefined): Promise<void>;
+    /**
+     * Rebuild's precondition, re-proved from finalized state (quorum proof reads), never
+     * taken from stored observations: each earlier Attempt's expiry passed, or (seqno)
+     * another transaction consumed its slot, per finalized state, and only then is it
+     * confirmed not included at finality. In that order, as the monitor does: any inclusion
+     * would lie at or below the already finalized expiry or slot, so the later read sees it.
+     * Otherwise INVALID_TRANSITION; nothing is written.
+     */
+    protected assertAttemptsDead(target: OperationTarget, op: OperationRecord): Promise<void>;
+    /**
+     * The wallet's next seqno as a reservation. Seqno wallets are strictly serial: another
+     * live Operation that may still consume the current seqno makes this SEQUENCE_BUSY.
+     */
+    protected nextSeqno(sequence: SequenceSource, op: OperationRecord): Promise<OrderingData>;
+    protected get observationDeps(): ObservationDeps;
+    /**
+     * Sends the active Attempt's stored raw bytes. `lease` is the held address lease (every
+     * caller holds it; leases are not reentrant): a rejection's terminal write and
+     * release run under it.
+     */
+    protected broadcastActive(target: OperationTarget, op: OperationRecord, signal?: AbortSignal, lease?: LeaseHandle): Promise<OperationRecord>;
+    /**
+     * The broadcast may have reached the network: a transport failure, an RPC error after a
+     * possibly delivered attempt (`ambiguous`), or a caller abort (which the transport
+     * surfaces bare). The Operation becomes `submitted` + `ambiguous` and is monitored; it is
+     * never failed and keeps its reservation. A retry with the same key resends the stored
+     * bytes. The observation is written first and on its own, then the transition, re-derived
+     * after a lost compare-and-set; a store failure is only logged: the caller must get the
+     * ambiguous error.
+     * `ambiguous: true` means the outcome is unknown and the caller retries
+     * with the same idempotency key; the error keeps its code and that code's retryability.
+     */
+    protected recordAmbiguous(op: OperationRecord, attempt: AttemptRecord, error: unknown, signal?: AbortSignal): Promise<CryptoAioError>;
+    /**
+     * Accepted / already-known → `submitted` (an `included` Operation is never
+     * downgraded); the acceptance is remembered on the observation (`firstSeenAt`). refused
+     * and rejected → the Attempt's own ref is looked up first (seen means it was ours all
+     * along). An `included` Operation, or an Attempt whose observation holds chain
+     * evidence (mined, replaced or expired), is never stalled, failed or released by a later
+     * answer, and a rejection of bytes a node once accepted counts only as a refusal.
+     * Otherwise refused → `stalled`, keeping the nonce; rejected (proven invalid) → `failed`
+     * with the nonce released, once every Attempt is rejected.
+     *
+     * The node's own refusal or rejection is thrown as it is; any other failure while
+     * recording the answer (the bytes may have reached the network) is thrown `ambiguous`
+     * with `operationId`, so a caller retries with the same key instead of paying again.
+     */
+    protected applyBroadcastResult(target: OperationTarget, op: OperationRecord, attempt: AttemptRecord, result: BroadcastResult, lease?: LeaseHandle): Promise<OperationRecord>;
+    /** `applyBroadcastResult`'s transitions; returns (never throws) the node's own answer. */
+    protected recordBroadcastResult(target: OperationTarget, op: OperationRecord, attempt: AttemptRecord, result: BroadcastResult, lease?: LeaseHandle): Promise<OperationRecord | ChainError>;
+    /**
+     * The all-rejected verdict. Once every Attempt is proven `rejected`, no valid
+     * signed bytes exist for the nonce: the Operation fails and the nonce is released in the
+     * same step, under the address lease, whoever reaches the verdict (the
+     * broadcast path or the monitor). Under the lease it re-reads the Operation, re-checks
+     * the verdict and renews the lease before the terminal compare-and-set; a lost lease or a
+     * verdict that no longer holds writes nothing and returns the stored Operation. Pass the
+     * held lease when already inside `withAddressLease` (it is not re-entrant).
+     *
+     * Without a held lease (the monitor), the lease wait is bounded by `signal` as well as
+     * `acquireTimeoutMs` (the option overrides it; `0` tries once); a busy lease, or a target
+     * whose wallet no longer owns the Operation (e.g. re-pointed to another key), writes
+     * nothing, logs the code and returns `op`. An abort is rethrown. A worker passes its
+     * claim `fence`: the terminal write carries it, and a claim taken over by another worker
+     * (FENCING) writes nothing, logs the code and returns the stored Operation.
+     */
+    failRejected(target: OperationTarget, op: OperationRecord, options?: {
+        readonly lease?: LeaseHandle;
+        readonly error?: CryptoAioError;
+        readonly signal?: AbortSignal;
+        readonly acquireTimeoutMs?: number;
+        readonly fence?: Fence;
+    }): Promise<OperationRecord>;
+    /** Nonce reconciliation under the address lease; see `reconcileNonces` in `./reconcile`. */
+    reconcileNonces(target: OperationTarget, op: OperationRecord, options?: {
+        readonly signal?: AbortSignal;
+        readonly acquireTimeoutMs?: number;
+    }): Promise<readonly bigint[]>;
+    /** The engine's steps that `./reconcile` runs, bound to this engine. */
+    protected reconciler(): reconcile.Reconciler;
+    protected everyAttemptRejected(op: OperationRecord): Promise<boolean>;
+    /**
+     * A post-broadcast Operation write. After a lost compare-and-set the Operation is
+     * re-read and `patchFor` re-derives the transition from it; `undefined` means the stored
+     * state already reflects it (or it no longer applies), and the stored Operation is
+     * returned.
+     */
+    protected updateAfterBroadcast(op: OperationRecord, patchFor: (current: OperationRecord) => OperationPatch | undefined | Promise<OperationPatch | undefined>): Promise<OperationRecord>;
+    /**
+     * A failure after the bytes may have reached the network is always an
+     * ambiguous STATE_UNRECORDED (retryable by its catalogue entry, so no other code's
+     * retryability is overridden), naming the Operation and the original code.
+     */
+    protected ambiguousAfterBroadcast(op: OperationRecord, attempt: AttemptRecord, error: unknown): CryptoAioError;
+    /**
+     * Before a refusal or rejection is believed, looks the Attempt's own ref up.
+     * A failed lookup decides nothing: the Operation is scheduled for the monitor (as the
+     * ambiguous path does) and the error names it.
+     */
+    protected seenOwnRef(target: OperationTarget, op: OperationRecord, attempt: AttemptRecord, now: number): Promise<boolean>;
+    /**
+     * Terminal failure before any signed bytes exist (after signing, see `failRejected`):
+     * mark failed, then free the nonce, both under one address lease. Callers already inside `withAddressLease` must pass their lease (it is not
+     * re-entrant); a caller without one gets it acquired first (acquire → renew → CAS →
+     * release, never CAS before acquire). The lease is renewed first: when it was lost (a
+     * slow policy hook or signer outlived it), nothing is written, the Operation keeps its
+     * state, its next repeat retries under a fresh lease, and the original `error` is
+     * rethrown. Returning means the terminal write landed; a failed release after it is only
+     * logged (callers rethrow their own error either way). Logs carry codes only. With
+     * `release: false` (a held ref) the nonce is kept: signed bytes of another Operation
+     * may use it.
+     */
+    protected failAfterPrepare(target: OperationTarget, op: OperationRecord, error: unknown, lease?: LeaseHandle, options?: {
+        readonly release?: boolean;
+    }): Promise<OperationRecord>;
+    /**
+     * Returns the Operation's reserved nonce under the held address lease. Call at most once
+     * per allocation, only after the Operation's terminal CAS made under that same lease.
+     * There is no lease-less fallback: acquiring a lease only after the CAS could fail and
+     * leak the nonce, so a missing lease for a nonce is a programming error.
+     */
+    protected releaseReservation(op: OperationRecord, lease: LeaseHandle | undefined): Promise<void>;
+    protected signingContext(target: OperationTarget, op: OperationRecord, unsigned: UnsignedTx, purpose: SigningPurpose): SigningContext;
+    /**
+     * Version-checked (and optionally fenced) state change; emits `operation.state` on
+     * transitions. The store does not guard transitions, so this refuses to move a terminal
+     * Operation to any other state (the version check makes `op.state` the stored state).
+     */
+    update(op: OperationRecord, patch: OperationPatch, fence?: Fence): Promise<OperationRecord>;
+    protected emitState(record: OperationRecord, from: OperationState | null): void;
+    /** Repeats of failed or stalled Operations surface the same error as the original call. */
+    protected settle(op: OperationRecord): OperationRecord;
+}