Documents the handler use's literal options

[johnnyt]

What

StatifierOban.Invoke.Handler's __using__/1 reads its options only when the use argument is a literal keyword list, and reads only :max_attempts from it. Until now the moduledoc did not say so: a keyword list reached through a module attribute, a variable or a function call is ignored whole, and an unknown or misspelled key is ignored, with no error in either case.

This takes the documentation arm of the bead's acceptance ("the moduledoc says literal keyword options only; a test pins the chosen behaviour"):

• The moduledoc's "Capping a handler's attempts" gains one paragraph: write the options as a literal keyword list in the use; an argument that only holds a keyword list, or is not one, declares no cap; max_attempts: nil declares no cap; any key other than :max_attempts is ignored; none of these is an error.
• test/statifier_oban/invoke/handler_test.exs gains two tests, each compiling a handler with Code.compile_string/1: a misspelled key, and a keyword list reached through a module attribute and through a variable. Each asserts __statifier_oban_max_attempts__/0 returns nil and the stored job carries the invoke worker's default max_attempts.

No behaviour change and no changelog fragment (documentation and tests are excluded by changelog.d/README.md).

Provenance

The compile-time-error arm of the acceptance was not taken: it would change what an existing host's code compiles to, which this change keeps as it is (ruled by the operator, 2026-09-27: defaults stay the packages'). The paragraph is consistent with ADR-0005's 2026-09-27 Note ("What an explicit nil does"), which already records that a non-keyword use argument and max_attempts: nil compile clean and declare no cap.

Review (own, in-turn)

I re-read the diff against the bead and checked each claim in the new paragraph against __using__/1 and __max_attempts__!/2 in lib/statifier_oban/invoke/handler.ex. The option is read by Keyword.keyword?(opts) on the unexpanded argument, so an attribute, a variable or a call is not a keyword list at that point and yields nil. Keyword.get(opts, :max_attempts) reads the one key and nothing else. __max_attempts__!(nil, _) returns nil, and put_max_attempts/2 adds nothing for nil. Two sabotage checks each turned a new test red on an assertion: reading the first value of any keyword list instead of :max_attempts, and evaluating a non-keyword argument in the module body. Both were reverted from a copy, confirmed byte-equal, and recorded in one comment line above each test. Tier: gate. The PR is a moduledoc paragraph and two tests, with no contract surface touched and fewer than 300 lines changed.

Gate

Full mix quality green on the committed tree: format, compile (warnings as errors), doc links, dependencies, credo, docs, tests (305 of 305, 97.1% coverage), dialyzer. Doctor, gettext and sobelow are skipped as not installed.

Refs: sob-qmb