ap2_mandate_verifier 1.6.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,153 +1,131 @@
1
1
  # AP2 Mandate Verifier — Ruby SDK for Checkout and Payment
2
2
 
3
- ### 1.6.0 candidate: long Open and monthly JPY acceptance
3
+ [日本語](README.ja.md) · **Published stable: 1.6.0** · [Quick Start](docs/QUICK_START.md)
4
4
 
5
- An explicit long profile reuses the same signed Checkout/Payment Open pair across approved UTC calendar months. Content can last up to400days while each outer proof/start stays short-lived. Protected authority epochs, root/key replacement and atomic period/count/JPY reservations prevent retries or renewal from resetting allowance. Old profiles/defaults and the seven-input contract are unchanged. Unpublished; Owner release decision pending. [Contract/API and Python differences](docs/LONG_PAYMENT.md), [twelve-period Ruby acceptance/Receipt example](examples/long_payment_acceptance.rb), [release gates](docs/RELEASE_160_CANDIDATE.md). The bounded [ON_DEMAND complete/selective profiles](docs/RECURRING_PAYMENT.md) remain available.
6
-
7
- ```ruby
8
- # Protected enrollment + current authority synchronization are application duties.
9
- accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
10
- execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
11
- usage = store.usage(**trusted_series_scope) # reservations, not settlement
12
- ```
13
-
14
- ### Published1.5.0: transactional Payment acceptance
15
-
16
- Reserve a protected business occurrence atomically, reverify before one fenced start, and recover the original Receipt after response loss without reopening an uncertain attempt. [Verified publication](docs/POST_RELEASE_150.md). [Integration/store/security contract](docs/PAYMENT_ACCEPTANCE.md), [plain Ruby recovery example](examples/payment_acceptance.rb), [release gates](docs/RELEASE_150_CANDIDATE.md).
17
-
18
- ```ruby
19
- accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
20
- dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inputs) if accepted.ticket
21
- # Application-owned processor call uses dispatch.processor_key; no SDK payment call.
22
- ```
23
-
24
- Verification, durable reservation and settlement are separate. Use protected enrollment, one authoritative store and processor idempotency/lookup; no automatic timeout release. Existing1.x verifiers remain unchanged. The optional SQLite reference driver is installed separately.
5
+ Issue, present and verify supported AP2 Checkout and Payment Mandates in plain Ruby.
6
+ Use this Gem when your app needs to check what a buyer approved, what an Agent may
7
+ choose, and whether signed Checkout/Payment data stays within those conditions.
8
+ No Rails dependency. **Verification success is not purchase or payment success; the SDK never executes payments.**
25
9
 
26
10
 
27
- ### Published1.4.0: PISP and execution-date Payment conditions
11
+ **Platforms:** MRI 3.4.12 / 4.0.9; native published-Gem checks passed on Linux ARM64/AMD64, macOS Intel/Apple Silicon and Windows Server 2022 X64. These observations cover the recorded OS images; Rails demo compatibility is separate. See [platform evidence and reproduction](docs/PLATFORM_SUPPORT.md).
28
12
 
29
- Explicit Payment profiles now constrain approved PISPs and parsed inclusive execution windows, bound to independent application provider/time context. Existing1.x defaults remain unchanged. [Contract/API/official differences](docs/PAYMENT_POLICY.md), [plain Ruby three-mode example](examples/payment_policy.rb), [verified publication](docs/POST_RELEASE_140.md).
30
-
31
- ### Published 1.3.0: selective Checkout and Payment
32
-
33
- Keep the complete approved Open confidential and disclose only the merchant/products needed for Checkout, then selected payee/instrument candidates for Payment. Every mandatory condition and quantity remains enforced. [Profile/API/privacy/Python limits](docs/SELECTIVE_CHECKOUT.md), [plain Ruby combined lifecycle](examples/selective_checkout_payment.rb), [verified publication](docs/POST_RELEASE_130.md).
34
-
35
- ### Published1.2.0: selective Payment
36
-
37
- Published1.2.0 adds explicit `SelectivePayment` candidate-array disclosure: retain confidential full issuance, send selected payee/instrument disclosures only, and verify every mandatory condition and exact original-wire reference. [Profile/API/privacy/Python limits](docs/SELECTIVE_PAYMENT.md), [plain Ruby retained-vs-sent example](examples/selective_payment.rb), [verified publication](docs/POST_RELEASE_120.md). Existing `Payment` defaults remain unchanged.
38
-
39
-
40
- ### Payment lifecycle (since1.1.0)
41
-
42
- 1.1.0 adds Direct and conditional Payment Mandates plus signed Success/Error Payment Receipts. [Payment APIs and constraints](docs/PAYMENT.md), [plain Ruby lifecycle sample](examples/payment.rb), [verified publication](docs/POST_RELEASE_110.md), [GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v1.1.0). Verification does not grant execution permission; durable atomic one-use state and actual payment remain application responsibilities.
13
+ ## Start here
43
14
 
