docs(internals): record Settings unknown-option handling as design intent - #2068
Merged
lestrrat merged 1 commit intoApr 27, 2026
Merged
Conversation
…tent Adversarial review JWA-20260426194121-003 flagged jwx.Settings / cert.Settings for silently skipping unknown options. The motivating cross-package mix-up case (cert.Settings(jwx.WithUseNumber(true))) is a compile error today — the two GlobalOption interfaces use unexported globalOption() markers on their own struct types, so they are not compiler-interchangeable despite both wrapping option.Interface. Remaining failure modes are internal-only generator-drift cases caught by ordinary test discipline. Adding the seal to internals.md so a future review agent sees the design intent and does not re-flag.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adversarial review (JWA-20260426194121-003) flagged
jwx.Settings/cert.Settingsfor silently skipping unknown options. The realistic motivator was a cross-package mix-up likecert.Settings(jwx.WithUseNumber(true)).That scenario is a compile error today —
jwx.GlobalOptionandcert.GlobalOptioneach carry their own unexportedglobalOption()marker on their own*globalOptionstruct (jwx/options.go:8-17,cert/options.go:6-15). Because the marker is unexported, the two interfaces are not compiler-interchangeable despite both wrappingoption.Interface. TheSettingsloops can never receive a foreign-package option.Remaining failure modes are internal-only generator-drift cases adequately covered by per-option test discipline. Adding
default: return errorwould be a future-contributor safety net but address no user-facing risk; v3 backport is also impossible (v3'sSettingsreturns no error).Doc-only PR adding a
Settingsunknown-option handling subsection to.claude/docs/internals.mdso future review agents see the design intent and don't re-flag.Resolves JWA-003 as WONTFIX.