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 52 selection/fallback cases and 26
schema expectations using the official schema tool and exact arithmetic.
It also checks 3 local-policy derivations and 8 complete outcome assertions.

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.

Public synthetic policy feedback

The synthetic hotel policy supplied in #780
is now represented by exact-boundary Phoenix cases. Derived New York spring/fall
examples separately verify local-calendar-to-instant resolution with IANA timezone
data before checking elapsed-offset selection. These are test-only examples of
unambiguous local times, not a new policy-template wire format or general compiler.

The fixtures distinguish symbolic one-night terms from a Business-resolved fixed
fee of 15000 minor units in root Booking currency USD. The latter carries a concrete
amount, not a machine-readable room-rate/tax basis; that representation gap remains
open. No schema fields or selection semantics changed in this follow-up.

Independent agent-disclosure study fixtures

Commit 365329a
adds 10 synthetic policy scenarios and 36 evaluation instants for paired
classification-plus-prose / schedule-added agent experiments:

• Portable fixtures
• Usage, provenance, and interpretation

The cases cover Phoenix and New York DST boundaries, multiple tiers,
non-refundable terms, symbolic outcomes without a monetary basis, malformed
schedules, and a prose/schedule conflict probe. Agent-visible data is separated
from held-out expectations. Conflict detection is exploratory; it does not
introduce a requirement to parse all legal prose for contradictions.

These are experiment inputs, not model results, official conformance tests,
or evidence of proposal approval. No customer agreements are included.
No wire schema or selection semantics changed.

Local validation for this follow-up: 10 scenarios, 36 evaluations, and 10
mutation checks pass; all repository pre-commit hooks, existing cancellation
vectors, validator unit tests, documentation examples, and the strict
specification documentation build pass. The container-based Super-Linter
remains unavailable because the local Docker daemon is not running.

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 a30b613:

• ucp-schema lint source/: 139 files pass; existing W002 warnings only
• documentation examples: 379 pass, 0 failures/errors, 50 explicitly skipped
• cancellation suite: 52 selection/fallback cases, 26 schema expectations,
  3 local-policy derivations, and 8 complete outcome assertions pass
• validator unit tests: 57 pass, 0 failures
• independent focused review and temporal mutation checks: pass
• strict specification documentation build: passes
• changed-file Ruff, Markdown, spelling and YAML checks: pass
• all repository pre-commit hooks: pass; CSS hook rerun successfully after
  installing the repository's locked Node development dependencies
• commit-message hooks: pass

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.