Conversation
…pply AUTH_REQUIRED prose tightening to main Two patch-level changesets on `main` describe work that has already shipped to 3.0.x and is also already on `main`. They are genuine forward-merge leftovers — the changeset files survived the merge but the work they describe was already in-tree. Without this cleanup, the next 3.1.0 cut would emit duplicate CHANGELOG entries claiming new patch-level work for code that shipped weeks ago. Deleted: - `.changeset/envelope-field-present-check-type.md` — the `envelope_field_present` check type already lives in `static/compliance/source/universal/storyboard-schema.yaml` on `main` (and shipped on 3.0.x as 3.0.2 via 9dcf7aa). - `.changeset/fix-asset-union-dedup.md` — `static/schemas/source/core/assets/asset-union.json` already exists on `main` (and shipped on 3.0.x as 3.0.2 via 9dcf7aa). The third "looks-stale" changeset, `auth-required-prose-tightening-3.0.x.md`, is a different shape: the changeset file is on `main` but the prose tightening it describes is NOT — `main`'s `AUTH_REQUIRED` description still reads "Authentication is required to access this resource" with no retry-storm warning. So `main`'s `AUTH_REQUIRED` carries the same operational risk 3.0.x already remediated: agents that conflate "credentials missing" with "credentials presented but rejected" retry-loop on revoked tokens against seller SSO endpoints, in a pattern indistinguishable from brute-force probes. Applied the same prose tightening that 3.0.x shipped in 3.0.4: - `static/schemas/source/enums/error-code.json` — `enumDescriptions.AUTH_REQUIRED` and `enumMetadata.AUTH_REQUIRED.suggestion` rewritten to spell out the two sub-cases and the SHOULD-NOT-auto-retry rule. - `docs/building/implementation/error-handling.mdx` — adds the `AUTH_REQUIRED sub-cases` callout under the Authentication and Access table; the example switch now branches on whether credentials were attached. Wire format unchanged on `main`. No new enum values. No recovery classification change at the structured level. The 3.1 line will still split this into `AUTH_MISSING` / `AUTH_INVALID` via #3739; until that lands, the prose tightening is the only operational guidance against the retry-storm pattern, and `main` should not regress relative to 3.0.x. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
Three review passes converged on the same surface: - Restructure the AUTH_REQUIRED enumDescription to match the established GOVERNANCE_DENIED pattern (one-sentence summary + recovery hinge, then `\n\nSub-cases (full guidance). …`). Adds an explicit cross-reference to error-handling.mdx#auth_required-sub-cases so readers can navigate from the schema hover to the docs anchor. - Drop the temporal "agents handling 3.0.x sellers" phrasing — temporal/version-aware copy is for CHANGELOGs, not enumDescriptions surfaced in 3.x SDK hovers. Replaced with neutral "until that ships". - Shorten enumMetadata.AUTH_REQUIRED.suggestion to a half-sentence imperative, matching the style of other suggestion values. - Promote the AUTH_REQUIRED sub-cases H4 to a Mintlify Warning callout immediately under the Authentication and Access table. The orphan H4 read as competing with the next H3 Billing and Account Setup; the callout integrates the depth without adding an out-of-band heading. - Fix the JS example so it stops introducing requestHadCredentials as a free variable. Both the inline snippet and the lower switch-case block now derive it locally with a comment pointing at error.request_had_credentials — a reader pasting the snippet no longer hits ReferenceError. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…red-retry-storm-prose The existing changeset's framing called itself a "3.0.x prose-only backport of #3739", which is correct for 3.0.x but reads oddly on main — main isn't backporting from itself, it's adopting the same prose tightening that 3.0.x already shipped in 3.0.4 because main's enum split (#3739) hasn't landed yet. Renames the changeset file (which makes it count as new for the changeset CI check) and rewrites the description to fit main's release framing without losing the operational rationale. Also rolls in a one-line note about the two stale changeset deletes already in this PR so the 3.1.0 CHANGELOG entry mentions them. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
Two patch-level changesets on `main` describe work already shipped to 3.0.x and already in-tree on `main` — genuine forward-merge leftovers that would emit duplicate CHANGELOG entries on the next 3.1.0 cut. A third "looks-stale" changeset turns out to describe operational guidance `main` actually still needs.
Audit
Why apply the AUTH_REQUIRED prose to `main` rather than delete
`main`'s `AUTH_REQUIRED` description currently reads "Authentication is required to access this resource" with no retry-storm warning. The same operational risk 3.0.x already remediated applies on `main`: agents that conflate "credentials missing" (correctable) with "credentials presented but rejected" (terminal — needs human rotation) retry-loop on revoked tokens against seller SSO endpoints, in a pattern indistinguishable from brute-force probes. The seller's fraud detection may rate-limit, suspend, or alert on the calling agent.
The 3.1 line will still split this into `AUTH_MISSING` / `AUTH_INVALID` via #3739. Until that lands, the prose tightening is the only operational guidance against the retry-storm pattern, and `main` should not regress relative to 3.0.x.
Changes
Wire-format impact
Wire format unchanged on `main`. No new enum values. No recovery classification change at the structured level. Senders that already emit `AUTH_REQUIRED` keep working; receivers gain the documented sub-case discipline.
Test plan
🤖 Generated with Claude Code