Skip to content

test: cover the payment-terms cross-field invariants (terms.md) - #89

Open
vishkaty wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:test/payment-terms-conformance
Open

vishkaty wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:test/payment-terms-conformance

Conversation

@vishkaty

@vishkaty vishkaty commented Aug 14, 2026 •

Copy link
Copy Markdown
Contributor

Adds a conformance module for the payment-terms capability that landed in ucp#602, covering the cross-field invariants the JSON schema cannot express. Offered in the #602 review thread (ucp#692 discussion) once the shape settled.

What it checks (all against the raw wire payload, following the totals_test.py stance):

Test Invariant Spec anchor (terms.md)
selected_term_names_an_offered_term terms non empty when present; selected_term_id present and names exactly one terms[].id Where terms is present it MUST contain at least one term, and selected_term_id MUST name one of them
term_ids_unique_within_checkout terms[].id unique A Business MUST make terms[].id unique within a Checkout
selected_term_schedules_sum_to_checkout_total selected term schedule amounts sum to the checkout total For the selected term, the Business MUST ensure that sum equals the checkout total
selecting_each_term_recomputes_the_checkout each selection is honored, or the change is reported with a payment_term_changed warning — including when the requested term stays selected but is rewritten in place (schedules, due dates, amounts); the responses selected term always resolves and keeps the sum invariant; selections drawn from the latest response terms[] a business resolving a selection conflict MUST report the change as a payment_term_changed warning, and MUST also report it when changing the selected term in place without naming a different term; a Platform can therefore detect a changed selection from the code alone
unresolvable_selection_is_not_silently_substituted an unknown selected_term_id is either rejected or answered with a payment_term_changed warning, never a silent substitute; a control update with a valid id must succeed first so a 4xx is attributable to the id MUST NOT silently substitute a term, and MUST report the change as a payment_term_changed warning in messages[]
accepted_term_travels_to_the_order order carries payment.accepted_term for the term selected once the checkout REACHED ready_for_complete (skips honestly if readiness is not observed); its schedules sum to the order total at creation; asserts on the embedded order or follows the id to GET /orders/{id} (the order_test pattern) Carry the accepted term onto the Order; MUST ensure its schedule amounts sum to the Order total; the term is already agreed before ready_for_complete
due_at_when_present_is_rfc3339 every stated due_at matches the RFC 3339 shape (lowercase t/z and leap seconds accepted per the RFC; naive datetimes without a UTC offset rejected as not absolute) with calendar fields range checked due_at is an absolute RFC 3339 date-time

Conformant variability is accepted, not just the happy path. A business that answers a valid selection by keeping the previous term with a payment_term_changed warning (a selection conflict), changes its default term during fulfillment updates (warned), embeds only an order reference at completion, changes which terms are offered across responses, or rejects an unresolvable selection with a 4xx instead of warning: all pass. Each of these is exercised as its own verification mode.

Gating and current CI behavior. The module gates on dev.ucp.common.payment.terms in /.well-known/ucp (the discount_test.py pattern) and additionally skips when the driven checkout carries no terms, since offering terms on a given checkout is a business decision. Against the current sample server the module skips cleanly (verified against samples main); the checks activate the day a business or the reference advertises the capability.

Verification. Exercised against a minimal golden business implementing the extension: 2 answer postures and 6 additional spec-sanctioned behavior variants all PASS (including an in-place term rewrite that is correctly warned); 11 violation mutants across 14 matrix rows each fail the intended test (wrong schedule sum, duplicate term ids, dangling and missing selected_term_id, ignored selection, silent substitution, missing and mis-summing accepted_term with both full and reference-only order embeds, malformed and naive due_at). Broad violations (a dangling selection, duplicate ids) legitimately fail every test that resolves the selected term; the selection, silence, order, and due_at tests each also have a surgical killer that fails them alone. Ruff lint and format clean per the repo config.

