crypto-aio 0.0.2 → 0.1.0

package/dist/core/lifecycle/workers.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Workers = void 0;
+const error_1 = require("../errors/error");
+const types_1 = require("../store/types");
+const bytes_1 = require("../util/bytes");
+const engine_rules_1 = require("./engine-rules");
+const DEFAULT_BATCH = 50;
+/** How many Operations' reported gaps a monitor remembers (`nonce.gap` is at-least-once). */
+const GAP_MEMORY = 10_000;
+/** Worker passes and startup recovery for one monitor (see `Monitor`). */
+class Workers {
+    deps;
+    monitor;
+    /**
+     * Per Operation, the expected nonces a `nonce.gap` was already emitted for; least
+     * recently reported first, capped at `GAP_MEMORY` Operations.
+     */
+    #gaps = new Map();
+    constructor(deps, monitor) {
+        this.deps = deps;
+        this.monitor = monitor;
+    }
+    /**
+     * One worker pass: claims up to `batch` due Operations, checks each under its claim fence
+     * (a stale worker's writes fail), then releases the claim. Every claimed Operation
+     * that stays live leaves the pass scheduled a poll interval ahead, including when its
+     * check threw, its view was stale or its all-rejected verdict could not run, so no worker
+     * claims it again before then. A stale view also skips gap handling and reconciliation.
+     * `signal` bounds each check and its lease wait; once it aborts, the Operations not yet
+     * checked are only released, still due, for another worker. Returns how many Operations
+     * it claimed.
+     */
+    async runOnce(options) {
+        const { signal } = options;
+        if (signal?.aborted)
+            return 0;
+        const claimed = await this.deps.stores.operations.claimDue(this.deps.namespace, options.workerId, this.deps.clock.now(), this.deps.lifecycle().claimLeaseMs, options.batch ?? DEFAULT_BATCH);
+        const reads = this.#passResolver(this.deps.resolveRead);
+        const writes = this.#passResolver(this.deps.resolveTarget);
+        for (const op of claimed) {
+            const fence = { claimToken: op.claim.token };
+            if (!signal?.aborted)
+                await this.#process(reads, writes, op, fence, signal);
+            await this.deps.stores.operations
+                .releaseClaim(this.deps.namespace, op.id, fence)
+                .catch((error) => this.deps.log.debug('claim already lost', {
+                operationId: op.id,
+                code: (0, engine_rules_1.errorCode)(error),
+            }));
+        }
+        return claimed.length;
+    }
+    /** One claimed Operation of a worker pass (see `runOnce`). */
+    async #process(reads, writes, op, fence, signal) {
+        const started = this.deps.clock.now();
+        let current;
+        try {
+            const target = await this.#resolved(reads, op);
+            const pass = await this.monitor.checkPass(target, op, fence, signal);
+            current = pass.record;
+            if (!pass.stale)
+                await this.#detectNonceGap(target, current, writes);
+        }
+        catch (error) {
+            // An abort mid-check is an expected shutdown, not a failure.
+            this.deps.log[signal?.aborted ? 'debug' : 'warn'](signal?.aborted ? 'monitor check stopped' : 'monitor check failed', { operationId: op.id, code: (0, engine_rules_1.errorCode)(error) });
+        }
+        const scheduled = current !== undefined &&
+            ((0, types_1.isTerminal)(current.state) ||
+                (current.nextCheckAt !== undefined && current.nextCheckAt > started));
+        if (!scheduled)
+            await this.#reschedule(op.id, fence, started);
+    }
+    /**
+     * Runs worker passes until `signal` aborts. Any number of workers, in any number of
+     * processes, may run: claims keep them apart. A full batch is followed by the next pass at
+     * once, anything less by a poll-interval sleep. A failed pass (e.g. a store outage) is
+     * logged by code and retried after the sleep.
+     */
+    async start(options = {}) {
+        const workerId = options.workerId ?? (0, bytes_1.randomId)('worker');
+        const batch = options.batch ?? DEFAULT_BATCH;
+        const { signal } = options;
+        while (!signal?.aborted) {
+            let processed = 0;
+            try {
+                processed = await this.runOnce({
+                    workerId,
+                    batch,
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (error) {
+                this.deps.log.warn('monitor worker pass failed', {
+                    workerId,
+                    code: (0, engine_rules_1.errorCode)(error),
+                });
+            }
+            if (processed > 0 && processed >= batch)
+                continue;
+            try {
+                await this.deps.clock.sleep(this.deps.lifecycle().pollIntervalMs, signal);
+            }
+            catch {
+                return;
+            }
+        }
+    }
+    /**
+     * Startup recovery for this namespace; it never signs. `signed` and ambiguously
+     * `submitted` Operations resend their stored raw bytes; every other signed-or-later live
+     * Operation is checked. `created`, `prepared`, `awaiting-signature` and `stalled` ones need
+     * a caller and are reported through `recovery.skipped` (codes and states only). Then each
+     * wallet with a live Operation has its nonces reconciled under its address lease. A
+     * failure is logged by code and counted, and the rest go on. `signal` stops recovery
+     * between Operations and bounds each check and lease wait. Known gap: a `signed` or
+     * ambiguous Operation whose wallet-bound target cannot be resolved is counted `failed`
+     * without its check, although the check needs no wallet.
+     */
+    async recover(options = {}) {
+        const { signal } = options;
+        const { namespace } = this.deps;
+        const live = await this.deps.stores.operations.list({
+            namespace,
+            states: types_1.NON_TERMINAL_STATES,
+        });
+        const reads = this.#passResolver(this.deps.resolveRead);
+        const writes = this.#passResolver(this.deps.resolveTarget);
+        let rebroadcast = 0;
+        let checked = 0;
+        let skipped = 0;
+        let failed = 0;
+        let reconciled = 0;
+        const skip = (op, reason) => {
+            skipped += 1;
+            this.deps.events.emit('recovery.skipped', {
+                namespace,
+                operationId: op.id,
+                state: op.state,
+                reason,
+            });
+        };
+        for (const op of live) {
+            if (signal?.aborted)
+                break;
+            if (engine_rules_1.PRE_SIGNING_STATES.has(op.state)) {
+                skip(op, 'CALLER_ACTION_REQUIRED');
+                continue;
+            }
+            if (op.state === 'stalled') {
+                skip(op, 'STALLED');
+                continue;
+            }
+            try {
+                const target = await this.#resolved(reads, op);
+                let current = op;
+                if (op.state === 'signed' ||
+                    (op.state === 'submitted' && op.ambiguous === true)) {
+                    const writer = await this.#resolved(writes, op);
+                    try {
+                        current = await this.deps.engine.rebroadcast(writer, op.id, signal);
+                    }
+                    catch (error) {
+                        // A refusal or an unknown outcome is recorded on the Operation: check it next.
+                        if (!(0, error_1.isCryptoAioError)(error) ||
+                            (error.category !== 'chain' && error.ambiguous !== true))
+                            throw error;
+                        current = (await this.monitor.find(op.id)) ?? op;
+                    }
+                    rebroadcast += 1;
+                }
+                await this.monitor.check(target, current, undefined, signal);
+                checked += 1;
+            }
+            catch (error) {
+                failed += 1;
+                this.deps.log.warn('recovery of an operation failed', {
+                    operationId: op.id,
+                    code: (0, engine_rules_1.errorCode)(error),
+                });
+            }
+        }
+        const wallets = new Map();
+        for (const op of live) {
+            const key = [op.context.chain, op.context.network, op.intent.from].join('\n');
+            if (!wallets.has(key))
+                wallets.set(key, op);
+        }
+        for (const op of wallets.values()) {
+            if (signal?.aborted)
+                break;
+            try {
+                const writer = await this.#resolved(writes, op);
+                reconciled += (await this.deps.engine.reconcileNonces(writer, op, { signal }))
+                    .length;
+            }
+            catch (error) {
+                this.deps.log.warn('nonce reconciliation failed', {
+                    operationId: op.id,
+                    code: (0, engine_rules_1.errorCode)(error),
+                });
+            }
+        }
+        return { rebroadcast, checked, skipped, failed, reconciled };
+    }
+    /**
+     * `resolve` for one pass: each execution context's target is rebuilt at most once, and
+     * only when first asked for (a wallet-bound one only by a write that needs it).
+     */
+    #passResolver(resolve) {
+        const targets = new Map();
+        return (op) => {
+            let target = targets.get(op.context.configHash);
+            if (!target) {
+                target = resolve(op);
+                targets.set(op.context.configHash, target);
+            }
+            return target;
+        };
+    }
+    async #resolved(resolve, op) {
+        const target = await resolve(op);
+        if (!target) {
+            throw new error_1.ConfigError('CONFIG_INVALID', `the target of operation '${op.id}' cannot be rebuilt from its context`);
+        }
+        return target;
+    }
+    /**
+     * Leaves a claimed, live Operation scheduled a poll interval ahead, unless it ended,
+     * another worker took it over or a writer scheduled it meanwhile. A pre-signing Operation
+     * is never scheduled (callers drive it), so it is unscheduled instead. Best effort.
+     */
+    async #reschedule(id, fence, started) {
+        try {
+            for (let tries = 0; tries < 3; tries++) {
+                const fresh = await this.deps.stores.operations.get(this.deps.namespace, id);
+                if (!fresh ||
+                    (0, types_1.isTerminal)(fresh.state) ||
+                    fresh.claim?.token !== fence.claimToken ||
+                    (fresh.nextCheckAt !== undefined && fresh.nextCheckAt > started))
+                    return;
+                const patch = engine_rules_1.PRE_SIGNING_STATES.has(fresh.state)
+                    ? { clear: ['nextCheckAt'] }
+                    : { nextCheckAt: this.deps.clock.now() + this.deps.lifecycle().pollIntervalMs };
+                try {
+                    await this.deps.engine.update(fresh, patch, fence);
+                    return;
+                }
+                catch (error) {
+                    if (!(0, error_1.isCryptoAioError)(error, 'VERSION_CONFLICT'))
+                        throw error;
+                }
+            }
+        }
+        catch (error) {
+            this.deps.log.debug('could not reschedule a claimed operation', {
+                operationId: id,
+                code: (0, engine_rules_1.errorCode)(error),
+            });
+        }
+    }
+    /**
+     * `nonce.gap`, once per (Operation, expected nonce): a `submitted` Operation has waited
+     * longer than `droppedGracePeriodMs` since its active Attempt was first seen or sent, and
+     * the chain's pending nonce is still below its own (a lower nonce is missing
+     * even from the mempool, so congestion alone is no gap). It names the live Operation
+     * holding the expected nonce, when one exists. Every such pass then reconciles the wallet's nonces, trying the lease
+     * once (never a filler transaction): a leaked value goes back for the next transfer.
+     * Only that write resolves the wallet-bound target (`writes`).
+     */
+    async #detectNonceGap(target, op, writes) {
+        const { sequence } = target.pooled.driver;
+        if (op.state !== 'submitted' || op.reservation?.kind !== 'nonce' || !sequence) {
+            this.#gaps.delete(op.id);
+            return;
+        }
+        const attempt = op.attempts.find((a) => a.id === op.activeAttemptId);
+        const observation = attempt
+            ? await this.deps.stores.operations.getObservation(attempt.id)
+            : null;
+        // Not `lastBroadcastAt`, which every resend of a dropped Attempt refreshes.
+        const since = observation?.firstSeenAt ?? attempt?.createdAt ?? op.createdAt;
+        if (this.deps.clock.now() - since < this.deps.lifecycle().droppedGracePeriodMs)
+            return;
+        const expected = await sequence.pending(op.intent.from);
+        if (expected >= op.reservation.nonce)
+            return;
+        const reported = this.#gaps.get(op.id) ?? new Set();
+        this.#gaps.delete(op.id);
+        this.#gaps.set(op.id, reported);
+        if (this.#gaps.size > GAP_MEMORY) {
+            const oldest = this.#gaps.keys().next().value;
+            if (oldest !== undefined)
+                this.#gaps.delete(oldest);
+        }
+        if (!reported.has(expected.toString())) {
+            reported.add(expected.toString());
+            const blocking = (await this.deps.stores.operations.list({
+                namespace: this.deps.namespace,
+                chain: op.context.chain,
+                network: op.context.network,
+                from: op.intent.from,
+                states: types_1.NON_TERMINAL_STATES,
+            })).find((o) => o.reservation?.kind === 'nonce' && o.reservation.nonce === expected);
+            this.deps.events.emit('nonce.gap', {
+                namespace: this.deps.namespace,
+                chain: op.context.chain,
+                network: op.context.network,
+                operationId: op.id,
+                expected: expected.toString(),
+                ...(blocking ? { blockingOperationId: blocking.id } : {}),
+            });
+        }
+        try {
+            const writer = await this.#resolved(writes, op);
+            await this.deps.engine.reconcileNonces(writer, op, { acquireTimeoutMs: 0 });
+        }
+        catch (error) {
+            const busy = (0, error_1.isCryptoAioError)(error, 'SEQUENCE_BUSY');
+            this.deps.log[busy ? 'debug' : 'warn']('nonce reconciliation did not run', {
+                operationId: op.id,
+                code: (0, engine_rules_1.errorCode)(error),
+            });
+        }
+    }
+}
+exports.Workers = Workers;
+//# sourceMappingURL=workers.js.map

