Skip to content

Govern actor & payment grammar; tighten purchase and ship semantics#9

Merged
GsCommand merged 2 commits intomainfrom
codex/implement-coherence-upgrades-for-commercial-protocol
Mar 19, 2026
Merged

Govern actor & payment grammar; tighten purchase and ship semantics#9
GsCommand merged 2 commits intomainfrom
codex/implement-coherence-upgrades-for-commercial-protocol

Conversation

@GsCommand
Copy link
Contributor

Motivation

  • Create a single, governed commercial language across authorize, checkout, purchase, ship, and verify so the repo reads as one protocol rather than a set of ad-hoc schemas.
  • Make ship clearly settlement-adjacent (fulfillment tied to an upstream commercial transaction) and lift purchase to be a first-class, well-evidenced one-step contract.
  • Normalize x402/payment vocabulary and actor roles repo-wide so payment requirements, session state, and final proof are consistently named and evidence flow is predictable.

Description

  • Standardized actor grammar by introducing per-schema $defs for actor_identity plus role-constrained aliases (payer_actor, payee_actor, merchant_actor, provider_actor, carrier_actor, verifier_actor) and replaced loose actor refs with these role-specific refs across all v1.1.0 commercial schemas.
  • Normalized payment/x402 grammar to three canonical layers: payment_requirement (pre-payment), payment_session (live session), and payment_proof (final evidence), and aligned request/receipt fields and reference enums to use these names consistently.
  • Reworked purchase into a deliberate one-step contract by adding itemized items, amount_breakdown, payment_input (accepting requirement/session/proof refs), normalized receipt statuses to captured/failed/pending, and requiring payment_proof on captured receipts.
  • Tightened ship semantics by making fulfillment_ref a typed fulfillment artifact, requiring an upstream commercial_ref (must be checkout or purchase), adding payer linkage, and strengthening evidence rules so tracking_url is required when tracking_number is present, active states require carrier+tracking, and delivered requires delivered_at and delivery_proof_ref.
  • Aligned authorize, checkout, and verify to the same actor/payment grammar (e.g., authorize emits payment_requirement_ref / authorization payment_proof, checkout and purchase require payment_proof on capture, verify accepts payment_proof and fulfillment targets).
  • Updated examples, README.md, SPEC.md, POLICY.md, manifest.json, and checksums.txt to document and reflect the new grammar and to teach the unified model.

Testing

  • Ran npm run validate to compile schemas and validate the current v1.1.0 line, and it completed successfully.
  • Ran npm run validate:examples to validate all current-line examples against the updated schemas, and it completed successfully.
  • Regenerated release integrity data with npm run generate:checksums and updated checksums.txt, and the checksums generation succeeded.

Codex Task

@GsCommand GsCommand merged commit 02a9606 into main Mar 19, 2026
1 check failed
@GsCommand GsCommand deleted the codex/implement-coherence-upgrades-for-commercial-protocol branch March 20, 2026 01:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant