import type { EngineInternals } from './internals.ts';
/**
 * Engine-side handler for `ctx.setFinalizerState(value)` (issue #446). Durably
 * records the payload associated with the workflow's definition-level
 * `finalizer` activity.
 *
 * This handler only records the value; the engine passes the decoded payload as
 * the finalizer's input when it drives cancel/timeout teardown (#446 Phase 2).
 *
 * The value is staged as a pending atomic side-effect — a `put` of
 * {@link KEYS.finalizerState} — that commits with whichever durable write lands
 * first: the next checkpoint/suspend commit, or, if no checkpoint runs before the
 * workflow terminates, the terminal `updateWorkflowState` batch
 * (`includePendingAtomicSideEffects` is set for terminal transitions). Either way
 * the resource id is durable before teardown is driven: a cancel arriving before
 * the next checkpoint still flushes the staged op in the terminal batch, so the
 * finalizer always sees the resource id. The staged op inherits the lease-epoch
 * fence (#470) for free, since checkpoint and terminal commits route through
 * `commitSelfWorkflowStateOperations` (completion) or
 * `commitExternalTerminalWorkflowStateOperations` (cancel/timeout/suspend —
 * ADR 0002), both in `storage-io.ts`.
 *
 * Oversized payloads are rejected before staging (the same hostile-input guard
 * activity results use). A call made once the workflow is already terminalizing
 * — e.g. from an `onCancel` handler, which runs after the terminal batch has
 * already taken the pending side-effects — is a no-op: the staged op has no
 * future commit to ride and is cleared on terminal cleanup. A development
 * warning is emitted so the footgun is visible, but no error is thrown.
 */
export declare function recordFinalizerState(internals: EngineInternals, workflowId: string, value: unknown): void;