@callback config_fingerprint(ctx :: map()) :: term()

Optional. Joiner-compatibility fingerprint, compared against fief_meta at join phase one; mismatch is fatal before shared state is touched. ctx carries :instance, :partitions, and :opts.

@callback handle_fence(deadline_ms :: non_neg_integer(), impl_state()) ::
  {:ok, impl_state()}

Advisory notification with a deadline; the framework kills the agent (and the linked impl subtree) unconditionally when the deadline passes. Never load-bearing for guarantee 1.

@callback handle_info(msg :: term(), impl_state()) :: {:noreply, impl_state()}

Optional (M6 contract change). Non-framework messages arriving in the agent process: because impl callbacks run in the agent, everything an impl-owned process sends back (extraction completions at freeze), every :DOWN for a monitor the impl holds, and every seam timer the impl armed (Fief.Seam.send_after/2 delivers {:timeout, ref, msg} to the arming process — the agent) lands in the agent's mailbox. This callback is that channel.

Routing rule — the framework claims, and the impl never sees:

• {:fief_fence, deadline_ms} from the manager (and any future framework-internal message, which will use a fief_agent_-prefixed tag — that tag prefix is reserved);
• {:timeout, ref, msg} for timers the agent itself armed — claimed by ref, never by shape. The agent arms no timers today, so in practice every {:timeout, ref, msg} is delivered here whole (match your own refs; ignore the rest — the stale-timer catch-all is yours now);
• anything that decodes as a Fief.Wire envelope (:msg/:peer take the validated paths above; :moved and unsupported protocol versions are dropped);
• :gen_statem calls (:reconcile and friends).

Everything else is delivered here whenever the impl exists (always, after init/2 — both :serving and :donor postures), under the same checkpoint discipline as every other delivery. Not exported → such messages are dropped silently (the pre-M6 behavior).

@callback handle_message(msg :: term(), from :: term() | nil, impl_state()) ::
  {:noreply, impl_state()} | {:reply, term(), impl_state()}

Delivered only while this node owns the vnode under a live lease (framework-validated). msg is opaque — a multi-key impl defines a wrapper format (implementation.md §7). from is opaque; reply inline or pass it to an owned process which replies directly via Fief.Vnode.reply/2.

@callback handle_peer(session(), msg :: term(), impl_state()) :: {:noreply, impl_state()}

Impl↔impl traffic between successive owners of this vnode. The framework delivers this ONLY when the session matches its authoritative view of the vnode row — stale-session messages are dropped before the impl sees them.

@callback handoff_in(session() | nil, impl_state()) :: {:ok, impl_state()}

Ownership arrived. session = open transfer with a live donor (pull from it); nil = no donor (fresh assignment, donor dead, or aborted transfer — rebuild from durable truth). The impl keeps its state across handoff transitions, so a donor regaining ownership after recipient death (handoff_out → handoff_in nil) can apply the taint rule from its own memory (implementation.md §7).

@callback handoff_out(session(), impl_state()) :: {:ok, impl_state()}

Ownership left this node with an open transfer; drain to the recipient via send_peer/2, then report_drained/1. New handle_message deliveries have already stopped (framework validation) before this is called.

@callback init(vnode_id(), ctx :: map()) :: {:ok, impl_state()}

Initialize the impl for one vnode. ctx carries :instance, :node_id, :vnode_id, and :opts (the opts half of the vnode_impl: {module, opts} instance opt).

@callback instance_children(ctx :: map()) :: [
  Supervisor.child_spec() | {module(), term()}
]

Optional. Child specs the impl needs at the instance root — supervised infrastructure that must outlive fence kills and kernel restarts (the root is rest_for_one; these children are placed first, so they survive a crash of any kernel child and die only with the instance). Fief.Key.VnodeImpl uses this for Fief.Key.Limbo. ctx carries :instance, :partitions, :opts, and :sim.