Skip to content

spec(delivery): define composable destination constraints - #13

Draft
ericfj2140 wants to merge 1 commit into
codex/spec-refactor-transpositionfrom
proposal/destination-constraints
Draft

spec(delivery): define composable destination constraints#13
ericfj2140 wants to merge 1 commit into
codex/spec-refactor-transpositionfrom
proposal/destination-constraints

Conversation

@ericfj2140

Copy link
Copy Markdown

Summary

Propose a versioned, composable destination-constraint grammar for kind 30406 shipping options. The proposal keeps ISO country and subdivision codes as shared primitives while adding country-scoped postal inclusion and exclusion rules with deterministic, fail-closed evaluation.

This PR is intentionally stacked on #1 and targets codex/spec-refactor-transposition so the semantic proposal remains separate from the repository reorganization.

Why

The current country and optional region tags identify administrative areas but do not define combination, exclusion, postal-zone, or overlap semantics. That leaves ordinary shipping policies—such as country-wide service with subdivision or postal exclusions—dependent on private tags or out-of-band interpretation. A client that ignores those rules can offer an automatic checkout price for a destination the merchant did not agree to serve.

Shipping constraints also vary by country. The shared protocol should define portable predicates and deterministic matching without pretending that one universal address form or ISO subdivision list captures every carrier service area.

What changed

  • Add an experimental delivery proposal with a destination_schema marker and typed destination include/exclude selectors.
  • Define country, ISO subdivision, and country-scoped postal exact/prefix shapes.
  • Define normalization, union/subtraction, completeness, unknown-rule, overlap, and order-first fallback behavior.
  • Model each distinct service, price, currency, and destination policy as its own kind 30406 option.
  • Clarify that Plus Codes are useful as optional encrypted delivery locators, not as postal or carrier eligibility rules.
  • Add compatibility guidance for current country, region, and existing country-scoped postal rules.
  • Link the proposal from the delivery pillar without modifying the normative SPEC.md compatibility snapshot.

Validation

  • Confirmed the branch parent is the current Reorganize specification navigation #1 head commit, 40a8d22d9bce1f8740d60bbf0dc4e25f6b7ef192.
  • Confirmed SPEC.md, current event kinds, existing tag examples, and normative transposition text remain unchanged.
  • Ran git diff --check against codex/spec-refactor-transposition.
  • Reviewed all example tag shapes for consistent country scoping and fail-closed behavior.
  • Checked the proposal against ISO 3166, Universal Postal Union addressing guidance, and Open Location Code documentation.

Runtime or visual evidence

Documentation-only experimental proposal; there is no runtime or visual surface.

Risks and follow-ups

  • Postal exact and prefix intentionally avoid arbitrary regex behavior; numeric range semantics remain a possible versioned follow-up.
  • Country-specific authoring and validation profiles still require implementation experience and review from merchants and delivery providers.
  • If accepted, the proposal must be transposed into SPEC.md and the normative kind 30406 examples as one coherent change. Adding only part of the grammar would allow clients to mistake coarse country metadata for sufficient automatic-checkout eligibility.

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