44
15
  ```sh
45
- gem install ap2_mandate_verifier --version 1.5.0
46
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/payment.rb"
16
+ gem install ap2_mandate_verifier --version 1.6.0
17
+ AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.0").full_gem_path')"
18
+ ruby "$AP2_GEM_DIR/examples/conditional_checkout.rb"
19
+ ruby "$AP2_GEM_DIR/examples/payment.rb"
47
20
  ```
48
21
 
49
- [日本語](README.ja.md)
50
-
51
- **Published stable: 1.5.0.**
52
-
53
- 1.0.0 establishes the stable public contract for the existing
54
- Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
55
- profiles, result meanings, saved formats and runtime implementation.
56
- See [the public API contract](docs/PUBLIC_API.md),
57
- [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and
58
- [1.0.0 release notes](docs/RELEASE_100.md). The official Gem matches the retained
59
- candidate; [publication verification](docs/POST_RELEASE_100.md) records its exact
60
- source, bytes and validation scope.
61
-
62
- ## Conditional purchase delegation
63
-
64
- Available since 0.8.0, `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`
65
- support this flow:
66
- approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
67
- a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
68
- `CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
69
- multi-item profile. Provider private keys never enter Agent operations.
70
- [API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [conditional code sample](docs/RELEASE_080.md) and [1.0.0 publication verification](docs/POST_RELEASE_100.md).
71
-
72
- Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
73
-
74
- ```sh
75
- gem install ap2_mandate_verifier --version 1.5.0
76
- ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/conditional_checkout.rb"
77
- ```
78
-
79
- The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
80
- public APIs, three rows, candidate choice, different requirement quantities and
81
- repeated products through both Receipt outcomes. Success consumes the operation;
82
- Error requires a new policy decision; missing Receipt or uncertain effect remains
83
- pending. Authentication, consent, enrollment, durable replay prevention and actual
84
- order/payment execution remain app-owned. Documented 0.8.0 API use needs no source
85
- migration; update the dependency constraint as described below.
86
-
87
- Direct and conditional workflows cover one merchant and 1–8 Checkout lines,
88
- including multiple products and quantities. Existing Direct and both Open→Closed
89
- profiles retain their contracts in 1.0.0.
90
-
91
- ## Multiple items and quantities
92
-
93
- Explicitly select `profile_ref: "ap2.checkout.single_merchant_multi_item"` when creating trust with `InputBuilder.trust`, signing a checkout with `CheckoutJWT.sign`, and using `CheckoutReceipt.reference/sign/verify`. The complete verifier follows the authenticated trust selection. The default `ap2.checkout.single_merchant_sku` v1 retains its exact definition, hash and one-line acceptance range.
94
-
95
- The multi-item v1 profile supports one merchant, one checkout, one currency and up to eight lines, with different quantities and repeated product IDs on distinct lines. It matches all disclosed product candidates using integer maximum flow: every requirement and every ordered unit must be consumed exactly once. Quantity shortages and extras reject. Requirement IDs and checkout line IDs are distinct identifiers. See the [multi-item contract and migration](docs/MULTI_ITEM_CHECKOUT.md), [synthetic runnable lifecycle](examples/multi_item_checkout.rb), and [official Python SDK differences](docs/MULTI_ITEM_INTEROP.md) for shortage, empty-candidate and Receipt-reference behavior.
96
-
97
- Verify purchase-delegation data in Ruby using a deliberately fixed AP2 profile. The Gem checks signed data against independently supplied Host trust and order information, then returns immutable Evidence. **Verification success is not purchase or payment permission.**
98
-
99
- `InputBuilder` converts business records into verification inputs: it creates the Gem-specific trust/selection/Host JSON, fingerprints and original-wire digests for you. You still choose whom to trust and supply the expected order, challenge state and clock. The Gem is Rails-independent and performs no network, database or payment operations.
100
-
101
- ## Try the local demo
102
-
103
- The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.8.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. It retains the existing synthetic Open→Agent Closed verification, multi-item and Success/Error Receipt screens. It has no conditional approval/issuance UI; use the standalone Ruby example above for that lifecycle. It is local-only and performs no real challenge issuance, nonce consumption or purchase/payment.
104
-
105
- ## Install
106
-
107
- Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
108
-
109
- ```sh
110
- gem install ap2_mandate_verifier --version 1.5.0
111
- ```
112
-
113
- Or add to your Gemfile:
114
-
115
- ```ruby
116
- gem "ap2_mandate_verifier", "~> 1.0"
117
- ```
118
-
119
- Runtime dependencies are pinned to JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2 and Digest 3.2.1. Normal installation may download/build dependencies; do not relax the pins to work around a conflict. The Ruby resolution interval is not certification of every Ruby version, OS or native provider. See the [support contract](docs/SUPPORT_CONTRACT.md).
120
-
121
- ### Upgrading from 0.8.0
122
-
123
- Documented 0.8.0 APIs, profiles, defaults and saved formats remain compatible.
124
- A constraint such as `~> 0.8.0` excludes 1.0.0. Change it to `~> 1.0` as above and
125
- update this Gem in the application's lockfile:
126
-
127
- ```sh
128
- bundle update ap2_mandate_verifier
129
- ```
130
-
131
- ## Merchant signing and Receipt
132
-
133
- Create a signed checkout, then sign the application's explicit outcome. These APIs were added in 0.5.0 and remain available in 1.0.0; the excerpt uses the default single-SKU profile.
134
- Here `checkout` is the application order Hash, `key` its P-256 signing key,
135
- `received_closed_sd_jwt` the original final inline SD-JWT and `now` the application clock:
136
-
137
- ```ruby
138
- signing = AP2MandateVerifier::CheckoutJWT
139
- signed = signing.sign(checkout: checkout, signer: signing.es256_signer(private_key: key),
140
- public_key_pem: key.public_to_pem)
141
- # Retain signed.jwt unchanged; use it as InputBuilder's host_checkout_jws.
142
- receipt = AP2MandateVerifier::CheckoutReceipt.sign(closed_sd_jwt: received_closed_sd_jwt,
143
- issuer: "shop", outcome: "Error", error: "declined", error_description: "Application declined",
144
- issued_at: now, signer: signing.es256_signer(private_key: key), public_key_pem: key.public_to_pem)
145
- ```
146
-
147
- Receipt verification separately checks a trusted public key, expected issuer,
148
- explicit time window and original closed-Mandate reference. An authentic Error
149
- Receipt has `verified? == true` and `purchase_succeeded? == false`.
150
- See the [complete runnable example](examples/merchant_signing.rb) and [API contract / SDK differences](docs/MERCHANT_SIGNING.md).
22
+ These installed examples create synthetic keys and approvals, issue/present/verify
23
+ Mandates, then authenticate alternative Success and Error Receipts. An authentic
24
+ Error Receipt reports failure. No account, credentials, database or Rails required.
25
+ Allow about ten minutes with a supported Ruby already installed; dependency builds
26
+ and Docker's first download can take longer.
27
+
28
+ **Next:** [step-by-step Quick Start and expected output](docs/QUICK_START.md),
29
+ including twelve UTC months and a cumulative JPY budget rejection.
30
+ [Docker demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)
31
+ uses published **1.6.0**, with local Checkout screens and Ruby Payment examples.
32
+
33
+ ## Choose a workflow
34
+
35
+ **Integrating a real application?** Start with the [Ruby integration and restart
36
+ recovery guide](docs/RUBY_INTEGRATION.md): protected application inputs, persistent
37
+ mock results, separate-process recovery and safe retry decisions. Use this repository
38
+ with published 1.6.0, or the bundled CLI in the 1.6.1 candidate. Public 1.6.0 does
39
+ not include this CLI; verify the 1.6.1 publication status before treating a candidate
40
+ as a registry release.
41
+
42
+ Checkout describes the order; a Checkout Mandate records approval/delegation for it.
43
+ A Payment Mandate adds payment conditions and references the Checkout approval.
44
+ Receipts authenticate an application's reported outcome for the original final Mandate;
45
+ they do not independently prove settlement.
46
+
47
+ | Workflow | Use when | API / guide |
48
+ | --- | --- | --- |
49
+ | Direct | Buyer approves an exact signed order/payment | `Buyer`, `Payment.issue_direct` · [Checkout](docs/BUYER_DIRECT_CHECKOUT.md) / [Payment](docs/PAYMENT.md) |
50
+ | Conditional delegation | Buyer approves candidates and limits; registered Agent chooses within them | `ConditionalCheckout`, `Payment.issue_open/issue_closed/present` · [Checkout](docs/CONDITIONAL_CHECKOUT.md) |
51
+ | Selective disclosure | Keep the full approved Open private and send selected merchant/product or payee/instrument candidates | `SelectiveCheckout`, `SelectivePayment` · [Checkout](docs/SELECTIVE_CHECKOUT.md) / [Payment](docs/SELECTIVE_PAYMENT.md) |
52
+ | Long Open | Reuse one approved Checkout/Payment Open pair across explicit UTC months, with finite count and cumulative JPY budget | `LongPayment`, `PaymentAcceptance::LongSQLiteStore` · [contract](docs/LONG_PAYMENT.md) |
53
+
54
+ Direct and conditional Checkout support one merchant and up to eight lines with
55
+ quantities under the explicit multi-item profile. The default single-SKU profile
56
+ retains its one-line contract. Selective profiles retain all mandatory conditions
57
+ and quantities; candidate count/order and issuer-JWT linkability are not hidden.
58
+ Long Open is a separate complete-disclosure profile (content up to 400 days,
59
+ short-lived proofs); it does not compose with selective or PISP/date profiles.
60
+ **Its UTC-monthly profile is not full compliance with generic AP2 MONTHLY semantics.**
61
+
62
+ Other explicit options: [PISP / execution-date constraints](docs/PAYMENT_POLICY.md),
63
+ [transactional acceptance and recovery](docs/PAYMENT_ACCEPTANCE.md), and bounded
64
+ [ON_DEMAND count / JPY budget profiles](docs/RECURRING_PAYMENT.md).
65
+ Existing 1.x API signatures, defaults, profiles and saved formats remain supported.
66
+
67
+ ## Choose your API by role
68
+
69
+ | Your component | Start with |
70
+ | --- | --- |
71
+ | Merchant backend | `CheckoutJWT.sign`; `CheckoutReceipt.sign/verify` |
72
+ | Trusted approval backend | `CheckoutJWT.verify` before consent; `Buyer.issue_closed` or `ConditionalCheckout.issue_open`; corresponding Payment issuance |
73
+ | Registered Agent | `Buyer.present_closed`, or conditional `issue_closed/present`; selective variants for supported disclosure profiles. Provider private keys stay in the approval backend. |
74
+ | Merchant / payment verifier | `Buyer.verify` for Direct; `InputBuilder.prepare/restore/verify` for conditional Checkout; `Payment.verify` for Payment plus Checkout binding; explicit selective/long variants |
75
+ | Receipt consumer | `CheckoutReceipt.verify`, `PaymentReceipt.verify`; check authenticity **and** reported outcome |
76
+ | App managing durable Payment acceptance | `PaymentAcceptance::Service` and the appropriate protected store; [integration contract](docs/PAYMENT_ACCEPTANCE.md) |
77
+
78
+ `verify_checkout` (also `verify_research`) is the complete seven-input conditional
79
+ Checkout entry. `InputBuilder` is the recommended business-record adapter.
80
+ Legacy `verify(presentation_json:)` checks syntax only and never returns successful
81
+ Evidence. [Exact APIs and result/error conventions](docs/PUBLIC_API.md).
82
+
83
+ ## Install and support
84
+
85
+ Formal support: **MRI 3.4.12 and 4.0.9**. For this walkthrough use
86
+ `gem "ap2_mandate_verifier", "= 1.6.0"` in a Gemfile. Applications following stable
87
+ 1.x may use `"~> 1.0"` and review lockfile updates. `~> 0.8.0` excludes 1.x;
88
+ [upgrade notes](docs/RELEASE_100.md) retain the compatibility details.
89
+
90
+ Runtime pins: JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2,
91
+ Digest 3.2.1. Installation may download/build native dependencies. Do not loosen
92
+ pins to bypass a conflict. The resolution interval does not certify every Ruby,
93
+ OS or provider. [Support contract](docs/SUPPORT_CONTRACT.md).
94
+
95
+ ## Responsibilities before using this in your app
96
+
97
+ The core verifier performs no network or payment operations. Optional acceptance
98
+ stores perform local database transactions; SQLite requires a separately installed
99
+ driver. **Verification, durable reservation, application authorization and settlement
100
+ are separate events.**
101
+
102
+ Your app owns authentication, consent, protected approval records, independently
103
+ trusted current keys/revocation/profile policy, order/challenge state and clock.
104
+ It must recheck current authority, durably consume one-use state atomically, handle
105
+ uncertain results, and decide whether to call a processor. SDK acceptance and
106
+ Receipt authentication do not establish real Issuer trust or processor exactly-once.
107
+ Missing/invalid Receipt or unknown effect stays pending for reconciliation; do not
108
+ automatically retry or refund allowance on timeout/Error.
109
+
110
+ Unknown/unsupported forms fail closed. Exceptions, unavailable results and missing
111
+ results never authorize an operation. Do not log private keys, raw Mandates/nonces
112
+ or treat serialized Evidence as an authenticated credential. General AP2/all-Schema
113
+ conformance, real-Issuer interoperability and production GO are not claimed.
114
+ [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md),
115
+ [security policy](SECURITY.md), [acceptance boundaries](docs/PAYMENT_ACCEPTANCE.md).
116
+
117
+ ## Reference and retained evidence
118
+
119
+ - [Public API](docs/PUBLIC_API.md), [InputBuilder guide](docs/INPUT_BUILDER.md), [diagnostics](docs/DIAGNOSTICS.md).
120
+ - [1.6.0 publication verification](docs/POST_RELEASE_160.md), [changelog](CHANGELOG.md), [project/publication history](docs/PROJECT_STATUS.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md).
121
+ - [Merchant signing](docs/MERCHANT_SIGNING.md), [multiple items](docs/MULTI_ITEM_CHECKOUT.md), [Python differences](docs/MULTI_ITEM_INTEROP.md).
122
+
123
+ Historical release and research documents remain evidence for their recorded
124
+ versions, not the current onboarding path. Repository documentation changes do
125
+ not rebuild or replace the already published 1.6.0 Gem.
126
+
127
+ <details>
128
+ <summary>Source-checkout InputBuilder walkthrough (advanced)</summary>
151
129
 
152
130
  ## A small InputBuilder example
153
131
 
@@ -197,74 +175,5 @@ Expected for these unchanged synthetic inputs: `verified_research/scoped_researc
197
175
 
198
176
  Do not call `prepare` again during verification or update saved hashes/references to match current values. Changed orders, trust or signed bytes must remain detectable. Persisted trust JSON can be loaded with `restore_trust` without reserializing it. The [complete example](examples/input_builder.rb) includes normal/tampered/expired cases; the [input guide](docs/INPUT_BUILDER.md) explains the business fields, exact restoration and Rails model mapping.
199
177
 
200
- ## Results and responsibility boundaries
201
178
 
202
- The following table applies to complete Open → Agent Closed verification through
203
- InputBuilder or `verify_checkout`. Direct, Checkout and Receipt APIs retain their
204
- own `verified?` or exception contracts; see [all result conventions](docs/PUBLIC_API.md#result-object-and-failure-contracts).
205
-
206
- | Result | Meaning and next step |
207
- | --- | --- |
208
- | `:verified_research` / `:scoped_research_verified`, `success? == true` | Immutable Evidence contains checked facts for the fixed profile. The Host must still decide whether to authorize the purchase. |
209
- | `:rejected`, `rejected? == true` | No Evidence. Stop and inspect `result.code`. |
210
- | `:unavailable`, `unavailable? == true` | No Evidence. Stop; a dependency or processing failure is not proof of invalid business data. |
211
-
212
- On failure, inspect supplemental check candidates. Successful results have no failure diagnostic.
213
-
214
- ```ruby
215
- if (diagnostic = result.diagnostic)
216
- puts diagnostic.to_h(locale: :en) # :ja for Japanese
217
- end
218
- ```
219
-
220
- `stage / field / reason / hint` are guidance; they do not change status/code or the verdict. Unknown fields/causes are not asserted. See the [diagnostic guide](docs/DIAGNOSTICS.md).
221
-
222
- Exceptions, process failure and missing results also never authorize an operation. Do not log raw inputs/nonces or treat serialized Evidence as an authenticated credential.
223
-
224
- The Gem checks signatures, supported disclosure closure, delegation, purchase/Host bindings, constraints and validity. The Host supplies authenticated, independent and current trust/keys/revocation, order/challenge state and clock. Before acting, it rechecks current state and validity, atomically consumes the nonce with order CAS, handles uncertain outcomes, and makes the final authorization/payment decision. `prepare`/`restore` do not authenticate storage or prove an unused nonce.
225
-
226
- Published 1.0.0 retains the default `ap2.checkout.single_merchant_sku` v1 and the
227
- explicit [multi-item profile](docs/MULTI_ITEM_CHECKOUT.md). Conditional issuance
228
- uses that multi-item profile, with all candidates disclosed and existing limits.
229
- Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer
230
- interoperability, new selective-disclosure profiles, Rails adapters, DB/payment
231
- execution and numeric performance guarantees remain outside scope. Real
232
- Issuer/Host production GO and Phase 2-B remain separate HOLDs.
233
-
234
- ### Which API should I use?
235
-
236
- | Entry | Role |
237
- | --- | --- |
238
- | `ConditionalCheckout.issue_open/issue_closed/present` | Conditional issuance and original-wire presentation; full merchant verification remains required. |
239
- | `Buyer.issue_closed/present_closed/verify` | Direct exact-order issuance, structural presentation and full Direct verification. |
240
- | `CheckoutJWT.sign/verify` | Merchant Checkout signing and authentication before approval. |
241
- | `CheckoutReceipt.reference/sign/verify` | Original final-Mandate reference, explicit application outcome signing and Receipt authentication. |
242
- | `InputBuilder.verify(**business_information)` | Recommended business-data path. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
243
- | `verify_checkout(**inputs)` | Complete Open → Agent Closed verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
244
- | `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
245
- | `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
246
-
247
- Malformed assembly arguments, including missing keywords, to `InputBuilder.verify` return `:rejected / :invalid_host_context`. Assembly dependency/unexpected failures return `:unavailable / :research_verification_unavailable`; results from the complete core retain their codes. In contrast, missing/unknown keywords to the direct `verify_checkout` / `verify_research` entries return `:unavailable / :research_verification_unavailable`. Every such failure has `success? == false` and `evidence == nil`. See [the exact contract](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs) for shapes, bounds and Ruby argument-binding caveats.
248
-
249
- ## More detail
250
-
251
- - [1.x public API, errors, profiles and persistence contract](docs/PUBLIC_API.md). Existing partial-verification APIs remain supported and never return successful Evidence.
252
- - [Business-data lifecycle and Rails mapping](docs/INPUT_BUILDER.md), [complete Ruby example](examples/input_builder.rb) and [before/after example](examples/input_builder_before.rb).
253
- - [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
254
- - [1.0.0 Release notes](docs/RELEASE_100.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
255
- - [Pinned historical seven-input / saved FULL example](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#try-the-saved-synthetic-example), [older artifact/provider evidence](research/stable010_release_linux_package/README.md) and [historical conceptual diagrams](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#illustrated-concepts-japanese-diagrams). These records are preserved, not current integration instructions or broader support claims.
256
- - [Security reporting](SECURITY.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and [product direction](docs/PRODUCT_VISION.md). Do not include secrets, real Mandates or personal data in reports.
257
-
258
- MIT. See [LICENSE](LICENSE).
259
-
260
- ### Buyer Direct checkout (published 0.7.0)
261
-
262
- Trusted Surface backends can verify a merchant Checkout before approval, issue a
263
- Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
264
- `AP2MandateVerifier::Buyer` module verifies Direct Closed-only presentations at
265
- the merchant and uses `CheckoutReceipt` with `profile_ref: Buyer::PROFILE_REF`.
266
- One merchant, 1–8 lines, multiple products and quantities are supported end to end.
267
- Existing Open→Agent Closed APIs and both profiles retain their contracts.
268
- See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
269
- [runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
270
- is not purchasing authority or payment success. See the [short verified buyer-flow sample](docs/RELEASE_070.md).
179
+ </details>
data/docs/LONG_PAYMENT.md CHANGED
@@ -1,4 +1,6 @@
1
- # Long Open Payment: explicit JPY / UTC monthly profile (1.6.0 candidate)
1
+ # Long Open Payment: explicit JPY / UTC monthly profile (1.6.0)
2
+
3
+ Published on RubyGems; [exact distribution and validation](POST_RELEASE_160.md). Packaged preparation notes retain their historical scope.
2
4
 
3
5
  `LongPayment` supports one signed Open Checkout and one signed Open Payment reused across approved UTC calendar months. Every Closed preserves its own Open's content `iat`/`exp`; each outer KB proof is fresh, bound to audience/nonce/original presentation. Content validity and permission to start execution are separate. This is a framework-independent Ruby SDK; no Rails, scheduler or payment processor is required or invoked.
4
6
 
@@ -2,6 +2,11 @@
2
2
 
3
3
  [Verified public distribution](POST_RELEASE_150.md).
4
4
 
5
+ For a runnable application walkthrough, see [Ruby integration and restart recovery](RUBY_INTEGRATION.md)
6
+ ([日本語](RUBY_INTEGRATION.ja.md)). It keeps application and mock processor state across
7
+ actual Ruby process termination. The older `examples/payment_acceptance.rb` reopens
8
+ a Store in the same process with an in-memory mock result; it is not a process-restart example.
9
+
5
10
  This opt-in application-side coordinator separates three events: cryptographic verification, durable reservation of an approved business occurrence, and an external payment processor’s outcome. Existing1.x verifiers and their result meanings remain unchanged. The SDK does not call a processor, transfer funds or promise distributed exactly-once execution.
6
11
 
7
12
  ## Stable identity and protected approval
data/docs/PUBLIC_API.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Ruby SDK public API — 1.x
2
2
 
3
- **Status: published 1.5.0; the original 1.0.0 Checkout contract below is preserved.**
3
+ **Status: published 1.6.0; the original 1.0.0 Checkout contract below is preserved.**
4
4
  This document defines the 1.x contract for the existing Checkout APIs.
5
5
  The 1.0.0 release preserves the 0.8.0 runtime behavior, API names and accepted
6
6
  formats. Exact distribution identity and validation are in
@@ -1,4 +1,6 @@
1
- # Repeated Payment approval: explicit JPY/ON_DEMAND subset (1.6.0 candidate)
1
+ # Repeated Payment approval: explicit JPY/ON_DEMAND subset (1.6.0)
2
+
3
+ Published on RubyGems; [exact distribution and validation](POST_RELEASE_160.md). Packaged preparation notes retain their historical scope.
2
4
 
3
5
  This additive profile supports several separately approved Payment occurrences under one signed Open, with finite occurrence and cumulative JPY reservation limits. It is not a scheduler, generic recurring-payment implementation or payment executor. Existing profiles, seven-input Checkout contract, default verifier results and 600-second Mandate lifetime remain unchanged. This bounded profile does not provide long subscriptions. The separate [LongPayment profile](LONG_PAYMENT.md) adds explicit UTC-calendar-month windows and long content with fresh proofs.
4
6
 
@@ -51,4 +53,4 @@ The recurring reference adapter uses an explicit **new schema2 database** with t
51
53
 
52
54
  One authoritative durable local ledger must serve every worker and occurrence for an agreement. A per-process database, multiple independent stores, rollback/loss, restoring a stale backup or splitting one consent into fresh IDs destroys the protection. Authenticated stable identities, genuine consent, full-Open confidentiality, current order/nonce/revocation CAS, processor idempotency/query and outcome reconciliation remain application duties. Custom adapters must make authorization, quota checks/updates, occurrence reservation and fenced start atomic with current authority. An external precheck followed by an independent database write is insufficient.
53
55
 
54
- No actual Issuer/Host provenance, production durability, external exactly-once settlement, refund semantics, distributed coordination, automatic scheduling, non-JPY budgets or calendar recurrence is claimed. This candidate covers bounded ON_DEMAND repeated use within existing validity; the broader monthly-subscription goal remains deferred pending a precise safe contract.
56
+ No actual Issuer/Host provenance, production durability, external exactly-once settlement, refund semantics, distributed coordination, automatic scheduling, non-JPY budgets or calendar recurrence is claimed. This profile covers bounded ON_DEMAND repeated use within existing validity; the separate [LongPayment contract](LONG_PAYMENT.md) defines the supported local UTC-calendar-month policy.
@@ -1,6 +1,6 @@
1
1
  # 1.6.0 candidate: long Open and UTC-monthly JPY acceptance
2
2
 
3
- Unpublished preparation; RubyGems, formal tag and GitHub Release require OwnerGO. No production/payment authority follows from tests, review or merge. The earlier bounded ON_DEMAND candidate is retained separately as historical evidence; it is not replaced in the registry.
3
+ Historical preparation record. Owner subsequently approved publication; [the publication record](POST_RELEASE_160.md) supersedes the availability status below. No production/payment authority follows from tests, review or merge. The earlier bounded ON_DEMAND candidate is retained separately as historical evidence; it is not replaced in the registry.
4
4
 
5
5
  ## Proposed notes and primary use
6
6
 
@@ -0,0 +1,30 @@
1
+ # 1.6.1 patch release preparation
2
+
3
+ ## Scope and status
4
+
5
+ This record prepares the patch following [PR #256](https://github.com/cuichangquan/ap2-mandate-verifier/pull/256).
6
+ The Owner requested distribution of the newly bundled Ruby integration and crash-recovery example.
7
+ The Owner will execute the final RubyGems push and complete MFA; the agent prepares and verifies the archive and commands only.
8
+ The SDK `lib/` implementation, public APIs, runtime dependency pins and Ruby requirements are unchanged.
9
+ The package includes the CLI, two helpers and English/Japanese guides already reviewed in #256.
10
+ The sample remains synthetic and Linux/Docker-validated; it grants no production or real-payment authority.
11
+ The legacy published examples and the public **1.6.0** archive audits remain unchanged.
12
+
13
+ **Candidate, not published:** registry publication, tag and GitHub Release are pending.
14
+ Do not infer publication from this document, a green CI run, version metadata, or a merge.
15
+ The current public baseline remains [1.6.0](https://github.com/cuichangquan/ap2-mandate-verifier/blob/main/docs/POST_RELEASE_160.md).
16
+
17
+ ## Required evidence and gates
18
+
19
+ - Build one exact 1.6.1 archive in the fixed MRI 4.0.9 Docker builder with `SOURCE_DATE_EPOCH=1794319977`, repeat the build byte-for-byte, and record SHA256/size.
20
+ - Run source and ordinary installed-package regressions on MRI 3.4.12 and 4.0.9 using that **same archive**, including the separate-process integration/recovery suite.
21
+ - Compare every payload file among source, extracted archive and actual installed files; verify metadata, dependency pins and no native extension or secret fixture.
22
+ - Keep public-1.6.0 tests pinned to 1.6.0. Candidate tests explicitly pass `AP2_GEM_VERSION=1.6.1`; do not weaken version identity checks to a range.
23
+ - Obtain independent Codex review on the latest PR HEAD, resolve substantive findings, and pass the required CI and repository merge conditions. No auto-merge; at most three workflow runs, attempt 1, for this PR.
24
+ - After merge, verify the reviewed and merged trees match and the fixed-builder merged-source archive is byte-identical.
25
+ - Present the final archive identity and verification to the Owner. Only explicit OwnerGO for those final bytes permits **one** publication attempt.
26
+ - Inspect the registry before publishing and after any uncertain outcome. Never blindly retry a push, overwrite a version, or create a replacement artifact under the same approval.
27
+ - Verify actual registry bytes/metadata and ordinary installation before creating the annotated tag and non-prerelease GitHub Release at the released source commit. Preserve the archive and public evidence.
28
+
29
+ No merge/push workflow publishes or deploys. No direct Mac installation, credentials disclosure,
30
+ new persistent access, real payment, production database or demo deployment is included.