Notes and limits.

  • Assertions are wire level dict reads, so nothing here depends on the SDK carrying payment_terms models.
  • Not asserted: that checkout terms are absent from the order (stated by the spec but additionalProperties true makes an extra field schema legal rather than a MUST violation); the disclosure travel MUSTs (they need a business with a disclosure bearing term to drive; follow-up once a reference implements one); the totals difference entry MUST (whether a term changes what the purchase costs is not observable server-agnostically); selected_term_id absent when terms absent (unreachable given the no-terms skip).
  • A business that churns term ids on every response without reporting payment_term_changed would still fail the selection test; the spec's own detection-from-the-code-alone sentence is read as making the warning the required signal for any changed selection.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Aug 14, 2026
@damaz91

damaz91 commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Thanks for working on this. Let's put this on-hold until the new UCP version + SDK is launched

@damaz91 damaz91 added status:blocked and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 17, 2026
@vishkaty

Copy link
Copy Markdown
Contributor Author

Sounds good, and once the new version and SDK are out I will re verify the module against the released text and refresh this PR to match.

@vishkaty

Copy link
Copy Markdown
Contributor Author

The hold condition here has cleared: v2026-08-25 is released and ucp-sdk 0.5.0 is published. Refreshing the module against the released text, and noting the payment constructs moved from shopping to common in ucp#741, so the import this module uses is absent in 0.5.0 while this repo still pins 0.4.4. Will push the refreshed branch shortly.

@vishkaty
vishkaty force-pushed the test/payment-terms-conformance branch from 80ca776 to 5bf15b1 Compare August 31, 2026 00:21
@vishkaty vishkaty changed the title test: cover the payment-terms cross-field invariants (payment-terms.md) test: cover the payment-terms cross-field invariants (terms.md) Sep 1, 2026
@vishkaty

Copy link
Copy Markdown
Contributor Author

Status update, since the hold condition here has now cleared.

UCP v2026-08-25 released on 2026-08-25, and ucp-sdk v2026-08-25 (0.5.0) followed
on 2026-08-27.

I have not refreshed the branch yet, because the suite itself still targets the
previous version: pyproject.toml pins ucp-sdk==0.4.6, the workflow checks out
python-sdk at v2026-04-08-6, and integration_test_utils.py sets
DEFAULT_UCP_VERSION to 2026-04-08. Payment terms moved from shopping to
common in ucp#741, so a module written against the released text imports a path
that does not exist at the pinned SDK, and the job would fail for that reason
rather than on the assertions.

That adoption is tracked separately in #104. Two options from here, whichever you
prefer:

  1. I refresh this branch against 2026-04-08, which is what CI can run today, and
    revisit the 2026-08-25 shapes when Adopt ucp-sdk 0.5.0 so the suite can assert 2026-08-25 behaviour #104 lands.
  2. I hold until Adopt ucp-sdk 0.5.0 so the suite can assert 2026-08-25 behaviour #104 resolves and then refresh once against the released text.

Happy either way, and happy to leave it on hold if the suite has a different
sequencing in mind.

@damaz91 damaz91 added status:stale Applied when PR is waiting for author response for 30 days and removed status:blocked labels Oct 11, 2026

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — thank you for refreshing this suite for the v2026-08-25 release and covering all seven dev.ucp.common.payment.terms invariants, @vishkaty!

Everything aligns cleanly with docs/specification/payment/extensions/terms.md and source/schemas/common/payment_terms.json:

  • PT-001 – PT-003 (test_selected_term_names_an_offered_term, test_term_ids_unique_within_checkout, test_selected_term_schedules_sum_to_checkout_total): selected_term_id presence/resolution, terms[].id uniqueness, and schedules[].amount integer validation and sum to the checkout total.
  • PT-004 & PT-005 (test_selecting_each_term_recomputes_the_checkout, test_unresolvable_selection_is_not_silently_substituted): Term selection updates (_select_term), in-place schedule rewrite detection (_term_shape), control PUT verification (_raw_selection_put) before probing an unresolvable selected_term_id, and checking for payment_term_changed in messages[] or 4xx rejection.
  • PT-006 & PT-007 (test_accepted_term_travels_to_the_order, test_due_at_when_present_is_rfc3339): Anchoring selected_id at ready_for_complete, verifying order.payment.accepted_term ID and schedule sum via _fetch_order, and validating RFC 3339 date-time format and calendar bounds on schedules[].due_at.
  • The fallback import for Payment (common.types.payment -> shopping.payment) also keeps the test compatible across ucp-sdk versions.

