@usearete/automations 0.0.0-stage → 0.44.1

package/dist/index.d.ts

@@ -0,0 +1,1379 @@
+import { ExecutionIntentV1, ProtocolPreparedTransaction, ProtocolTransactionFormat, RichUpdate, Update, StackDefinition, ConnectedArete, ProtocolTypeMap, ProtocolDefinition, ProtocolStepAvailability, ProtocolIntentState, ProtocolEventsOptions, ProtocolEventSubscription, ProtocolParticipantDetail } from '@usearete/sdk';
+
+/** One top-level instruction: indexes into the message's account keys (static keys, then lookup-table writable entries, then read-only ones). */
+interface CompiledInstruction {
+    readonly programIndex: number;
+    readonly accounts: readonly number[];
+    readonly data: Uint8Array;
+}
+/** One address lookup table a v0 message loads from. */
+interface Lookup {
+    readonly table: string;
+    readonly writable: readonly number[];
+    readonly readonly: readonly number[];
+}
+/** A decoded wire transaction. */
+interface DecodedTransaction {
+    /** `null` for legacy messages, else the message version. */
+    readonly version: 0 | 1 | null;
+    /** Signature slots, in key order; all zero when not signed yet. */
+    readonly signatures: readonly Uint8Array[];
+    /** Where the first signature slot starts in the wire bytes. */
+    readonly signatureOffset: number;
+    /** The byte range every signer signs, `[start, end)`. */
+    readonly message: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly requiredSignatures: number;
+    readonly staticKeys: readonly string[];
+    /** Indexes of the static keys the message marks writable. */
+    readonly writableStatic: readonly number[];
+    /** The program of each top-level instruction, in order. */
+    readonly instructionPrograms: readonly string[];
+    readonly instructions: readonly CompiledInstruction[];
+    readonly lookups: readonly Lookup[];
+}
+declare class TransactionDecodeError extends Error {
+    constructor(message: string);
+}
+/** Decode a legacy, v0 or v1 wire transaction. */
+declare function decodeTransaction(bytes: Uint8Array): DecodedTransaction;
+
+/**
+ * Instructions that hand control of the signer's funds to someone else
+ * without moving a balance.
+ *
+ * The policy's caps measure balance changes, and some instructions change no
+ * balance yet give the funds away: a token delegation (`approve`), a new
+ * owner or authority (`setAuthority`, System `assign`), or lamports leaving
+ * an account the signer controls that is not the signer's own (a nonce or
+ * stake withdrawal). This module names those instructions in the System, SPL
+ * Token, Token-2022, upgradeable loader and stake programs when the signer
+ * takes part in them (signs, or is one of their accounts).
+ *
+ * Top-level instructions are read from the wire bytes. Inner (CPI)
+ * instructions are read from a simulation when the RPC returns them.
+ *
+ * A token account closed to an account other than the signer is not refused;
+ * its lamports count as SOL leaving the signer.
+ */
+
+/** An instruction the signer must not sign. */
+interface AuthorityFinding {
+    readonly programId: string;
+    readonly instruction: string;
+    /** Whether it is an inner (CPI) instruction from the simulation. */
+    readonly inner: boolean;
+    readonly reason: string;
+}
+
+/**
+ * A Solana JSON-RPC endpoint the policy simulates prepared transactions on.
+ *
+ * The summary calls two methods: `getMultipleAccounts` (lookup tables and
+ * the pre-state of written accounts) and `simulateTransaction` (with the
+ * written accounts' post-state and inner instructions). `call` resolves
+ * with the JSON-RPC `result` and rejects on a JSON-RPC `error`.
+ */
+interface Simulator {
+    call(method: string, params: readonly unknown[]): Promise<unknown>;
+}
+interface RpcSimulatorOptions {
+    /** Defaults to the global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Extra request headers, for example an RPC provider's API key. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * How long one call may take, request and response body together, in
+     * milliseconds. Defaults to 15 seconds. A call that runs out fails, so the
+     * transaction's effect is unknown and the policy refuses it.
+     */
+    readonly timeoutMs?: number;
+}
+/** A {@link Simulator} over a JSON-RPC URL. */
+declare function rpcSimulator(url: string, options?: RpcSimulatorOptions): Simulator;
+
+/**
+ * What a prepared step's transactions do, read from the transactions
+ * themselves rather than from the labels a prepare returns:
+ *
+ * - the programs each transaction invokes;
+ * - the accounts it writes (static keys, plus address lookup table entries,
+ *   resolved when a simulator is available);
+ * - the signatures it carries and the ones still required;
+ * - with a simulator, the signer's SOL and token balance changes from a
+ *   simulation of the exact bytes, the simulation error and the tail of its
+ *   logs;
+ * - the instructions that would hand control of the signer's funds to
+ *   someone else (see `authority.ts`): read from the top-level instructions
+ *   always, and from the inner instructions when the simulation returns
+ *   them.
+ *
+ * Without a simulator the balance changes are reported as unavailable,
+ * never as zero.
+ */
+
+/** A prepare result, as far as the summary reads it. */
+interface PreparedStepLike {
+    readonly intent?: unknown;
+    readonly transactions: readonly {
+        readonly index?: number;
+        readonly transactionBase64: string;
+    }[];
+    /** Role-labelled instructions, when the prepare returns them. */
+    readonly anatomy?: unknown;
+    /** The server's simulation metrics, when the prepare returns them. */
+    readonly simulation?: unknown;
+}
+interface TokenDelta {
+    readonly mint: string;
+    /** Base units, signed: negative when tokens leave the signer. */
+    readonly amount: string;
+}
+interface SignerEffectSummary {
+    /** Whether every balance change of the signer is known. */
+    readonly known: boolean;
+    readonly solLamports?: string | null;
+    readonly sol?: string | null;
+    readonly tokens?: TokenDelta[];
+    readonly closedAccountLamportsOut?: string | null;
+    readonly unresolvedLookupTables?: string[];
+    readonly omittedAccounts?: number;
+    readonly innerInstructionsChecked?: boolean;
+    readonly preStateSlot?: number | null;
+    readonly simulatedSlot?: number | null;
+    /** Why the simulation could not run. */
+    readonly error?: string;
+}
+interface TransactionSummary {
+    readonly index: number;
+    readonly version: 'legacy' | 'v0' | 'v1';
+    readonly feePayer: string | null;
+    readonly programs: Array<{
+        readonly programId: string;
+        readonly roles: string[];
+    }>;
+    readonly accountsWritten: string[];
+    readonly accountsWrittenComplete: boolean;
+    readonly unresolvedWritableAccounts: Array<{
+        readonly table: string;
+        readonly addressIndex: number;
+    }>;
+    readonly signatures: {
+        readonly required: string[];
+        readonly present: string[];
+        readonly missing: string[];
+    };
+    readonly serverSimulation: unknown;
+    readonly lookupTables?: Array<{
+        readonly table: string;
+        readonly writableEntries: number;
+        readonly readonlyEntries: number;
+    }>;
+    readonly signerEffect: SignerEffectSummary;
+    readonly simulation?: {
+        readonly err: unknown;
+        readonly logsTail: string[];
+    };
+    readonly unsafeInstructions: AuthorityFinding[];
+}
+interface PreparedSummary {
+    readonly signer: string;
+    readonly transactions: TransactionSummary[];
+    readonly programsInvoked: string[];
+    readonly signerBalanceChanges: {
+        readonly available: false;
+        readonly reason: string;
+    } | {
+        readonly available: true;
+        readonly complete: boolean;
+        readonly solLamports: string | null;
+        readonly sol: string | null;
+        readonly tokens: TokenDelta[];
+        readonly note: string;
+    };
+    readonly simulationErrors: Array<{
+        readonly transaction: number;
+        readonly err: unknown;
+        readonly dependsOnEarlierTransactions: boolean;
+    }>;
+    readonly signaturesStillRequired: string[];
+}
+/**
+ * The summary of a prepared step for `signer` (the wallet that signs).
+ * `simulator` adds the simulated balance changes.
+ */
+declare function summarizePrepared(prepared: PreparedStepLike, signer: string, simulator?: Simulator | null): Promise<PreparedSummary>;
+
+/**
+ * What a signer may sign for a user: the static policy.
+ *
+ * The rules, their names and the refusal shape match the Arete MCP server's
+ * local signer, and both implementations run the shared vectors in
+ * `test-vectors/signer-policy/`. The caps hold per transaction, measured by
+ * simulating the exact prepared bytes. Wrapped SOL counts against
+ * `maxSolPerTransaction`, as do the lamports of a token account closed to
+ * someone else. Instructions that hand control of the signer's funds to
+ * someone else (token approvals, authority changes, System assignments) are
+ * always refused, and so is any transaction whose effect on the signer
+ * could not be simulated.
+ */
+
+/** Clusters a policy allows when it does not list any. */
+declare const DEFAULT_CLUSTERS: readonly ["dev"];
+/**
+ * Every cluster a target can be: `dev` for a deployment in a dev environment
+ * (a fork of mainnet), `mainnet` for a published deployment.
+ */
+declare const KNOWN_CLUSTERS: readonly ["dev", "mainnet"];
+type Cluster = (typeof KNOWN_CLUSTERS)[number];
+/**
+ * Programs the transaction compiler adds around a step's own instructions
+ * (compute budget, memo, fee transfers, token accounts and wrapped SOL).
+ * They are always allowed; what they move is bounded by the SOL and token
+ * caps.
+ */
+declare const RUNTIME_PROGRAMS: readonly ["ComputeBudget111111111111111111111111111111", "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr", "Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo", "11111111111111111111111111111111", "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"];
+/** The fields of a policy, as an integrator writes them. */
+interface PolicyInput {
+    /** Deployments the signer may act in. Required, at least one. */
+    readonly deployments: readonly string[];
+    /** The most SOL one transaction may move out of the signer, in SOL. */
+    readonly maxSolPerTransaction: string | number;
+    /** Programs a transaction may invoke besides the runtime programs. Omit to allow any. */
+    readonly programs?: readonly string[] | null;
+    /**
+     * Base units per mint that one transaction may move out of the signer.
+     * A mint without a cap may not leave at all, so without this table no
+     * token may leave (wrapped SOL counts as SOL instead).
+     */
+    readonly maxTokenAmounts?: Readonly<Record<string, string | number | bigint>> | null;
+    /** Defaults to `dev`; mainnet only when listed. */
+    readonly clusters?: readonly Cluster[] | null;
+}
+/** A validated policy. */
+interface SignerPolicy {
+    readonly deployments: readonly string[];
+    readonly maxLamportsPerTransaction: bigint;
+    readonly programs: readonly string[] | null;
+    readonly maxTokenAmounts: ReadonlyMap<string, bigint> | null;
+    readonly clusters: readonly string[];
+    /** Whether the input listed `clusters` (rather than the default). */
+    readonly clustersListed: boolean;
+}
+/**
+ * Why a step was not signed. The first six are the signing policy's rules;
+ * the rest are the runtime's checks around the signer.
+ */
+type RefusalRule = 'deployments' | 'clusters' | 'programs' | 'authority' | 'maxSolPerTransaction' | 'maxTokenAmounts'
+/** The prepared transactions are not what the intent committed to. */
+ | 'intent_mismatch'
+/** The signer and the deployment share no transaction format, or the prepare used another. */
+ | 'transaction_format'
+/** The signer changed a message, another signature, or the signers. */
+ | 'signer_modified'
+/** The wallet's signature slot does not hold its valid signature. */
+ | 'signer_signature'
+/** The signer cannot sign for the wallet (no key, no session signer). */
+ | 'signer_unavailable'
+/** The wallet provider's own policy refused to sign. */
+ | 'provider_policy'
+/** The step moves more than the consent allows in one run, or an asset it sets no limit for. */
+ | 'consent_limit'
+/** The step would take the wallet past the consent's limit for its window. */
+ | 'consent_window';
+/** A policy refusal: the rule and why. */
+interface Refusal {
+    readonly rule: RefusalRule;
+    readonly reason: string;
+}
+declare class PolicyError extends Error {
+    constructor(message: string);
+}
+/** Validate a policy. Throws {@link PolicyError} naming the field at fault. */
+declare function definePolicy(input: PolicyInput): SignerPolicy;
+/** Whether the deployment and cluster are allowed, before preparing. `null` when they are. */
+declare function checkTarget(policy: SignerPolicy, deploymentId: string, cluster: string): Refusal | null;
+interface CheckPreparedInput {
+    /** The deployment the step was prepared in. */
+    readonly deploymentId: string;
+    /** The prepare result; its intent's deployment must match. */
+    readonly prepared: unknown;
+    /** The summary of the prepared step for the signer. */
+    readonly summary: PreparedSummary;
+    /** Whether the summary came from a simulation at all. */
+    readonly simulates: boolean;
+}
+/**
+ * Check a prepared step against the policy: the intent's deployment, every
+ * transaction's programs, the instructions that would hand over control of
+ * the signer's funds, and the simulated SOL and token outflows of the
+ * signer, per transaction. `null` when it may be signed.
+ */
+declare function checkPrepared(policy: SignerPolicy, input: CheckPreparedInput): Refusal | null;
+
+/**
+ * What a signer is given. Hand it copies and keep your own snapshot of the
+ * prepared transactions for `checkSignedTransactions`: `readonly` is not
+ * enforced at run time, and a signer that changed the objects it was given
+ * could change a shared baseline too. The runtime does this.
+ */
+interface SignTransactionsInput {
+    /** The wallet whose signature slot to fill. */
+    readonly wallet: string;
+    /** What the prepare committed to. */
+    readonly intent: ExecutionIntentV1;
+    /** The prepared transactions, base64 wire bytes, in intent order. */
+    readonly transactions: readonly ProtocolPreparedTransaction[];
+}
+/**
+ * Signs prepared protocol transactions for a wallet the backend controls by
+ * delegation (a dev keypair, an embedded-wallet provider, a KMS).
+ *
+ * A signer fills the wallet's signature slot of each transaction and
+ * nothing else: it must not change the message, add instructions, touch
+ * other signatures, or broadcast. The runtime does not trust this: it
+ * re-hashes every returned message against the intent and verifies the
+ * wallet's signature before anything is submitted.
+ */
+interface ProtocolSigner {
+    /** A short name for logs and refusals, for example `keypair` or `privy`. */
+    readonly kind: string;
+    /** Formats the signer can sign, in order of preference. */
+    readonly supportedTransactionFormats: readonly ProtocolTransactionFormat[];
+    /** Whether this signer can sign for `wallet` now. */
+    canSign(wallet: string): Promise<boolean>;
+    /** The signed transactions, base64 wire bytes, one per input in the same order. */
+    signTransactions(input: SignTransactionsInput): Promise<string[]>;
+    /**
+     * Whether the backend holds delegated access to `wallet`, and whether a
+     * provider-side policy bounds what it may sign. Granting consent warns
+     * when either is missing.
+     */
+    delegationStatus?(wallet: string): Promise<DelegationStatus>;
+}
+interface DelegationStatus {
+    readonly delegated: boolean;
+    readonly providerPolicy: boolean;
+    readonly detail?: string;
+}
+/**
+ * Thrown by a signer that declines to sign, for example because the wallet
+ * provider's own policy refused the transaction. The job ends `refused`
+ * with this rule instead of being retried.
+ */
+declare const REFUSAL_BRAND: unique symbol;
+declare class SignerRefusal extends Error {
+    readonly rule: 'provider_policy' | 'signer_unavailable';
+    /** Recognised across entry points: each bundle has its own copy of this class. */
+    readonly [REFUSAL_BRAND] = true;
+    constructor(message: string, rule?: 'provider_policy' | 'signer_unavailable');
+}
+/**
+ * Whether `error` is a {@link SignerRefusal}, including one thrown by a
+ * signer from another entry point (`@usearete/automations/privy` is a
+ * separate bundle, so `instanceof` would miss it).
+ */
+declare function isSignerRefusal(error: unknown): error is SignerRefusal;
+
+/** What the API prepares by default, then the fallback. */
+declare const DEFAULT_TRANSACTION_FORMATS: readonly ProtocolTransactionFormat[];
+/**
+ * The first format in `preferred` (the deployment's order) that the signer
+ * supports, or `null` when they share none.
+ */
+declare function negotiateTransactionFormat(signerFormats: readonly ProtocolTransactionFormat[], preferred?: readonly ProtocolTransactionFormat[]): ProtocolTransactionFormat | null;
+
+/**
+ * The exact-bytes checks around a delegated signer.
+ *
+ * Before signing, the prepared transactions must be the ones the intent
+ * committed to. After signing, every message must hash to the intent's
+ * `messageSha256`, every signature slot but the wallet's must be untouched,
+ * and the wallet's slot must hold the wallet's valid signature. A signer
+ * that adds a compute-budget instruction, re-encodes, or signs something
+ * else fails here, before anything is submitted.
+ */
+
+/**
+ * Whether the prepared transactions are what `intent` committed to, in the
+ * format that was asked for, with `wallet` as a required signer of each.
+ * `null` when they are.
+ */
+declare function checkPreparedAgainstIntent(input: {
+    readonly wallet: string;
+    readonly intent: ExecutionIntentV1;
+    readonly transactions: readonly ProtocolPreparedTransaction[];
+    readonly format: ProtocolTransactionFormat;
+}): Refusal | null;
+/**
+ * Whether `signed` is `prepared` with only the wallet's signature slot
+ * filled, by the wallet. `null` when it is.
+ *
+ * `prepared` is the baseline: pass a copy the signer never had, because a
+ * signer that can change the objects it was given could change the
+ * baseline too.
+ */
+declare function checkSignedTransactions(input: {
+    readonly wallet: string;
+    readonly intent: ExecutionIntentV1;
+    readonly prepared: readonly ProtocolPreparedTransaction[];
+    readonly signed: readonly string[];
+}): Refusal | null;
+
+/** A duration in milliseconds, or text such as `30s`, `10m`, `24h` or `7d`. */
+type Duration = number | `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`;
+declare function durationMs(duration: Duration): number;
+/** Wall-clock time and waiting, injectable for tests. */
+interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+declare const systemClock: Clock;
+type SchedulePeriod = 'minute' | 'hour' | 'day' | 'week' | 'month';
+/**
+ * A deterministic dispatch id for a scheduled run: the same name, period
+ * and time give the same id, so a cron that fires twice in one period is
+ * deduplicated. Times are UTC.
+ *
+ * `scheduleSlot('weekly-buy', 'week')` → `weekly-buy:2026-W43`.
+ */
+declare function scheduleSlot(name: string, period: SchedulePeriod, at?: Date | number): string;
+
+/** Where a trigger came from. */
+type TriggerSource = 'webhook' | 'stream' | 'dispatch' | 'view';
+/** One accepted trigger: a webhook delivery, a stream event or a dispatch. */
+interface Delivery {
+    /** Unique per trigger, namespaced by source (`webhook:…`, `stream:…`, `dispatch:…`, `view:…`). */
+    readonly id: string;
+    /** The handler name: an event name or a dispatch name. */
+    readonly name: string;
+    readonly source: TriggerSource;
+    readonly payload: unknown;
+    /** Milliseconds since the epoch. */
+    readonly receivedAt: number;
+}
+/** A step a handler asks for. */
+interface StepRequest {
+    readonly step: string;
+    readonly wallet: string;
+    /** The instance, for steps that act on one; omitted for create steps. */
+    readonly instance?: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Skip the step when the same (wallet, step) completed this recently, in milliseconds. */
+    readonly cooldownMs?: number;
+}
+/** Delivery jobs run a handler; they never sign. */
+type DeliveryJobState = 'queued' | 'running' | 'done' | 'failed';
+/**
+ * Step jobs run the signing pipeline. `running`, `signed`, `submitted` and
+ * `submitted_unknown` are active: while one is, no other step job of the
+ * same wallet may start.
+ */
+type StepJobState = 'queued' | 'running' | 'signed' | 'submitted' | 'submitted_unknown' | 'completed' | 'chain_failed' | 'expired' | 'skipped' | 'rejected' | 'refused' | 'failed';
+type JobState = DeliveryJobState | StepJobState;
+declare const ACTIVE_STEP_STATES: readonly StepJobState[];
+declare const TERMINAL_STEP_STATES: readonly StepJobState[];
+declare const TERMINAL_DELIVERY_STATES: readonly DeliveryJobState[];
+/** Why a job ended where it did. */
+interface JobOutcome {
+    /** A refusal rule, a guard or rejection code, `no_consent`, `cooldown`, or an error class. */
+    readonly code: string;
+    readonly reason?: string;
+    readonly detail?: unknown;
+}
+/** What a step job carries once it has prepared and signed. */
+interface StepProgress {
+    /** Increments when an expired intent is prepared again. */
+    readonly generation: number;
+    readonly format?: ProtocolTransactionFormat;
+    readonly intent?: ExecutionIntentV1;
+    readonly prepared?: readonly ProtocolPreparedTransaction[];
+    /** The signed transactions, saved before submit so a crash never re-signs blind. */
+    readonly signed?: readonly string[];
+    /** Transaction signatures once the intent has them. */
+    readonly signatures?: readonly (string | null)[];
+    /** When the step was signed: its spending counts against windows from then. */
+    readonly signedAt?: number;
+    /** What each transaction moves out of the wallet (decimal amounts per asset), saved at signing. */
+    readonly outflows?: readonly {
+        readonly index: number;
+        readonly amounts: Readonly<Record<string, string>>;
+    }[];
+}
+interface JobBase {
+    /** Unique across both kinds: the delivery id for a delivery job, {@link stepJobId} for a step job. */
+    readonly id: string;
+    readonly attempts: number;
+    /** Not claimable before this time (milliseconds since the epoch). */
+    readonly notBefore: number;
+    readonly lease: {
+        readonly worker: string;
+        readonly until: number;
+    } | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly outcome: JobOutcome | null;
+}
+interface DeliveryJob extends JobBase {
+    readonly kind: 'delivery';
+    readonly state: DeliveryJobState;
+    readonly delivery: Delivery;
+}
+interface StepJob extends JobBase {
+    readonly kind: 'step';
+    readonly state: StepJobState;
+    readonly deliveryId: string;
+    readonly deploymentId: string;
+    readonly request: StepRequest;
+    readonly progress: StepProgress;
+}
+type Job = DeliveryJob | StepJob;
+/**
+ * A step job's id: `step:${deliveryId}:${step}:${wallet}`, then
+ * `:${instance}` for a step on an instance, so one trigger can run the same
+ * step for one wallet on several instances. The `step:` namespace and the
+ * encoded components keep step job ids apart from delivery ids (which start
+ * `webhook:`, `stream:`, `dispatch:` or `view:`) and from each other.
+ */
+declare function stepJobId(deliveryId: string, request: Pick<StepRequest, 'step' | 'wallet' | 'instance'>): string;
+
+/** Spending limits of a consent grant, per asset: `SOL` (in lamports) or a mint (in base units). */
+interface StoredConsentLimits {
+    /** The most one step may move out of the wallet. An asset without one may not leave. */
+    readonly perExecution: Readonly<Record<string, string>>;
+    /** The most all steps together may move out within a rolling window. */
+    readonly perWindow: Readonly<Record<string, {
+        readonly amount: string;
+        readonly windowMs: number;
+    }>>;
+}
+/** The signed proof a grant was made from. */
+interface ConsentProof {
+    /** The exact message the wallet signed. */
+    readonly message: string;
+    /** Base58 Ed25519 signature by the wallet. */
+    readonly signature: string;
+    readonly nonce: string;
+    readonly issuedAt: number;
+}
+/** A user's consent for automations to run steps for their wallet. */
+interface ConsentGrant {
+    readonly wallet: string;
+    readonly deploymentId: string;
+    /** `null` for every instance of the deployment. */
+    readonly instanceId: string | null;
+    readonly steps: readonly string[];
+    readonly limits: StoredConsentLimits;
+    /** The user's own settings for the steps (amount, weekday, ...). */
+    readonly params: Readonly<Record<string, unknown>>;
+    /** Milliseconds since the epoch. */
+    readonly expiresAt: number;
+    readonly grantedAt: number;
+    readonly revokedAt: number | null;
+    readonly proof: ConsentProof;
+}
+/** What one step moved, counted against a grant's windows. */
+interface LedgerEntry {
+    readonly jobId: string;
+    readonly wallet: string;
+    readonly deploymentId: string;
+    /** `SOL` or a mint. */
+    readonly asset: string;
+    /** Lamports or base units, as a decimal string. */
+    readonly amount: string;
+    readonly recordedAt: number;
+    /** Set when the step's intent never landed, so it no longer counts. */
+    readonly voidedAt: number | null;
+}
+interface ConsentQuery {
+    readonly wallet: string;
+    readonly deploymentId: string;
+    readonly step: string;
+    readonly instanceId: string | null;
+    readonly now: number;
+}
+/** What a view source last saw for one key. */
+interface SourceState {
+    readonly source: string;
+    readonly key: string;
+    /** Canonical-JSON SHA-256 of the stable value. */
+    readonly hash: string;
+    /** The stable derived value (JSON). */
+    readonly value: unknown;
+    /** Increments with every stable change; delivery ids carry it. */
+    readonly generation: number;
+    /** A new value waiting out `stableFor`, if any. */
+    readonly pending: {
+        readonly hash: string;
+        readonly value: unknown;
+        readonly since: number;
+    } | null;
+    /** The newest observation order written (a decimal integer), or `null`. */
+    readonly observed: string | null;
+    /** Increments with every write; compare-and-set reads it. */
+    readonly version: number;
+    readonly updatedAt: number;
+}
+interface SourceAdvance {
+    readonly source: string;
+    readonly key: string;
+    /** The version read; `null` when there was no state yet. The write fails if it moved. */
+    readonly expectedVersion: number | null;
+    readonly next: Pick<SourceState, 'hash' | 'value' | 'pending'> & {
+        readonly observed?: string | null;
+    };
+    /**
+     * Accept a delivery in the same atomic step, with id
+     * `view:${encodeURIComponent(source)}:${encodeURIComponent(key)}:${generation}`
+     * (the generation after the write).
+     */
+    readonly deliver?: {
+        readonly name: string;
+        readonly payload: unknown;
+    };
+    readonly now: number;
+}
+/** A step job to create, without its bookkeeping. */
+interface NewStepJob {
+    readonly id: string;
+    readonly deploymentId: string;
+    readonly request: StepRequest;
+}
+interface ClaimInput {
+    readonly worker: string;
+    readonly leaseMs: number;
+    readonly now: number;
+}
+interface TransitionInput {
+    /** The worker that holds the lease. */
+    readonly worker: string;
+    /** The state the job must be in; the transition fails otherwise. */
+    readonly from: JobState;
+    readonly to: JobState;
+    readonly now: number;
+    /** Merged into a step job's progress. */
+    readonly progress?: Partial<StepProgress>;
+    readonly outcome?: JobOutcome | null;
+    /** Keep the lease (for more work in the same claim) instead of releasing it. */
+    readonly keepLease?: {
+        readonly until: number;
+    };
+    /** Not claimable again before this time. */
+    readonly notBefore?: number;
+    readonly attempts?: number;
+    /**
+     * Ledger changes made in the same atomic step as the transition:
+     * `record` adds entries for this job, `void` voids its entries except
+     * those for `keepAssets`.
+     */
+    readonly ledger?: {
+        /** New entries; `recordedAt` defaults to the transition's `now`. */
+        readonly record?: readonly (Omit<LedgerEntry, 'jobId' | 'recordedAt' | 'voidedAt'> & {
+            readonly recordedAt?: number;
+        })[];
+        readonly void?: boolean;
+        readonly keepAssets?: readonly string[];
+    };
+}
+/**
+ * Where automations keep their state. A store must provide:
+ *
+ * - a unique insert for deliveries, so a trigger is accepted once;
+ * - exclusive job claims with a lease;
+ * - at most one active step job per wallet (`running`, `signed`,
+ *   `submitted`, `submitted_unknown`);
+ * - compare-and-set transitions, by state and lease holder;
+ * - completing a delivery job and enqueuing its step jobs atomically;
+ * - ledger writes atomic with the job transition they belong to;
+ * - single-use consent nonces;
+ * - compare-and-set on view-source state, with its delivery in the same step.
+ *
+ * `runStoreConformance` from `@usearete/automations/testing` checks all of
+ * these; a custom store must pass it.
+ */
+interface AutomationStore {
+    /**
+     * Tie the store to one deployment. The first call records it; a call for
+     * another deployment throws `StoreDeploymentError`. Use a separate store
+     * (for Postgres, a separate schema) per deployment.
+     */
+    bindDeployment(deploymentId: string): Promise<void>;
+    readonly deliveries: {
+        /**
+         * Record the delivery and queue its delivery job, atomically. `false`
+         * when a delivery with this id was already accepted, or its job still
+         * exists after the delivery id was pruned.
+         */
+        accept(delivery: Delivery, now: number): Promise<boolean>;
+        /** Forget accepted delivery ids older than `before`; returns how many. */
+        prune(before: number): Promise<number>;
+    };
+    readonly jobs: {
+        get(id: string): Promise<Job | null>;
+        /**
+         * Claim the next job: a queued delivery job; a queued step job whose
+         * wallet has no active step job (it becomes `running`); or an active job
+         * whose lease has lapsed. Jobs before their `notBefore` are skipped.
+         */
+        claimNext(input: ClaimInput): Promise<Job | null>;
+        /** Move a job from `from` to `to` if it is still there and leased by `worker`. */
+        transition(id: string, input: TransitionInput): Promise<boolean>;
+        /** Extend `worker`'s lease. `false` when it no longer holds it. */
+        renew(id: string, worker: string, until: number): Promise<boolean>;
+        /**
+         * Mark a running delivery job `done` and create its step jobs, in one
+         * step. Step jobs whose id exists already are left alone.
+         */
+        completeDelivery(id: string, worker: string, steps: readonly NewStepJob[], now: number): Promise<boolean>;
+        /** When this wallet last completed this step in this deployment, or `null`. */
+        lastCompleted(input: {
+            wallet: string;
+            deploymentId: string;
+            step: string;
+        }): Promise<number | null>;
+        list(filter?: {
+            kind?: Job['kind'];
+            state?: JobState;
+        }): Promise<Job[]>;
+        /** Delete finished jobs last updated before `before`; returns how many. */
+        prune(before: number): Promise<number>;
+    };
+    readonly consent: {
+        /** Store a grant, replacing the wallet's grant for the same deployment and instance. */
+        put(grant: ConsentGrant): Promise<void>;
+        /** The active grant covering the query, or `null`. */
+        find(query: ConsentQuery): Promise<ConsentGrant | null>;
+        /** Revoke grants (or only some of their steps). Returns how many grants changed. */
+        revoke(input: {
+            wallet: string;
+            deploymentId: string;
+            steps?: readonly string[];
+            /** Only the grant scoped to this instance. */
+            instanceId?: string;
+            now: number;
+        }): Promise<number>;
+        /** Every grant of a wallet, active or not. */
+        list(input: {
+            wallet: string;
+        }): Promise<ConsentGrant[]>;
+        /** Active grants in a deployment that cover `step`, for fan-out. */
+        active(input: {
+            deploymentId: string;
+            step?: string;
+            now: number;
+        }): Promise<ConsentGrant[]>;
+        /** Remember a nonce handed out with a proof message. */
+        issueNonce(nonce: string, expiresAt: number): Promise<void>;
+        /** Use an issued, unexpired nonce once. `false` when it was not issued, expired or used. */
+        useNonce(nonce: string, now: number): Promise<boolean>;
+    };
+    readonly sources: {
+        get(source: string, key: string): Promise<SourceState | null>;
+        /**
+         * Write a key's state if its version is still `expectedVersion`. The
+         * generation increments when the stable hash changes. Returns the new
+         * state, or `null` when another writer got there first.
+         */
+        advance(input: SourceAdvance): Promise<SourceState | null>;
+        /** The furthest cursor an append-view source recorded. */
+        cursor(source: string): Promise<string | null>;
+        /**
+         * Record a cursor if it is after the stored one (see `cursorAfter`), so a
+         * slow replica can never move a source back. Atomic.
+         */
+        putCursor(source: string, cursor: string, now: number): Promise<void>;
+        /** Hold a source exclusively until `until`. `false` while another holder's lease runs. */
+        acquireLease(source: string, holder: string, until: number, now: number): Promise<boolean>;
+        releaseLease(source: string, holder: string): Promise<void>;
+    };
+    readonly ledger: {
+        /** The sum of unvoided entries for the wallet and asset recorded at or after `since`. */
+        spent(input: {
+            wallet: string;
+            deploymentId: string;
+            asset: string;
+            since: number;
+        }): Promise<bigint>;
+        list(input: {
+            wallet: string;
+        }): Promise<LedgerEntry[]>;
+    };
+}
+
+/** An append-view cursor `{epoch}:{offset}` as numbers, or `null` when it is not one. */
+declare function parseCursor(cursor: string): {
+    epoch: string;
+    offset: bigint;
+} | null;
+/**
+ * Whether `next` moves past `current`. Offsets are compared within an
+ * epoch; a different epoch is a new tape lifetime, which cannot be ordered
+ * against the old one, so it always moves on. Any cursor is after an
+ * unreadable one.
+ */
+declare function cursorAfter(next: string, current: string | null): boolean;
+declare class StoreDeploymentError extends Error {
+    constructor(bound: string, requested: string);
+}
+
+/**
+ * Consent: what a user signs to let automations run steps for their wallet.
+ *
+ * The proof is a human-readable, domain-bound message in the style of
+ * Sign-In-With-Solana. It is built from the grant's fields, so the backend
+ * rebuilds it from the fields it is given and checks the wallet's signature
+ * over that, rather than parsing a message. Raising a limit or changing a
+ * setting needs a new signature; revoking does not.
+ *
+ * The signature is an accountability and anti-bug record. It does not
+ * protect against a compromised backend; the wallet provider's policy and
+ * the protocol's on-chain rules do.
+ */
+
+/** The asset key for SOL (wrapped SOL included), in lamports. */
+declare const SOL = "SOL";
+declare const CONSENT_PROOF_VERSION = "arete.automation-consent/v1";
+type Amount = string | number | bigint;
+/** Spending limits, per asset: `SOL` (lamports) or a mint (base units). */
+interface ConsentLimits {
+    /** The most one step may move out of the wallet. An asset without a limit may not leave. */
+    readonly perExecution?: Readonly<Record<string, Amount>>;
+    /** The most all steps together may move out within a rolling window. */
+    readonly perWindow?: Readonly<Record<string, {
+        readonly amount: Amount;
+        readonly window: Duration;
+    }>>;
+}
+/** What a user consents to. */
+interface ConsentFields {
+    readonly wallet: string;
+    readonly deploymentId: string;
+    /** One instance, or omit for every instance of the deployment. */
+    readonly instanceId?: string | null;
+    readonly steps: readonly string[];
+    readonly limits: ConsentLimits;
+    /** The user's settings for the steps, for example `{ amount: '50000000', weekday: 'fri' }`. */
+    readonly params?: Readonly<Record<string, unknown>>;
+    /** When the grant ends (a `Date` or milliseconds since the epoch). */
+    readonly expiresAt: Date | number;
+}
+interface NormalizedConsent {
+    readonly wallet: string;
+    readonly deploymentId: string;
+    readonly instanceId: string | null;
+    readonly steps: string[];
+    readonly limits: StoredConsentLimits;
+    readonly params: Record<string, unknown>;
+    readonly expiresAt: number;
+}
+type ConsentErrorCode = 'invalid_fields' | 'invalid_signature' | 'nonce_not_usable' | 'proof_stale' | 'expired' | 'no_domain';
+declare class ConsentError extends Error {
+    readonly code: ConsentErrorCode;
+    constructor(code: ConsentErrorCode, message: string);
+}
+/** Validate and normalize consent fields. Throws {@link ConsentError}. */
+declare function normalizeConsent(fields: ConsentFields): NormalizedConsent;
+/** A window as the message shows it: the largest whole unit. */
+declare function windowText(windowMs: number): string;
+/**
+ * The message a wallet signs to grant consent. Lines are joined by `\n`:
+ *
+ * ```text
+ * <domain> asks to run protocol steps for your wallet without asking each time:
+ * <wallet>
+ *
+ * Deployment: <deployment id>
+ * Instance: <instance id, or "any">
+ * Steps: <steps, sorted, comma-separated>
+ * Per run: <amount> lamports of SOL | <amount> base units of <mint>   (one line per asset, sorted)
+ * Per <window>: <amount> ...                                          (one line per asset, sorted)
+ * Setting <key as a JSON string>: <RFC 8785 JSON of the value>       (one line per key, sorted)
+ * Expires At: <ISO 8601 UTC>
+ *
+ * Nothing else may leave your wallet through these steps. You can revoke this at any time without signing.
+ *
+ * Version: arete.automation-consent/v1
+ * Nonce: <nonce>
+ * Issued At: <ISO 8601 UTC>
+ * ```
+ *
+ * Without per-run limits the message says that nothing may leave the wallet.
+ */
+declare function consentMessage(domain: string, consent: NormalizedConsent, nonce: string, issuedAt: number): string;
+/**
+ * What a prepared step moves out of the wallet, per asset, summed over its
+ * transactions: SOL as the policy measures it (wrapped SOL and token
+ * accounts closed to someone else included), and every mint that leaves.
+ * The summary must be complete; the policy refuses one that is not.
+ */
+declare function stepOutflows(summary: PreparedSummary): Map<string, bigint>;
+
+/**
+ * View sources: watch a live view and dispatch a trigger when a condition
+ * becomes true.
+ *
+ * Exactly-once comes from the store, not from ids derived from the view's
+ * data (list and state views carry no cursor or version). Each source key
+ * keeps its last stable value; a change is written by compare-and-set and,
+ * when `changed(previous, next)` holds, its delivery
+ * (`view:${source}:${key}:${generation}`) is accepted in the same step. So:
+ *
+ * - replicas watching one view produce one delivery per transition;
+ * - after a restart the first snapshot is compared with the stored value,
+ *   so a crossing during downtime fires once and nothing fires twice;
+ * - every transition has its own generation, so A → B → A → B fires three
+ *   times.
+ *
+ * A value that changed and changed back while no replica was watching is
+ * not seen: list and state views hold current state, not history.
+ *
+ * Replicas whose views lag each other can still disagree about the order of
+ * values: one stores B while another, behind, still sees A. Give the source
+ * `observedAt` (for example the slot a row was updated at) so an older
+ * observation never replaces a newer one, or run it on one replica
+ * (`exclusive`).
+ *
+ * A trigger means "go and look", not the truth: handlers read live state
+ * before returning steps, and every step is checked again before signing.
+ */
+
+/** The parts of a list view a source reads. A `TypedListView` is one. */
+interface ListViewLike<T> {
+    /** The complete current rows (the source seeds from these). */
+    get(): Promise<T[]>;
+    /** The rows the open subscription holds now; used to drop rows a reconnect removed. */
+    getSync?(): T[] | undefined;
+    watchRich(options?: {
+        withSnapshot?: boolean;
+    }): AsyncIterable<RichUpdate<T>>;
+}
+/** The parts of an append view a source reads: updates with `{epoch}:{offset}` cursors. */
+interface AppendViewLike<T> {
+    watch(options?: {
+        after?: string;
+        withSnapshot?: boolean;
+    }): AsyncIterable<Update<T>>;
+}
+interface SourceOptionsBase<V> {
+    /** The handler name the source dispatches to. Unique per source. */
+    readonly name: string;
+    /**
+     * Whether a change from `previous` (undefined the first time) to `next`
+     * is a trigger. Defaults to every change. Put hysteresis here or in
+     * `derive`.
+     */
+    readonly changed?: (previous: V | undefined, next: V) => boolean;
+    /** A new value must hold this long before it counts. Stops one bad update from firing. */
+    readonly stableFor?: Duration;
+}
+type Observed = number | bigint | null | undefined;
+/** One signal for the whole view (for example: which market pays best). */
+interface AggregateSourceOptions<T, V> extends SourceOptionsBase<V> {
+    /** A row's identity in the view (its id), so updates and removals find the row. */
+    readonly key: (row: T) => string;
+    /** The signal, as JSON. */
+    readonly derive: (rows: readonly T[]) => V;
+    /** How recent the rows are (a slot, a sequence); an older observation is ignored. */
+    readonly observedAt?: (rows: readonly T[]) => Observed;
+}
+/** One signal per row, kept separately (for example: is this position's health low). */
+interface RowSourceOptions<T, V> extends SourceOptionsBase<V> {
+    readonly key: (row: T) => string;
+    /** The row's signal, as JSON. */
+    readonly derive: (row: T) => V;
+    /** Rows to watch; others are ignored. */
+    readonly filter?: (row: T) => boolean;
+    /** How recent the row is (a slot, a sequence); an older observation is ignored. */
+    readonly observedAt?: (row: T) => Observed;
+}
+interface ListSource<T = any, V = any> {
+    readonly kind: 'list';
+    readonly name: string;
+    readonly view: ListViewLike<T>;
+    /** A row's identity in the view. */
+    readonly rowKey: (row: T) => string;
+    readonly stableForMs: number;
+    readonly changed: (previous: V | undefined, next: V) => boolean;
+    /** The keys, values and observation orders the rows give. */
+    readonly signals: (rows: readonly T[]) => Array<[string, V, bigint | null]>;
+    /** The key, value and order one changed row gives, or `null` for an aggregate (re-read every row). */
+    readonly rowSignal: ((row: T) => [string, V, bigint | null] | undefined) | null;
+}
+interface AppendSource<T = any> {
+    readonly kind: 'append';
+    readonly name: string;
+    readonly view: AppendViewLike<T>;
+    readonly filter?: (row: T) => boolean;
+}
+type ViewSource = ListSource | AppendSource;
+/** The payload a list-view source dispatches. */
+interface ViewTrigger<V = unknown> {
+    readonly source: string;
+    /** The row key, or `all` for an aggregate source. */
+    readonly key: string;
+    readonly value: V;
+    /** The stable value before; absent the first time the key is seen. */
+    readonly previous?: V;
+}
+/** The payload an append-view source dispatches, one per row. */
+interface AppendTrigger<T = unknown> {
+    readonly source: string;
+    readonly cursor: string;
+    readonly row: T;
+}
+declare const AGGREGATE_KEY = "all";
+/** A source with one signal for the whole list view, under the key `all`. */
+declare function fromView<T, V>(view: ListViewLike<T>, options: AggregateSourceOptions<T, V>): ListSource<T, V>;
+/** A source with one signal per row of a list view, keyed by `key(row)`. */
+declare function fromViewRows<T, V>(view: ListViewLike<T>, options: RowSourceOptions<T, V>): ListSource<T, V>;
+/** A source over an append view: one trigger per row, resumed from the stored cursor. */
+declare function fromAppendView<T>(view: AppendViewLike<T>, options: {
+    readonly name: string;
+    readonly filter?: (row: T) => boolean;
+}): AppendSource<T>;
+
+/**
+ * Automations as a definition: the handlers and view sources, apart from the
+ * client, signer, store and secrets that run them. The same definition runs
+ * under `a4 dev` (against the project's dev environment) and in production
+ * (`automations.use(definition)`), so moving from one to the other changes
+ * configuration only.
+ */
+
+/** Connects a stack's views: the dev environment's under `a4 dev`, the published stack in production. */
+type StackConnector = <T extends StackDefinition>(stack: T) => Promise<ConnectedArete<T>>;
+/** What a definition's setup registers handlers and sources on. */
+interface AutomationsSetup<TTypes extends ProtocolTypeMap = ProtocolTypeMap> {
+    readonly on: Automations<TTypes>['on'];
+    source(source: ViewSource, options?: {
+        exclusive?: boolean;
+    }): SourceHandle;
+    /** Connect a stack for its views, to build view sources from. */
+    readonly connect: StackConnector;
+}
+/** The policy fields a definition may set: the deployment and cluster come from where it runs. */
+type DefinitionPolicy = Omit<PolicyInput, 'deployments' | 'clusters'>;
+interface AutomationsDefinition<TTypes extends ProtocolTypeMap = ProtocolTypeMap> {
+    readonly kind: 'automations';
+    /** The protocol's generated definition, for its client. */
+    readonly protocol: ProtocolDefinition<TTypes, any, any>;
+    /**
+     * The programs and caps the steps need. `a4 dev` signs under it; in
+     * production, spread it into `definePolicy` with the deployment and
+     * clusters. Without it `a4 dev` allows 1 SOL per transaction and no token.
+     */
+    readonly policy?: DefinitionPolicy;
+    readonly setup: (automations: AutomationsSetup<TTypes>) => void | Promise<void>;
+}
+/**
+ * Define automations for a protocol: handlers for its events and dispatched
+ * triggers, and view sources. Export the definition as the module's default
+ * for `a4 dev` (`[dev.automations] entry` in arete.toml).
+ */
+declare function defineAutomations<TTypes extends ProtocolTypeMap>(protocol: ProtocolDefinition<TTypes, any, any>, setup: (automations: AutomationsSetup<TTypes>) => void | Promise<void>, options?: {
+    policy?: DefinitionPolicy;
+}): AutomationsDefinition<TTypes>;
+/** Whether `value` is a definition, from this or another copy of the package. */
+declare function isAutomationsDefinition(value: unknown): value is AutomationsDefinition;
+/** Connects with the SDK's defaults: `ARETE_API_KEY` or the `a4` login. */
+declare const connectStack: StackConnector;
+
+/** The parts of a protocol client automations use. A secret-key `ProtocolClient` is one. */
+interface AutomationClient<TTypes extends ProtocolTypeMap = ProtocolTypeMap> {
+    readonly deploymentId: string;
+    /** Present on a real client; only used to infer the protocol's types. */
+    readonly definition?: ProtocolDefinition<TTypes, any, any>;
+    readonly steps: object;
+    allowedSteps(input: {
+        instance: string;
+        wallet: string;
+    }): Promise<readonly ProtocolStepAvailability[]>;
+    submit(intent: ExecutionIntentV1 | string, signedTransactions: readonly (string | Uint8Array)[]): Promise<ProtocolIntentState>;
+    readonly intents: {
+        get(executionId: string): Promise<ProtocolIntentState>;
+    };
+    events?(instanceId: string, options: ProtocolEventsOptions<TTypes>): ProtocolEventSubscription;
+    /** Used to end instance-scoped consent when the instance is terminal. */
+    readonly instances?: {
+        get(id: string): Promise<{
+            readonly terminal: boolean;
+        }>;
+    };
+    /** Present on a real client: a handler reads a participant's current state with it. */
+    readonly participants?: {
+        get(input: {
+            instance: string;
+            wallet: string;
+            signal?: AbortSignal;
+        }): Promise<ProtocolParticipantDetail<TTypes>>;
+    };
+}
+type EventName<TTypes extends ProtocolTypeMap> = Extract<keyof TTypes['events'], string>;
+type StepName<TTypes extends ProtocolTypeMap> = Extract<keyof TTypes['steps'], string>;
+type EventState<TTypes extends ProtocolTypeMap, E extends EventName<TTypes>> = TTypes['events'][E]['machine'] extends 'participant' ? TTypes['participantState'] : TTypes['instanceState'];
+/** An emitted protocol event, from a webhook or an instance's event stream. */
+interface AutomationEvent<TEvent extends string = string, TState extends string = string> {
+    /** The emission id. */
+    readonly id: string;
+    readonly event: TEvent;
+    readonly deploymentId: string;
+    readonly instanceId: string;
+    readonly participantId: string | null;
+    /** The machine's state at emission; `null` for stream events, which do not carry it. */
+    readonly state: TState | null;
+    readonly occurredAt: string;
+    readonly source: 'webhook' | 'stream';
+}
+interface TriggerInfo {
+    readonly name: string;
+    readonly id: string;
+    readonly source: TriggerSource;
+    readonly receivedAt: number;
+}
+interface StepOptions {
+    /** Skip the step when the same wallet completed it this recently. */
+    readonly cooldown?: Duration;
+}
+interface HandlerContext<TTypes extends ProtocolTypeMap = ProtocolTypeMap> {
+    readonly client: AutomationClient<TTypes>;
+    readonly trigger: TriggerInfo;
+    /**
+     * Active consent grants in this deployment, for fan-out: every wallet the
+     * automations may act for. A starting set only; each step job checks
+     * consent again.
+     */
+    readonly consents: {
+        list(query?: {
+            step?: StepName<TTypes> | (string & {});
+            instanceId?: string;
+        }): Promise<ConsentGrant[]>;
+    };
+    /** A step request for the handler to return. Handlers never prepare steps themselves. */
+    step<S extends StepName<TTypes>>(step: S, request: {
+        wallet: string;
+        instance?: string;
+        args?: Partial<TTypes['steps'][S]['args']> & Record<string, unknown>;
+    }, options?: StepOptions): StepRequest;
+}
+type Handler<TPayload, TTypes extends ProtocolTypeMap> = (payload: TPayload, ctx: HandlerContext<TTypes>) => readonly StepRequest[] | void | Promise<readonly StepRequest[] | void>;
+/** Where a step job ended, for notifications. */
+interface AutomationOutcome {
+    readonly jobId: string;
+    readonly deliveryId: string;
+    readonly deploymentId: string;
+    readonly step: string;
+    readonly wallet: string;
+    readonly instanceId: string | null;
+    readonly state: StepJobState;
+    readonly code: string;
+    readonly reason?: string;
+    readonly detail?: unknown;
+    readonly executionId: string | null;
+    readonly signatures: readonly (string | null)[];
+}
+interface AutomationsOptions<TTypes extends ProtocolTypeMap = ProtocolTypeMap> {
+    readonly client: AutomationClient<TTypes>;
+    readonly signer: ProtocolSigner;
+    readonly policy: SignerPolicy;
+    /** Measures what each transaction moves out of the wallet; the policy refuses what it cannot measure. */
+    readonly simulator: Simulator;
+    readonly store: AutomationStore;
+    /**
+     * Where the deployment runs; the policy must list it. Defaults to the
+     * client's: `dev` for a client `a4 dev` generated (the deployment in a dev
+     * environment), else `mainnet`.
+     */
+    readonly cluster?: Cluster;
+    /** Transaction formats in the deployment's order of preference. Defaults to v1, then v0. */
+    readonly transactionFormats?: readonly ProtocolTransactionFormat[];
+    /** Identifies this worker in leases. Defaults to a random id. */
+    readonly worker?: string;
+    /** How long a claim lasts before another worker may take the job over. Defaults to 60s. */
+    readonly lease?: Duration;
+    /** Attempts before a job that has not signed yet fails. Defaults to 5. */
+    readonly maxAttempts?: number;
+    /** How long one claim waits for a submitted intent to settle. Defaults to 30s. */
+    readonly trackFor?: Duration;
+    /** Between intent status reads while tracking. Defaults to 2s. */
+    readonly trackInterval?: Duration;
+    /** Before a pending intent is read again in a later claim. Defaults to 10s, doubling up to 5m. */
+    readonly reconcileInterval?: Duration;
+    readonly clock?: Clock;
+    /** Consent proofs: the host name users see in the message they sign. */
+    readonly consent?: {
+        readonly domain: string;
+        /** How long a proof message may wait to be signed and granted. Defaults to 10 minutes. */
+        readonly proofTtl?: Duration;
+    };
+    /** Every step job that reaches a final state. */
+    readonly onOutcome?: (outcome: AutomationOutcome) => void | Promise<void>;
+    /** Step jobs refused by the policy or the signer checks. */
+    readonly onRefused?: (outcome: AutomationOutcome) => void | Promise<void>;
+    /** Step jobs the protocol rejected (a guard, an access or a state code). */
+    readonly onRejected?: (outcome: AutomationOutcome) => void | Promise<void>;
+    /** Errors the runtime recovers from by retrying, and hook failures. */
+    readonly onError?: (error: unknown, context: {
+        jobId?: string;
+        phase: string;
+    }) => void;
+}
+interface WebhookHandlerOptions {
+    /** The endpoint's signing secret. */
+    readonly secret: string | Uint8Array;
+    /** Allowed clock skew in seconds; defaults to 300. */
+    readonly toleranceSeconds?: number;
+}
+/** A consent proof message for the user's wallet to sign. */
+interface ConsentProofRequest {
+    /** The UTF-8 message, lines joined by `\n`. */
+    readonly message: string;
+    /** `message` as bytes, for `wallet.signMessage`. */
+    readonly bytes: Uint8Array;
+    readonly nonce: string;
+    /** Milliseconds since the epoch; send it back with the grant. */
+    readonly issuedAt: number;
+}
+interface ConsentGrantInput extends ConsentFields {
+    readonly nonce: string;
+    readonly issuedAt: number;
+    /** The wallet's 64-byte Ed25519 signature over the message, or its base58 text. */
+    readonly signature: Uint8Array | string;
+}
+interface ConsentApi {
+    /** Build the message to sign. Issues a single-use nonce. */
+    proofMessage(fields: ConsentFields): Promise<ConsentProofRequest>;
+    /**
+     * Verify the wallet's signature over the message rebuilt from `fields`,
+     * use the nonce, and store the grant. `warnings` lists what the signer
+     * reports missing on the provider side (no delegation, no provider policy).
+     */
+    grant(input: ConsentGrantInput): Promise<{
+        grant: ConsentGrant;
+        warnings: string[];
+    }>;
+    /** Revoke without a signature. Queued and running jobs see it before signing. */
+    revoke(input: {
+        wallet: string;
+        steps?: readonly string[];
+        instanceId?: string;
+    }): Promise<number>;
+    list(input: {
+        wallet: string;
+    }): Promise<ConsentGrant[]>;
+}
+interface WebhookResult {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+}
+interface Automations<TTypes extends ProtocolTypeMap = ProtocolTypeMap> {
+    readonly consent: ConsentApi;
+    /** Handle an emitted protocol event. */
+    on<E extends EventName<TTypes>>(event: E, handler: Handler<AutomationEvent<E, EventState<TTypes, E>>, TTypes>): this;
+    /** Handle a dispatched trigger (a cron tick, a view source). */
+    on<TPayload = unknown>(name: string, handler: Handler<TPayload, TTypes>): this;
+    /**
+     * Accept a trigger. `id` makes it idempotent: a repeated dispatch with the
+     * same id is ignored. Resolves `false` for a duplicate.
+     */
+    dispatch(name: string, payload: unknown, options: {
+        id: string;
+    }): Promise<boolean>;
+    /** A fetch-standard webhook endpoint (Workers, Next.js, Hono, Bun). */
+    webhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+    /** An Express endpoint. Mount it behind `express.raw({ type: 'application/json' })`. */
+    expressWebhookHandler(options: WebhookHandlerOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<void>;
+    /** Verify and accept a webhook delivery from its raw body and headers. */
+    acceptWebhook(body: string | Uint8Array, headers: WebhookHeadersLike, options: WebhookHandlerOptions): Promise<WebhookResult>;
+    /** Follow one instance's event stream and accept its events. */
+    follow(instanceId: string, options?: {
+        lastEventId?: string;
+        signal?: AbortSignal;
+    }): ProtocolEventSubscription;
+    /**
+     * Watch a view source and accept its triggers until `stop()`. With
+     * `exclusive`, only the replica holding the source's lease subscribes
+     * (the compare-and-set already makes several subscribers correct; the
+     * lease only saves bandwidth).
+     */
+    source(source: ViewSource, options?: {
+        exclusive?: boolean;
+    }): SourceHandle;
+    /**
+     * Register a definition's handlers and view sources (see
+     * `defineAutomations`). `connect` opens the stacks its sources read;
+     * it defaults to the SDK's own connection.
+     */
+    use(definition: AutomationsDefinition<TTypes>, options?: {
+        connect?: StackConnector;
+    }): Promise<this>;
+    /** Read a list-view source's snapshot once and accept what changed (for a serverless cron). */
+    poll(source: ListSource): Promise<{
+        delivered: number;
+        pending: number;
+    }>;
+    /** Claim and run one job. `false` when none was ready. */
+    runOnce(): Promise<boolean>;
+    /** Run jobs until none is ready (or `maxJobs` ran). Returns how many ran. */
+    drain(options?: {
+        maxJobs?: number;
+    }): Promise<number>;
+    /** Run jobs in the background until `stop()`. */
+    start(options?: {
+        pollInterval?: Duration;
+        concurrency?: number;
+    }): void;
+    stop(): Promise<void>;
+}
+interface SourceHandle {
+    stop(): Promise<void>;
+}
+type WebhookHeadersLike = {
+    get(name: string): string | null;
+} | Record<string, string | readonly string[] | undefined>;
+interface ExpressLikeRequest {
+    readonly body: unknown;
+    readonly headers: Record<string, string | readonly string[] | undefined>;
+}
+interface ExpressLikeResponse {
+    status(code: number): ExpressLikeResponse;
+    json(body: unknown): unknown;
+}
+/** Where a client's deployment runs: `dev` when `a4 dev` generated it, else `mainnet`. */
+declare function clientCluster(client: Pick<AutomationClient, 'definition'>): Cluster;
+declare function createAutomations<TTypes extends ProtocolTypeMap = ProtocolTypeMap>(options: AutomationsOptions<TTypes>): Automations<TTypes>;
+
+/**
+ * An in-memory store for tests and single-process development. State is
+ * lost on restart, so it must not back automations that sign real funds.
+ * Each method runs to completion without awaiting, which makes every
+ * operation atomic under JavaScript's single-threaded event loop.
+ */
+
+/**
+ * A memory store's contents, for `a4 dev` to keep across restarts. Opaque:
+ * write it with `v8.serialize` and read it back with `v8.deserialize`.
+ */
+interface MemoryStoreState {
+    readonly version: 1;
+    readonly deliveries: Map<string, number>;
+    readonly jobs: Map<string, Job>;
+    readonly order: number;
+    readonly sequence: Map<string, number>;
+    readonly grants: ConsentGrant[];
+    readonly deployment: string | null;
+    readonly nonces: Map<string, {
+        expiresAt: number;
+        used: boolean;
+    }>;
+    readonly ledger: LedgerEntry[];
+    readonly sourceStates: Map<string, SourceState>;
+    readonly cursors: Map<string, string>;
+}
+declare function memoryStore(options?: {
+    state?: MemoryStoreState;
+}): AutomationStore;
+
+export { ACTIVE_STEP_STATES, AGGREGATE_KEY, CONSENT_PROOF_VERSION, ConsentError, DEFAULT_CLUSTERS, DEFAULT_TRANSACTION_FORMATS, KNOWN_CLUSTERS, PolicyError, RUNTIME_PROGRAMS, SOL, SignerRefusal, StoreDeploymentError, TERMINAL_DELIVERY_STATES, TERMINAL_STEP_STATES, TransactionDecodeError, checkPrepared, checkPreparedAgainstIntent, checkSignedTransactions, checkTarget, clientCluster, connectStack, consentMessage, createAutomations, cursorAfter, decodeTransaction, defineAutomations, definePolicy, durationMs, fromAppendView, fromView, fromViewRows, isAutomationsDefinition, isSignerRefusal, memoryStore, negotiateTransactionFormat, normalizeConsent, parseCursor, rpcSimulator, scheduleSlot, stepJobId, stepOutflows, summarizePrepared, systemClock, windowText };
+export type { AggregateSourceOptions, AppendSource, AppendTrigger, AppendViewLike, AuthorityFinding, AutomationClient, AutomationEvent, AutomationOutcome, AutomationStore, Automations, AutomationsDefinition, AutomationsOptions, AutomationsSetup, CheckPreparedInput, ClaimInput, Clock, Cluster, ConsentApi, ConsentErrorCode, ConsentFields, ConsentGrant, ConsentGrantInput, ConsentLimits, ConsentProof, ConsentProofRequest, ConsentQuery, DecodedTransaction, DefinitionPolicy, DelegationStatus, Delivery, DeliveryJob, DeliveryJobState, Duration, ExpressLikeRequest, ExpressLikeResponse, Handler, HandlerContext, Job, JobOutcome, JobState, LedgerEntry, ListSource, ListViewLike, NewStepJob, NormalizedConsent, PolicyInput, PreparedStepLike, PreparedSummary, ProtocolSigner, Refusal, RefusalRule, RowSourceOptions, RpcSimulatorOptions, SchedulePeriod, SignTransactionsInput, SignerEffectSummary, SignerPolicy, Simulator, SourceAdvance, SourceHandle, SourceState, StackConnector, StepJob, StepJobState, StepOptions, StepProgress, StepRequest, StoredConsentLimits, TokenDelta, TransactionSummary, TransitionInput, TriggerInfo, TriggerSource, ViewSource, ViewTrigger, WebhookHandlerOptions, WebhookResult };