package/dist/core/lifecycle/workers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.js","sourceRoot":"","sources":["../../../src/core/lifecycle/workers.ts"],"names":[],"mappings":"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","sourcesContent":["import { ConfigError, isCryptoAioError } from '../errors/error';\nimport {\n  NON_TERMINAL_STATES,\n  isTerminal,\n  type Fence,\n  type OperationClaim,\n  type OperationPatch,\n  type OperationRecord,\n} from '../store/types';\nimport { randomId } from '../util/bytes';\nimport type { ReadTarget } from './engine';\nimport { PRE_SIGNING_STATES, errorCode } from './engine-rules';\nimport type { MonitorDeps, ReadResolver, TargetResolver } from './monitor';\n\n/*\n * The monitor's background worker loop and startup recovery (`Monitor` delegates to\n * `Workers`). They check Operations through the monitor\n * (`MonitorChecks`) and write only through the engine.\n */\n\n/**\n * What `recover()` did. The counts are per Operation, except `reconciled`, and they\n * overlap: an Operation whose resend was attempted and whose check then failed counts in\n * both `rebroadcast` and `failed`.\n */\nexport interface RecoveryReport {\n  /**\n   * `signed` or ambiguously `submitted` Operations whose stored bytes were sent again:\n   * attempted resends, including ones the node refused or whose outcome is unknown.\n   */\n  readonly rebroadcast: number;\n  /** Operations checked on chain after any resend. */\n  readonly checked: number;\n  /** Operations that need a caller (see `recovery.skipped`); never resent or checked. */\n  readonly skipped: number;\n  /** Operations whose target could not be rebuilt, or whose resend or check threw. */\n  readonly failed: number;\n  /** Leaked nonce values that reconciliation returned for reuse (across all wallets). */\n  readonly reconciled: number;\n}\n\nexport interface WorkerOptions {\n  /** Default: a random id per `start` call. */\n  readonly workerId?: string;\n  readonly signal?: AbortSignal;\n  /** How many due Operations one pass claims. Default: 50. */\n  readonly batch?: number;\n}\n\nconst DEFAULT_BATCH = 50;\n/** How many Operations' reported gaps a monitor remembers (`nonce.gap` is at-least-once). */\nconst GAP_MEMORY = 10_000;\n\n/** What the worker loop and recovery use of the monitor's own checks. */\nexport interface MonitorChecks {\n  checkPass(\n    target: ReadTarget,\n    op: OperationRecord,\n    fence?: Fence,\n    signal?: AbortSignal,\n  ): Promise<{ readonly record: OperationRecord; readonly stale: boolean }>;\n  check(\n    target: ReadTarget,\n    op: OperationRecord,\n    fence?: Fence,\n    signal?: AbortSignal,\n  ): Promise<OperationRecord>;\n  find(ref: string): Promise<OperationRecord | null>;\n}\n\n/** Worker passes and startup recovery for one monitor (see `Monitor`). */\nexport class Workers {\n  /**\n   * Per Operation, the expected nonces a `nonce.gap` was already emitted for; least\n   * recently reported first, capped at `GAP_MEMORY` Operations.\n   */\n  readonly #gaps = new Map<string, Set<string>>();\n\n  constructor(\n    private readonly deps: MonitorDeps,\n    private readonly monitor: MonitorChecks,\n  ) {}\n\n  /**\n   * One worker pass: claims up to `batch` due Operations, checks each under its claim fence\n   * (a stale worker's writes fail), then releases the claim. Every claimed Operation\n   * that stays live leaves the pass scheduled a poll interval ahead, including when its\n   * check threw, its view was stale or its all-rejected verdict could not run, so no worker\n   * claims it again before then. A stale view also skips gap handling and reconciliation.\n   * `signal` bounds each check and its lease wait; once it aborts, the Operations not yet\n   * checked are only released, still due, for another worker. Returns how many Operations\n   * it claimed.\n   */\n  async runOnce(options: {\n    readonly workerId: string;\n    readonly batch?: number;\n    readonly signal?: AbortSignal;\n  }): Promise<number> {\n    const { signal } = options;\n    if (signal?.aborted) return 0;\n    const claimed = await this.deps.stores.operations.claimDue(\n      this.deps.namespace,\n      options.workerId,\n      this.deps.clock.now(),\n      this.deps.lifecycle().claimLeaseMs,\n      options.batch ?? DEFAULT_BATCH,\n    );\n    const reads = this.#passResolver(this.deps.resolveRead);\n    const writes = this.#passResolver(this.deps.resolveTarget);\n    for (const op of claimed) {\n      const fence: Fence = { claimToken: (op.claim as OperationClaim).token };\n      if (!signal?.aborted) await this.#process(reads, writes, op, fence, signal);\n      await this.deps.stores.operations\n        .releaseClaim(this.deps.namespace, op.id, fence)\n        .catch((error: unknown) =>\n          this.deps.log.debug('claim already lost', {\n            operationId: op.id,\n            code: errorCode(error),\n          }),\n        );\n    }\n    return claimed.length;\n  }\n\n  /** One claimed Operation of a worker pass (see `runOnce`). */\n  async #process(\n    reads: ReadResolver,\n    writes: TargetResolver,\n    op: OperationRecord,\n    fence: Fence,\n    signal: AbortSignal | undefined,\n  ): Promise<void> {\n    const started = this.deps.clock.now();\n    let current: OperationRecord | undefined;\n    try {\n      const target = await this.#resolved(reads, op);\n      const pass = await this.monitor.checkPass(target, op, fence, signal);\n      current = pass.record;\n      if (!pass.stale) await this.#detectNonceGap(target, current, writes);\n    } catch (error) {\n      // An abort mid-check is an expected shutdown, not a failure.\n      this.deps.log[signal?.aborted ? 'debug' : 'warn'](\n        signal?.aborted ? 'monitor check stopped' : 'monitor check failed',\n        { operationId: op.id, code: errorCode(error) },\n      );\n    }\n    const scheduled =\n      current !== undefined &&\n      (isTerminal(current.state) ||\n        (current.nextCheckAt !== undefined && current.nextCheckAt > started));\n    if (!scheduled) await this.#reschedule(op.id, fence, started);\n  }\n\n  /**\n   * Runs worker passes until `signal` aborts. Any number of workers, in any number of\n   * processes, may run: claims keep them apart. A full batch is followed by the next pass at\n   * once, anything less by a poll-interval sleep. A failed pass (e.g. a store outage) is\n   * logged by code and retried after the sleep.\n   */\n  async start(options: WorkerOptions = {}): Promise<void> {\n    const workerId = options.workerId ?? randomId('worker');\n    const batch = options.batch ?? DEFAULT_BATCH;\n    const { signal } = options;\n    while (!signal?.aborted) {\n      let processed = 0;\n      try {\n        processed = await this.runOnce({\n          workerId,\n          batch,\n          ...(signal ? { signal } : {}),\n        });\n      } catch (error) {\n        this.deps.log.warn('monitor worker pass failed', {\n          workerId,\n          code: errorCode(error),\n        });\n      }\n      if (processed > 0 && processed >= batch) continue;\n      try {\n        await this.deps.clock.sleep(this.deps.lifecycle().pollIntervalMs, signal);\n      } catch {\n        return;\n      }\n    }\n  }\n\n  /**\n   * Startup recovery for this namespace; it never signs. `signed` and ambiguously\n   * `submitted` Operations resend their stored raw bytes; every other signed-or-later live\n   * Operation is checked. `created`, `prepared`, `awaiting-signature` and `stalled` ones need\n   * a caller and are reported through `recovery.skipped` (codes and states only). Then each\n   * wallet with a live Operation has its nonces reconciled under its address lease. A\n   * failure is logged by code and counted, and the rest go on. `signal` stops recovery\n   * between Operations and bounds each check and lease wait. Known gap: a `signed` or\n   * ambiguous Operation whose wallet-bound target cannot be resolved is counted `failed`\n   * without its check, although the check needs no wallet.\n   */\n  async recover(\n    options: { readonly signal?: AbortSignal } = {},\n  ): Promise<RecoveryReport> {\n    const { signal } = options;\n    const { namespace } = this.deps;\n    const live = await this.deps.stores.operations.list({\n      namespace,\n      states: NON_TERMINAL_STATES,\n    });\n    const reads = this.#passResolver(this.deps.resolveRead);\n    const writes = this.#passResolver(this.deps.resolveTarget);\n    let rebroadcast = 0;\n    let checked = 0;\n    let skipped = 0;\n    let failed = 0;\n    let reconciled = 0;\n    const skip = (op: OperationRecord, reason: string) => {\n      skipped += 1;\n      this.deps.events.emit('recovery.skipped', {\n        namespace,\n        operationId: op.id,\n        state: op.state,\n        reason,\n      });\n    };\n    for (const op of live) {\n      if (signal?.aborted) break;\n      if (PRE_SIGNING_STATES.has(op.state)) {\n        skip(op, 'CALLER_ACTION_REQUIRED');\n        continue;\n      }\n      if (op.state === 'stalled') {\n        skip(op, 'STALLED');\n        continue;\n      }\n      try {\n        const target = await this.#resolved(reads, op);\n        let current = op;\n        if (\n          op.state === 'signed' ||\n          (op.state === 'submitted' && op.ambiguous === true)\n        ) {\n          const writer = await this.#resolved(writes, op);\n          try {\n            current = await this.deps.engine.rebroadcast(writer, op.id, signal);\n          } catch (error) {\n            // A refusal or an unknown outcome is recorded on the Operation: check it next.\n            if (\n              !isCryptoAioError(error) ||\n              (error.category !== 'chain' && error.ambiguous !== true)\n            )\n              throw error;\n            current = (await this.monitor.find(op.id)) ?? op;\n          }\n          rebroadcast += 1;\n        }\n        await this.monitor.check(target, current, undefined, signal);\n        checked += 1;\n      } catch (error) {\n        failed += 1;\n        this.deps.log.warn('recovery of an operation failed', {\n          operationId: op.id,\n          code: errorCode(error),\n        });\n      }\n    }\n    const wallets = new Map<string, OperationRecord>();\n    for (const op of live) {\n      const key = [op.context.chain, op.context.network, op.intent.from].join('\\n');\n      if (!wallets.has(key)) wallets.set(key, op);\n    }\n    for (const op of wallets.values()) {\n      if (signal?.aborted) break;\n      try {\n        const writer = await this.#resolved(writes, op);\n        reconciled += (await this.deps.engine.reconcileNonces(writer, op, { signal }))\n          .length;\n      } catch (error) {\n        this.deps.log.warn('nonce reconciliation failed', {\n          operationId: op.id,\n          code: errorCode(error),\n        });\n      }\n    }\n    return { rebroadcast, checked, skipped, failed, reconciled };\n  }\n\n  /**\n   * `resolve` for one pass: each execution context's target is rebuilt at most once, and\n   * only when first asked for (a wallet-bound one only by a write that needs it).\n   */\n  #passResolver<T>(\n    resolve: (op: OperationRecord) => Promise<T | undefined>,\n  ): (op: OperationRecord) => Promise<T | undefined> {\n    const targets = new Map<string, Promise<T | undefined>>();\n    return (op) => {\n      let target = targets.get(op.context.configHash);\n      if (!target) {\n        target = resolve(op);\n        targets.set(op.context.configHash, target);\n      }\n      return target;\n    };\n  }\n\n  async #resolved<T>(\n    resolve: (op: OperationRecord) => Promise<T | undefined>,\n    op: OperationRecord,\n  ): Promise<T> {\n    const target = await resolve(op);\n    if (!target) {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        `the target of operation '${op.id}' cannot be rebuilt from its context`,\n      );\n    }\n    return target;\n  }\n\n  /**\n   * Leaves a claimed, live Operation scheduled a poll interval ahead, unless it ended,\n   * another worker took it over or a writer scheduled it meanwhile. A pre-signing Operation\n   * is never scheduled (callers drive it), so it is unscheduled instead. Best effort.\n   */\n  async #reschedule(id: string, fence: Fence, started: number): Promise<void> {\n    try {\n      for (let tries = 0; tries < 3; tries++) {\n        const fresh = await this.deps.stores.operations.get(this.deps.namespace, id);\n        if (\n          !fresh ||\n          isTerminal(fresh.state) ||\n          fresh.claim?.token !== fence.claimToken ||\n          (fresh.nextCheckAt !== undefined && fresh.nextCheckAt > started)\n        )\n          return;\n        const patch: OperationPatch = PRE_SIGNING_STATES.has(fresh.state)\n          ? { clear: ['nextCheckAt'] }\n          : { nextCheckAt: this.deps.clock.now() + this.deps.lifecycle().pollIntervalMs };\n        try {\n          await this.deps.engine.update(fresh, patch, fence);\n          return;\n        } catch (error) {\n          if (!isCryptoAioError(error, 'VERSION_CONFLICT')) throw error;\n        }\n      }\n    } catch (error) {\n      this.deps.log.debug('could not reschedule a claimed operation', {\n        operationId: id,\n        code: errorCode(error),\n      });\n    }\n  }\n\n  /**\n   * `nonce.gap`, once per (Operation, expected nonce): a `submitted` Operation has waited\n   * longer than `droppedGracePeriodMs` since its active Attempt was first seen or sent, and\n   * the chain's pending nonce is still below its own (a lower nonce is missing\n   * even from the mempool, so congestion alone is no gap). It names the live Operation\n   * holding the expected nonce, when one exists. Every such pass then reconciles the wallet's nonces, trying the lease\n   * once (never a filler transaction): a leaked value goes back for the next transfer.\n   * Only that write resolves the wallet-bound target (`writes`).\n   */\n  async #detectNonceGap(\n    target: ReadTarget,\n    op: OperationRecord,\n    writes: TargetResolver,\n  ): Promise<void> {\n    const { sequence } = target.pooled.driver;\n    if (op.state !== 'submitted' || op.reservation?.kind !== 'nonce' || !sequence) {\n      this.#gaps.delete(op.id);\n      return;\n    }\n    const attempt = op.attempts.find((a) => a.id === op.activeAttemptId);\n    const observation = attempt\n      ? await this.deps.stores.operations.getObservation(attempt.id)\n      : null;\n    // Not `lastBroadcastAt`, which every resend of a dropped Attempt refreshes.\n    const since = observation?.firstSeenAt ?? attempt?.createdAt ?? op.createdAt;\n    if (this.deps.clock.now() - since < this.deps.lifecycle().droppedGracePeriodMs)\n      return;\n    const expected = await sequence.pending(op.intent.from);\n    if (expected >= op.reservation.nonce) return;\n    const reported = this.#gaps.get(op.id) ?? new Set<string>();\n    this.#gaps.delete(op.id);\n    this.#gaps.set(op.id, reported);\n    if (this.#gaps.size > GAP_MEMORY) {\n      const oldest = this.#gaps.keys().next().value;\n      if (oldest !== undefined) this.#gaps.delete(oldest);\n    }\n    if (!reported.has(expected.toString())) {\n      reported.add(expected.toString());\n      const blocking = (\n        await this.deps.stores.operations.list({\n          namespace: this.deps.namespace,\n          chain: op.context.chain,\n          network: op.context.network,\n          from: op.intent.from,\n          states: NON_TERMINAL_STATES,\n        })\n      ).find((o) => o.reservation?.kind === 'nonce' && o.reservation.nonce === expected);\n      this.deps.events.emit('nonce.gap', {\n        namespace: this.deps.namespace,\n        chain: op.context.chain,\n        network: op.context.network,\n        operationId: op.id,\n        expected: expected.toString(),\n        ...(blocking ? { blockingOperationId: blocking.id } : {}),\n      });\n    }\n    try {\n      const writer = await this.#resolved(writes, op);\n      await this.deps.engine.reconcileNonces(writer, op, { acquireTimeoutMs: 0 });\n    } catch (error) {\n      const busy = isCryptoAioError(error, 'SEQUENCE_BUSY');\n      this.deps.log[busy ? 'debug' : 'warn']('nonce reconciliation did not run', {\n        operationId: op.id,\n        code: errorCode(error),\n      });\n    }\n  }\n}\n"]}

package/dist/core/model/address.d.ts

@@ -0,0 +1,32 @@
+export interface NormalizedAddress {
+    readonly canonical: string;
+    readonly display: string;
+    /**
+     * Chain-specific meaning of a recipient address. It reaches drivers in
+     * `DriverOutput.variant` and is part of the intent hash, so it must hold only JSON scalars
+     * (strings, finite numbers, booleans, `null`) under string keys, and should contain only
+     * semantic fields that change what the transfer does (for example TON's `bounceable`),
+     * never encoding-only choices such as a display alphabet. Omit it, or leave it empty,
+     * when the address has no such meaning: an empty variant is no variant.
+     */
+    readonly variant?: Readonly<Record<string, unknown>>;
+}
+export type AddressFormatter = (address: NormalizedAddress, options?: Readonly<Record<string, unknown>>) => string;
+/** A chain-bound address. Equality uses `canonical`; `variant` keeps chain-specific meaning. */
+export declare class Address implements NormalizedAddress {
+    #private;
+    readonly chain: string;
+    readonly canonical: string;
+    readonly display: string;
+    readonly variant?: Readonly<Record<string, unknown>>;
+    constructor(chain: string, normalized: NormalizedAddress, format?: AddressFormatter);
+    format(options?: Readonly<Record<string, unknown>>): string;
+    equals(other: Address | NormalizedAddress | string): boolean;
+    toString(): string;
+    toJSON(): {
+        chain: string;
+        canonical: string;
+        display: string;
+        variant?: Readonly<Record<string, unknown>>;
+    };
+}

package/dist/core/model/address.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Address = void 0;
+/** A chain-bound address. Equality uses `canonical`; `variant` keeps chain-specific meaning. */
+class Address {
+    chain;
+    canonical;
+    display;
+    variant;
+    #format;
+    constructor(chain, normalized, format) {
+        this.chain = chain;
+        this.canonical = normalized.canonical;
+        this.display = normalized.display;
+        if (normalized.variant)
+            this.variant = Object.freeze({ ...normalized.variant });
+        this.#format = format;
+        Object.freeze(this);
+    }
+    format(options) {
+        return this.#format ? this.#format(this, options) : this.display;
+    }
+    equals(other) {
+        if (typeof other === 'string')
+            return other === this.canonical;
+        if (other instanceof Address && other.chain !== this.chain)
+            return false;
+        return other.canonical === this.canonical;
+    }
+    toString() {
+        return this.display;
+    }
+    toJSON() {
+        return {
+            chain: this.chain,
+            canonical: this.canonical,
+            display: this.display,
+            ...(this.variant ? { variant: this.variant } : {}),
+        };
+    }
+}
+exports.Address = Address;
+//# sourceMappingURL=address.js.map

package/dist/core/model/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../../src/core/model/address.ts"],"names":[],"mappings":";;;AAmBA,gGAAgG;AAChG,MAAa,OAAO;IACT,KAAK,CAAS;IACd,SAAS,CAAS;IAClB,OAAO,CAAS;IAChB,OAAO,CAAqC;IAC5C,OAAO,CAAoB;IAEpC,YAAY,KAAa,EAAE,UAA6B,EAAE,MAAyB;QACjF,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;QAClC,IAAI,UAAU,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,MAAM,CAAC,OAA2C;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IACnE,CAAC;IAED,MAAM,CAAC,KAA2C;QAChD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,KAAK,IAAI,CAAC,SAAS,CAAC;QAC/D,IAAI,KAAK,YAAY,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzE,OAAO,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,CAAC;IAC5C,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,MAAM;QAMJ,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC;IACJ,CAAC;CACF;AA3CD,0BA2CC","sourcesContent":["export interface NormalizedAddress {\n  readonly canonical: string;\n  readonly display: string;\n  /**\n   * Chain-specific meaning of a recipient address. It reaches drivers in\n   * `DriverOutput.variant` and is part of the intent hash, so it must hold only JSON scalars\n   * (strings, finite numbers, booleans, `null`) under string keys, and should contain only\n   * semantic fields that change what the transfer does (for example TON's `bounceable`),\n   * never encoding-only choices such as a display alphabet. Omit it, or leave it empty,\n   * when the address has no such meaning: an empty variant is no variant.\n   */\n  readonly variant?: Readonly<Record<string, unknown>>;\n}\n\nexport type AddressFormatter = (\n  address: NormalizedAddress,\n  options?: Readonly<Record<string, unknown>>,\n) => string;\n\n/** A chain-bound address. Equality uses `canonical`; `variant` keeps chain-specific meaning. */\nexport class Address implements NormalizedAddress {\n  readonly chain: string;\n  readonly canonical: string;\n  readonly display: string;\n  readonly variant?: Readonly<Record<string, unknown>>;\n  readonly #format?: AddressFormatter;\n\n  constructor(chain: string, normalized: NormalizedAddress, format?: AddressFormatter) {\n    this.chain = chain;\n    this.canonical = normalized.canonical;\n    this.display = normalized.display;\n    if (normalized.variant) this.variant = Object.freeze({ ...normalized.variant });\n    this.#format = format;\n    Object.freeze(this);\n  }\n\n  format(options?: Readonly<Record<string, unknown>>): string {\n    return this.#format ? this.#format(this, options) : this.display;\n  }\n\n  equals(other: Address | NormalizedAddress | string): boolean {\n    if (typeof other === 'string') return other === this.canonical;\n    if (other instanceof Address && other.chain !== this.chain) return false;\n    return other.canonical === this.canonical;\n  }\n\n  toString(): string {\n    return this.display;\n  }\n\n  toJSON(): {\n    chain: string;\n    canonical: string;\n    display: string;\n    variant?: Readonly<Record<string, unknown>>;\n  } {\n    return {\n      chain: this.chain,\n      canonical: this.canonical,\n      display: this.display,\n      ...(this.variant ? { variant: this.variant } : {}),\n    };\n  }\n}\n"]}

package/dist/core/model/amount.d.ts

@@ -0,0 +1,25 @@
+import type { AssetId, AssetInfo } from './asset';
+export type AmountInput = bigint | string | Amount;
+/** An exact, non-negative quantity of one asset in base units. Never floating point. */
+export declare class Amount {
+    readonly base: bigint;
+    readonly asset: AssetInfo;
+    private constructor();
+    static fromBase(base: bigint, asset: AssetInfo): Amount;
+    static parse(value: string, asset: AssetInfo): Amount;
+    static from(input: unknown, asset: AssetInfo): Amount;
+    get decimals(): number;
+    isZero(): boolean;
+    toDecimalString(): string;
+    format(): string;
+    plus(other: Amount): Amount;
+    minus(other: Amount): Amount;
+    compare(other: Amount): -1 | 0 | 1;
+    equals(other: Amount): boolean;
+    toJSON(): {
+        base: string;
+        asset: AssetId;
+    };
+    toString(): string;
+    private assertSameAsset;
+}

package/dist/core/model/amount.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Amount = void 0;
+const error_1 = require("../errors/error");
+const DECIMAL = /^(0|[1-9][0-9]*)(\.[0-9]+)?$/;
+function invalid(message) {
+    return new error_1.ValidationError('INVALID_AMOUNT', message);
+}
+/** An exact, non-negative quantity of one asset in base units. Never floating point. */
+class Amount {
+    base;
+    asset;
+    constructor(base, asset) {
+        this.base = base;
+        this.asset = asset;
+        Object.freeze(this);
+    }
+    static fromBase(base, asset) {
+        if (typeof base !== 'bigint')
+            throw invalid('base amount must be a bigint');
+        if (base < 0n)
+            throw invalid('amounts cannot be negative');
+        return new Amount(base, asset);
+    }
+    static parse(value, asset) {
+        if (typeof value !== 'string' || !DECIMAL.test(value)) {
+            throw invalid(`'${String(value)}' is not a plain decimal string (expected digits with an optional fractional part, e.g. "1.25")`);
+        }
+        const { decimals, symbol } = asset.metadata;
+        const [whole = '0', fraction = ''] = value.split('.');
+        if (fraction.length > decimals) {
+            throw invalid(`'${value}' has ${fraction.length} fractional digits but ${symbol} has ${decimals} decimals`);
+        }
+        const scale = 10n ** BigInt(decimals);
+        const fractional = fraction.length > 0 ? BigInt(fraction.padEnd(decimals, '0')) : 0n;
+        return new Amount(BigInt(whole) * scale + fractional, asset);
+    }
+    static from(input, asset) {
+        if (input instanceof Amount) {
+            if (input.asset.id !== asset.id) {
+                throw invalid(`amount is denominated in '${input.asset.id}', expected '${asset.id}'`);
+            }
+            return input;
+        }
+        if (typeof input === 'bigint')
+            return Amount.fromBase(input, asset);
+        if (typeof input === 'string')
+            return Amount.parse(input, asset);
+        if (typeof input === 'number') {
+            throw invalid('JavaScript numbers are not accepted for amounts; use a bigint (base units) or a decimal string');
+        }
+        throw invalid(`unsupported amount input of type ${input === null ? 'null' : typeof input}`);
+    }
+    get decimals() {
+        return this.asset.metadata.decimals;
+    }
+    isZero() {
+        return this.base === 0n;
+    }
+    toDecimalString() {
+        const decimals = this.decimals;
+        if (decimals === 0)
+            return this.base.toString();
+        const digits = this.base.toString().padStart(decimals + 1, '0');
+        const whole = digits.slice(0, -decimals);
+        const fraction = digits.slice(-decimals).replace(/0+$/, '');
+        return fraction ? `${whole}.${fraction}` : whole;
+    }
+    format() {
+        return `${this.toDecimalString()} ${this.asset.metadata.symbol}`;
+    }
+    plus(other) {
+        this.assertSameAsset(other);
+        return new Amount(this.base + other.base, this.asset);
+    }
+    minus(other) {
+        this.assertSameAsset(other);
+        if (other.base > this.base)
+            throw invalid('result would be negative');
+        return new Amount(this.base - other.base, this.asset);
+    }
+    compare(other) {
+        this.assertSameAsset(other);
+        return this.base < other.base ? -1 : this.base > other.base ? 1 : 0;
+    }
+    equals(other) {
+        return other.asset.id === this.asset.id && other.base === this.base;
+    }
+    toJSON() {
+        return { base: this.base.toString(), asset: this.asset.id };
+    }
+    toString() {
+        return this.format();
+    }
+    assertSameAsset(other) {
+        if (other.asset.id !== this.asset.id) {
+            throw invalid(`cannot combine '${this.asset.id}' with '${other.asset.id}'`);
+        }
+    }
+}
+exports.Amount = Amount;
+//# sourceMappingURL=amount.js.map

package/dist/core/model/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../../src/core/model/amount.ts"],"names":[],"mappings":"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","sourcesContent":["import { ValidationError } from '../errors/error';\nimport type { AssetId, AssetInfo } from './asset';\n\nexport type AmountInput = bigint | string | Amount;\n\nconst DECIMAL = /^(0|[1-9][0-9]*)(\\.[0-9]+)?$/;\n\nfunction invalid(message: string): ValidationError {\n  return new ValidationError('INVALID_AMOUNT', message);\n}\n\n/** An exact, non-negative quantity of one asset in base units. Never floating point. */\nexport class Amount {\n  private constructor(\n    readonly base: bigint,\n    readonly asset: AssetInfo,\n  ) {\n    Object.freeze(this);\n  }\n\n  static fromBase(base: bigint, asset: AssetInfo): Amount {\n    if (typeof base !== 'bigint') throw invalid('base amount must be a bigint');\n    if (base < 0n) throw invalid('amounts cannot be negative');\n    return new Amount(base, asset);\n  }\n\n  static parse(value: string, asset: AssetInfo): Amount {\n    if (typeof value !== 'string' || !DECIMAL.test(value)) {\n      throw invalid(\n        `'${String(value)}' is not a plain decimal string (expected digits with an optional fractional part, e.g. \"1.25\")`,\n      );\n    }\n    const { decimals, symbol } = asset.metadata;\n    const [whole = '0', fraction = ''] = value.split('.');\n    if (fraction.length > decimals) {\n      throw invalid(\n        `'${value}' has ${fraction.length} fractional digits but ${symbol} has ${decimals} decimals`,\n      );\n    }\n    const scale = 10n ** BigInt(decimals);\n    const fractional = fraction.length > 0 ? BigInt(fraction.padEnd(decimals, '0')) : 0n;\n    return new Amount(BigInt(whole) * scale + fractional, asset);\n  }\n\n  static from(input: unknown, asset: AssetInfo): Amount {\n    if (input instanceof Amount) {\n      if (input.asset.id !== asset.id) {\n        throw invalid(\n          `amount is denominated in '${input.asset.id}', expected '${asset.id}'`,\n        );\n      }\n      return input;\n    }\n    if (typeof input === 'bigint') return Amount.fromBase(input, asset);\n    if (typeof input === 'string') return Amount.parse(input, asset);\n    if (typeof input === 'number') {\n      throw invalid(\n        'JavaScript numbers are not accepted for amounts; use a bigint (base units) or a decimal string',\n      );\n    }\n    throw invalid(\n      `unsupported amount input of type ${input === null ? 'null' : typeof input}`,\n    );\n  }\n\n  get decimals(): number {\n    return this.asset.metadata.decimals;\n  }\n\n  isZero(): boolean {\n    return this.base === 0n;\n  }\n\n  toDecimalString(): string {\n    const decimals = this.decimals;\n    if (decimals === 0) return this.base.toString();\n    const digits = this.base.toString().padStart(decimals + 1, '0');\n    const whole = digits.slice(0, -decimals);\n    const fraction = digits.slice(-decimals).replace(/0+$/, '');\n    return fraction ? `${whole}.${fraction}` : whole;\n  }\n\n  format(): string {\n    return `${this.toDecimalString()} ${this.asset.metadata.symbol}`;\n  }\n\n  plus(other: Amount): Amount {\n    this.assertSameAsset(other);\n    return new Amount(this.base + other.base, this.asset);\n  }\n\n  minus(other: Amount): Amount {\n    this.assertSameAsset(other);\n    if (other.base > this.base) throw invalid('result would be negative');\n    return new Amount(this.base - other.base, this.asset);\n  }\n\n  compare(other: Amount): -1 | 0 | 1 {\n    this.assertSameAsset(other);\n    return this.base < other.base ? -1 : this.base > other.base ? 1 : 0;\n  }\n\n  equals(other: Amount): boolean {\n    return other.asset.id === this.asset.id && other.base === this.base;\n  }\n\n  toJSON(): { base: string; asset: AssetId } {\n    return { base: this.base.toString(), asset: this.asset.id };\n  }\n\n  toString(): string {\n    return this.format();\n  }\n\n  private assertSameAsset(other: Amount): void {\n    if (other.asset.id !== this.asset.id) {\n      throw invalid(`cannot combine '${this.asset.id}' with '${other.asset.id}'`);\n    }\n  }\n}\n"]}

package/dist/core/model/asset.d.ts

@@ -0,0 +1,28 @@
+export type AssetRef = 'native' | {
+    readonly standard: string;
+    readonly contract: string;
+};
+export type TokenRef = Exclude<AssetRef, 'native'>;
+export type AssetId = string;
+export interface AssetMetadata {
+    readonly symbol: string;
+    readonly decimals: number;
+    readonly name?: string;
+}
+export interface AssetInfo {
+    readonly id: AssetId;
+    readonly chain: string;
+    readonly network: string;
+    readonly ref: AssetRef;
+    readonly metadata: AssetMetadata;
+}
+export declare function assetId(chain: string, network: string, ref: AssetRef): AssetId;
+export declare function isAssetId(value: string): boolean;
+export declare function parseAssetId(id: string): {
+    chain: string;
+    network: string;
+    ref: AssetRef;
+};
+export declare function sameAssetRef(a: AssetRef, b: AssetRef): boolean;
+/** Returns a reason when metadata is unusable, otherwise `undefined`. */
+export declare function metadataProblem(metadata: AssetMetadata): string | undefined;