@vishkaty
vishkaty force-pushed the test/payment-terms-conformance branch 2 times, most recently from 3a69b13 to 93de62f Compare November 10, 2026 17:33
@vishkaty

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 79a0f40f and added payment_terms_test to SUITE_REGISTRY, since #120
made the registry the only path --suite=all runs. Before the entry, --suite=all selected
none of this module; with it, 85 cases, of which seven are its own.

Run against the sample server booted from samples main 52319dff: 7 skipped, with the reason
the description already gives, since nothing in the reference advertises
dev.ucp.common.payment.terms. I rechecked that string against the samples tree and it does not
appear, and the live profile advertises checkout, cart, order, discount, fulfillment and
buyer_consent only. So registering the module makes it reachable and it still skips until a
business or the reference advertises the extension, which is the stated intent.

Once #121 lands this file moves under shopping/ and the entry becomes a dotted path.

@damaz91 damaz91 added status:under-review and removed status:stale Applied when PR is waiting for author response for 30 days labels Nov 10, 2026
Seven cases over the payment terms extension, asserted against the raw wire
payload: schedule sums, term id uniqueness, selected_term_id resolution,
selection handling, and accepted_term on the order.

Placed as `common/payments/terms_test.py` and registered as
`common.payments.terms_test`, following the layout Universal-Commerce-Protocol#121 landed. Payment terms
is a common payment extension, which is why it sits beside the other payment
modules rather than under `shopping/`.

Universal-Commerce-Protocol#120 made `SUITE_REGISTRY` the only path `--suite=all` runs, so the entry is
what makes the module reachable: without it `--suite=all` selects none of
these seven.

Run against the sample server from samples main: 7 skipped, for the reason the
description gives, since nothing in the reference advertises
`dev.ucp.common.payment.terms`.
@vishkaty
vishkaty force-pushed the test/payment-terms-conformance branch from 93de62f to 1246fb4 Compare November 11, 2026 19:41
@vishkaty

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 1201fb78 now that #121 has landed, and relocated.

The test content is unchanged. The file is now common/payments/terms_test.py, beside the other
payment modules rather than under shopping/, since payment terms is a common payment
extension, and SUITE_REGISTRY gains common.payments.terms_test.

Measured on this head against the sample server from samples main: 7 skipped, for the reason the
description gives, since nothing in the reference advertises dev.ucp.common.payment.terms.
Without the registry entry --suite=all selects none of the seven; with it, 85.

damaz91 and others added 2 commits November 16, 2026 09:06
…nformance

The spellcheck job flagged three coined words in this module. They are
reworded rather than added to .cspell/custom-words.txt, since no other file
in the tree uses them.

Running the cases for the first time found four defects in them. The reference
serves 2026-04-08, where dev.ucp.common.payment.terms is not defined, so all
seven skip against it; they were exercised behind an overlay that serves the
extension, and each correction below has a server that fails the old code and
passes the new one.

PT-006 could not reach its assertions. It created the checkout with
select_fulfillment=False and then called ensure_fulfillment_ready, and with no
fulfillment on the create that helper has no method to update, so it builds
one from nothing. The reference rejects that payload for two missing members,
id and line_item_ids, of which fulfillment_method.json marks line_item_ids
"update": "required" at the served version and id "update": "optional". The
case fails on the 422 before asserting anything. The build-from-nothing path
is reported upstream in Universal-Commerce-Protocol#102. This case now creates with fulfillment, the path
every other completing case in the tree already uses. Against a business that
honors the selection on create, as the reference does, readiness then issues
no update at all; against one that does not, the helper updates the method the
create supplied instead of building one.

PT-005 treated a refusal as a silent substitution. A business may decline an
unresolvable selected_term_id through the message channel rather than an HTTP
4xx, returning the checkout with a recoverable error for the platform to
correct in band. Only an error the probe produced now counts, and only when
the selection and the schedules of the term in effect are both unchanged: an
incomplete checkout already lists what it still needs as recoverable errors,
so counting those would excuse a business that ignored the selection
outright, and a refusal that rewrites the term in effect is the case the
warning exists to report.

