Explain resolve as a single-authority answer point, including its failure rules and how it differs from ordinary hooks

Resolve

resolve is the easiest extension point to misunderstand.

It may look like just another handler, but its semantic job is not "participate in a flow."

Its job is:

provide the final answer to a named question

Separate it from the first three

The first three are closer to:

pipeline: several participants transform a value
guard: several participants inspect a value
effect: several participants trigger side effects

resolve is closer to:

who is the final authority for this answer

Why there must be exactly one resolver

Because the question it serves is usually not "let several plugins each add something."

It is more like:

what is the final role
which provider is finally selected
who is the final route owner

These questions require:

one definite answer
one final authority

That is why duplicate registration for the same resolve point throws immediately.

Minimal example

const role = await agent.plugins.resolve<{ userId: string }, string>(
  "auth.resolve_role",
  { userId: "owner" },
);

A plugin can define it like this:

resolves: {
  "auth.resolve_role": async ({ value }) => {
    const body = value as { userId?: unknown };
    const userId = String(body.userId || "").trim();
    if (!userId) {
      throw new Error("userId is required");
    }
    if (userId === "owner") return "admin" as never;
    return "member" as never;
  },
}