feat: add deterministic schedules to lodging cancellation policies

[yairsabag]

Description

Adds an optional cancellation schedule to the Lodging policy introduced by
#780, so a Platform can select the applicable cancellation terms at an explicit
instant. For example, a booking can offer a full refund before its 48-hour
cutoff and select a one-night penalty exactly at that cutoff.

The schedule contains an absolute anchor, ordered relative cutoffs, and
percentage, fixed-fee, or shared-measure outcomes. The required refundability
snapshot and human-readable description remain. The change implements #807
and is limited to buyer-initiated, pre-purchase policy disclosure.

Stacked PR status

• Base: feat: Introduce Lodging Booking Capability and Cancellation Policy Extension #780 branch lodging/booking
• Enhancement Proposal: [Proposal]: Add deterministic schedules to lodging cancellation policies #807
• Draft for technical review; do not merge before EP approval and feat: Introduce Lodging Booking Capability and Cancellation Policy Extension #780
• After feat: Introduce Lodging Booking Capability and Cancellation Policy Extension #780 merges, rebase or rebuild on main and re-verify the diff

Behavior and compatibility

• schedule is optional and response-only; existing classification-only
  payload shapes remain valid.
• refundability is the Business's authoritative response-generation summary;
  explicit-instant evaluation selects a schedule outcome without extrapolating
  that snapshot or guessing a monetary basis.
• Cutoffs are half-open. Arithmetic uses Unix time (POSIX), exact comparisons,
  and 86400-second days. Calendar validity and ordering are checked before
  selection; unsupported timestamps and invalid schedules fall back to prose.
• Percentage and unit outcomes stay symbolic unless Booking data supplies an
  unambiguous monetary basis. Fixed fees use the root Booking currency.
  Policy targeting alone does not imply multiplication by matched-room count.
• This does not define cancellation/refund execution, no-show rules,
  purchase-relative cooling-off periods, or calendar-based durations.

Executable vectors

scripts/fixtures/lodging_cancellation_schedule.json contains portable inputs
and expected selection/fallback metadata. The test-only oracle in
scripts/test_cancellation_schedule.py checks 44 evaluation vectors and 22
schema expectations using the official schema tool and exact arithmetic.

Coverage includes cutoff equality, offsets/DST, fractional instants, equivalent
and reversed durations, invalid calendar dates, malformed unselected outcomes,
unknown selected/unselected kinds, trailing newlines, and a POSIX leap-boundary
case. It does not calculate money, infer refundability, or resolve targeting.
The suite is wired into docs.yml and the local pre-commit configuration.

Review questions

1. Should the portable fixture remain here or move to the conformance
   repository before merge?
2. Is shared UCP measure the preferred shape for positive whole lodging-unit
   penalties such as night?
3. This repository has no generated SDK model artifacts. Is an external SDK
   follow-up required for this stacked Draft?

Category (Required)

• Core Protocol
• Governance/Contributing
• Capability
• Documentation
• Infrastructure
• Maintenance
• SDK
• Samples / Conformance
• UCP Schema
• Community Health (.github)

Related Issues

• [Proposal]: Add deterministic schedules to lodging cancellation policies #807
• feat: Introduce Lodging Booking Capability and Cancellation Policy Extension #780
• Corpus-validated cancellation policy type for policies[] — seeking Lodging TC feedback #776
• feat: add policies[] to cart, checkout, catalog, and order #572

Checklist

• Contributing Guide and non-breaking Conventional Commit title
• Documentation and relevant JSON schema updated
• Executable evaluation fixtures and test runner added
• Documentation examples and targeted tests pass locally
• Final conformance-fixture location agreed with maintainers
• All repository pre-commit hooks pass
• Container-based Super-Linter completes
• Generated SDK models updated or confirmed unnecessary

Validation

Validation for 7b4e654:

• ucp-schema lint source/: 139 files pass; existing W002 warnings only
• documentation examples: 379 pass, 0 failures/errors, 50 explicitly skipped
• cancellation suite: 44 selection/fallback vectors and 22 schema expectations
  pass; independently reviewed and rerun
• strict specification documentation build: passes
• changed-file Ruff, Markdown, spelling and YAML checks: pass
• all repository pre-commit hooks: pass, including the new cancellation suite

Local Super-Linter could not run because the Docker daemon is unavailable. There is
no sdk/python/generate_models.sh in this repository checkout; SDK follow-up
is an explicit review question.

The CLA check passes. Existing PR workflow triggers target main and
release/**, so these local validation results are necessary while this
stacked Draft targets lodging/booking.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[yairsabag]

@googlebot rescan

[yairsabag]

@jingyli, could you point me to an engineer implementing a UCP Lodging consumer who might be open to a small interoperability test of the schedule proposed in #807 and this draft?

I can help adapt one synthetic or publicly shareable lodging policy fixture and contribute a focused integration patch to select the applicable cancellation terms at a supplied instant, including cutoff boundaries and fallback behavior. This would remain pre-purchase disclosure only, with no payment/refund execution or inferred monetary bases.

The aim is to test the proposal against a consumer implementation beyond the executable vectors here. A pointer to the right contact or venue would be appreciated. This is exploratory feedback, not a dependency for #780.