PT-004 applied the in-place warning rule to every offered term. terms.md
states that unselected terms are indicative and directs a platform not to
assume the amounts in terms[] survive selection unchanged, so the module takes
the narrower reading: the rule binds only the term already in effect, which is
what the case docstring described. The walk now visits that term first,
because otherwise the rule is unreachable for a business that lists its
default term anywhere but first.

_new_terms_checkout skipped when terms[] was present but empty, which no case
could then catch. payment_terms.json puts minItems 1 on terms and terms.md
requires at least one term where terms is present, so that is asserted.

Verified against the flower shop reference with the CI pinned SDK at
v2026-04-08-6: --suite=all gives 90 executed, 81 passed, 9 skipped, 0
failures; the pinned pre-commit, ruff, ruff format and cspell are clean.
Behind the overlay all seven cases pass, and fourteen servers each breaking
one stated obligation redden their own case, including one that silently
ignores the selection while carrying an unrelated recoverable error, one that
refuses and rewrites the term in effect, and one that lists its default term
second.
@vishkaty

Copy link
Copy Markdown
Contributor Author

Spellcheck was the red check, and the three flagged words are reworded in
place rather than added to .cspell/custom-words.txt, since no other file in
the tree uses them.

Fixing only the spelling felt wrong without saying what running the cases
turned up, so this covers that too. The module gates on discovery, and the
reference serves 2026-04-08, where dev.ucp.common.payment.terms is not
defined; the extension first appears at v2026-08-25. All seven cases
therefore skip against the flower shop and contribute no signal to this repo
CI today. Behind an overlay that serves the extension, three of the cases
and one helper they all share turned out to be wrong.

PT-006 could not reach its assertions. It created the checkout with
select_fulfillment=False and then called ensure_fulfillment_ready, and with no
fulfillment on the create that helper has no method to update, so it builds
one from nothing. The reference rejects that payload for two missing members,
id and line_item_ids, of which fulfillment_method.json marks line_item_ids
"update": "required" at the served version and id "update": "optional". The
case fails on the 422 before asserting anything. That build-from-nothing path
is already reported in #102 item 2, so nothing here touches the helper: the
case now creates with fulfillment, the path every other completing case in
the tree already uses.

PT-005 treated a refusal as a silent substitution. A business may decline an
unresolvable selected_term_id through the message channel rather than an HTTP
4xx, returning the checkout with a recoverable error for the platform to
correct in band. Only an error the probe produced now counts, and only when
the selection and the schedules of the term in effect are both unchanged.
Both conditions matter: an incomplete checkout already lists what it still
needs as recoverable errors, so counting those would excuse a business that
ignored the selection outright, and a refusal that rewrites the term in
effect is the case the warning exists to report.

PT-004 applied the in-place warning rule to every offered term, and failed a
business with a message saying a term had been kept selected and rewritten,
of a term that had not been selected before. terms.md states that unselected
terms are indicative and directs a platform not to assume the amounts in
terms[] survive selection unchanged, so the module takes the narrower
reading: the rule binds only the term already in effect. The walk now visits
that term first, because otherwise the rule is unreachable for a business
that lists its default term anywhere but first.

_new_terms_checkout skipped when terms[] was present but empty, so a server
returning an empty list passed all seven cases by skipping them.
payment_terms.json puts minItems 1 on terms and terms.md requires at least
one term where terms is present, so that is asserted.

Verified on the branch as it stands, against the flower shop reference with
the CI pinned SDK at v2026-04-08-6:

  • uv run ucp-conformance --suite=all: 90 executed, 81 passed, 9 skipped,
    0 failures, exit 0
  • pinned pre-commit run --all-files, ruff check, ruff format --check: clean
  • cspell with .cspell.json over the changed files: 0 issues
  • behind the overlay: all seven cases pass, and fourteen servers each
    breaking one stated obligation redden their own case, including one that
    silently ignores the selection while carrying an unrelated recoverable
    error, one that refuses and rewrites the term in effect, and one that lists
    its default term second. Two servers that are conformant on a fair reading,
    one refusing by recoverable error and one recomputing a term as it is first
    selected, pass all seven, and the original mutant matrix is unchanged by
    the PT-004 and PT-005 corrections.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants