Skip to content

docs: correct circular reasoning about the message_* variant refs - #15

Merged
chaz8081 merged 1 commit into
mainfrom
variant-refs-fix
Aug 23, 2026
Merged

docs: correct circular reasoning about the message_* variant refs#15
chaz8081 merged 1 commit into
mainfrom
variant-refs-fix

Conversation

@chaz8081

Copy link
Copy Markdown
Owner

Two corrections to what #14 recorded, both found by re-reading python-sdk#83 properly.

1. The count reasoning was circular

#14 said six of the twelve base-pointing refs are correct, because message_error, message_info and message_warning have no request variants to point at.

They have no request variants because of this same defect. Variant need is propagated by scanning a schema for external refs — and that scan skips top-level composition keywords, which is precisely why the refs are not rewritten. So nothing ever marks those three as needing a variant. The missing files are a symptom of the bug, not evidence that the bug does not apply there.

The behavioural counts are unchanged and still correct: 4 refs cause real harm today (fulfillment_destination create/update), 2 are wrong but inert (postal_address's variant is identical to its base). What changes is that the remaining six are not a clean bill of health — they are the bug hiding one layer down.

2. The fix is larger than described

Because those variants are missing because of the defect, upstream's fix creates them. #83 adds fourteen new schemaserror_code, info_code, warning_code, message_error, message_info, message_warning, signed_amount, each in create and update form.

The corpus goes 145 → 159 files. Every count in the README ending in 145 moves when this lands. That is a materially bigger port than "rewrite six refs," and worth knowing before starting it.

3. The upstream status in #14 was wrong

#14 said #83 fixes a SyntaxError in downstream codegen that #35's change triggers, and that "only #35 would affect us."

#83 is the fix: it carries the same preprocess_schemas.py change as #35, plus the postprocess_models.py fix that change requires, plus regenerated models and a pipeline test. It supersedes the community PR.

I had read the first 30 lines of the diff, which land in postprocess_models.py because it sorts before preprocess_schemas.py, and generalized from that hunk to the whole PR.

The guard test needed no change

Its mechanism was already right. The os.Stat check excludes the message_* refs only while the variants do not exist — so the moment upstream creates them, the check starts matching and the test reports message_create_request and message_update_request as newly affected. That failure is the intended signal.

Only the comment explaining the exclusion was wrong, and it now says why the exclusion is temporary.

Verification

gofmt clean, go build, go vet, root tests and the conformance module all pass. No generated output changed — documentation and one test comment only.

PR #14 claimed six of the twelve base-pointing refs are correct because
message_error, message_info and message_warning have no request variants
to point at. That reasoning is circular: they have no request variants
BECAUSE of this same defect. Variant need is propagated by scanning a
schema for external refs, and that scan skips top-level composition
keywords for exactly the reason the refs are not rewritten, so nothing
ever marks those three as needing a variant. The missing files are a
symptom, not independent evidence.

Upstream's fix therefore does more than rewrite refs: python-sdk#83
creates fourteen new schemas — error_code, info_code, warning_code,
message_error, message_info, message_warning and signed_amount, each in
create and update form — taking the corpus from 145 files to 159. Every
count in the README ending in 145 moves when it lands.

Also corrects the upstream status recorded in #14. python-sdk#83 is not a
companion fixing a SyntaxError that #35 triggers; it is the fix itself,
carrying the same preprocess_schemas.py change plus the downstream
codegen fix it requires plus regenerated models, and it supersedes #35.
The earlier claim came from reading the first hunk of the diff, which
lands in postprocess_models.py, and generalizing from it.

The guard test's mechanism was already right and is unchanged — the
os.Stat check will start matching the moment those variants exist, so the
test reports message_create_request and message_update_request as newly
affected. Only the comment explaining why they are excluded was wrong.
@chaz8081
chaz8081 merged commit 28d2cdf into main Aug 23, 2026
2 checks passed
@chaz8081
chaz8081 deleted the variant-refs-fix branch August 23, 2026 02:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant