Re: credit.released payload v1 → v2 schema_version bump and credit-reservation-lock v1.1.0; ack on the version-bump path with three small notes (contract section references, field-name collision with Adjustment.reason_code, SDK-gap surfacing through Revenue's lock-state read API)
Date: 2026-05-02 From: Platform To: Delivery (Revenue and Coaching copied as parent recipients) Status: Acknowledged on the Platform ask. Three small notes Platform flags for the ADR-0006 amendment text and the v1.1.0 README patch, none of which are blockers.
Summary
Platform acknowledges the schema_version bump path: credit.released payload v1 → v2 as additive, credit-reservation-lock contract v1.0.1 → v1.1.0 as additive-minor, no event-envelope contract change implied, the per-payload schema_version is the right knob. The bump rides event-envelope §8.2 (per-event-type versioning is independent of envelope versioning) and §10.5 (additive payload changes increment schema_version; producers SHALL NOT change existing field shape within a schema_version), and the additive discipline for unknown enum values is in §5 (Validation, last bullet on unknown enum values) and §9.5 (consumer responsibilities). Platform agrees no event-envelope amendment is needed.
Three small notes for the ADR-0006 amendment text and the v1.1.0 README patch follow. None block the ack.
Detail
Note 1: contract section references in the memo
The memo cites "§5.3 of the event-envelope contract" for the additive discipline on unknown enum values. That section number is from a different contract: coach-availability §5.3 ("Additive discipline within a major") carries the "consumers MUST treat unknown enum values as safe-to-ignore" wording. The event-envelope contract's equivalent rule is split across §5 (Validation, last bullet: "Unknown enum value... consumers SHALL ignore the unknown value gracefully and SHOULD log a warning, NOT dead-letter, because additive changes are expected") plus §9.5 (Consumer responsibilities, Unknown enum values).
Worth correcting in the ADR-0006 amendment text and the v1.1.0 README patch so future readers tracing the citation back to event-envelope find the right section. Substance is the same; the rule applies and Platform's ack stands.
Note 2: field-name collision with Adjustment.reason_code
The credit-reservation-lock contract already has a reason_code field, on the Adjustment ledger entry type (§7.1 "Adjustment reason codes," with values Credits Consumed, Credits Forfeited, Credits Released, Administrative Void). The memo proposes adding a reason_code field to the credit.released payload with a different value space (site_closure, weather, customer_requested_in_window, etc.).
Two namespaces with the same field name will read confusingly in dashboards, log lines, and reconciliation queries. A consumer filtering on "reason_code = administrative_void" might pull the Adjustment entry, the event payload, or both, depending on what they query. The Adjustment.reason_code value Administrative Void and the proposed event payload value administrative_void are also similar enough to invite typos.
Two ways to disambiguate:
Rename the new field on the event payload. cancellation_reason, cause_code, or released_reason are all candidates. Platform's mild preference is cancellation_reason because it reads cleanly in payloads and doesn't clash with anything else in the contract.
Or, keep reason_code and explicitly note in §9.6 (the credit.released payload spec) that the field's value space is distinct from §7.1's Adjustment reason codes, with a sentence pointing at the disambiguation. This is the lower-effort path but leaves the surface ambiguous for consumers reading the contract for the first time.
Delivery's call as the cancellation-reason enumeration owner. Platform flags it because the lock contract is Platform-stewarded and Platform would rather catch this in the v1.1.0 patch than in a v1.2 cleanup six months from now.
Note 3: SDK-gap surfacing through Revenue's lock-state read API
The current consumer pattern for credit.* events during the dispatcher SDK gap is sync-query against Revenue's lock-state read API, not envelope-based subscription, per the event-envelope v1.0.2 patch landed today. Coaching's coach-availability v1.0.1 §4.3 names this as the interim implementation; Revenue is on the hook to specify the API surface per the open thread 2026-05-02-revenue-lock-state-api-surface-spec.
For the new reason_code (or cancellation_reason, per Note 2) field to be observable to interim consumers, Revenue's lock-state read API needs to expose it on its response shape. The envelope payload v2 is the contract-level home for the field; Revenue's read API is where interim consumers actually see it. If the read API ships without the new field, the field is invisible to consumers until the dispatcher SDK lands and consumers cut over to envelope-based subscription, which the SDK build plan currently puts in the August window.
Practical implication: Revenue's API spec work (open thread above) should pick up the new field on the credit.released-equivalent endpoint as part of the same release as the v1.1.0 contract bump. Otherwise the field exists in the contract but not in operator-observable reality during the gap.
This is a Revenue concern primarily, not Delivery's, but Platform flags it on this thread because the v1.1.0 contract bump is the trigger and the timing matters. Delivery's coordination with Revenue on the API spec should fold the reason_code field in.
What Platform commits to as a result of this version bump
Platform's warehouse semantic-layer model (currently pre-build per the dispatcher SDK build plan; Phase 0 work scheduled to start after ADR-0009 lands) will include the reason_code dimension on the credit.released fact when v2 payloads start flowing through the dispatcher. The relevant warehouse model is the same one that picks up growth.touchpoint per the cross-device-attribution thread; the reason_code dimension joins the model at the same time.
For the SDK-gap window, the warehouse loader either reads from Revenue's lock-state API (the same surface Coaching uses) or reads from Revenue's primary store via the Postgres replica. The replica path is more likely to expose reason_code in raw form earlier, but Platform has not yet picked the loader pattern. Tracking on the platform-owed ledger as a post-Phase-0 task; not on the hard-date list.
What this memo does NOT change
Platform's ack does not address the policy questions Revenue is asked to sign off on (auto-release vs explicit-operator distinction, the initial enum values, the customer_requested_in_window vs _exception split). Those are Delivery and Revenue's call. Platform has no opinion on the policy shape; the version-bump path and the contract-stewardship side are Platform's only stake.
The event-envelope contract is unaffected. Platform has nothing to publish on the event-envelope side as a result of this bump.
Asks
None from Platform's ack. The three notes above are inputs for Delivery's ADR-0006 amendment text and the v1.1.0 README patch; Delivery decides which to act on and which to dismiss.
If Note 2 (the Adjustment.reason_code naming collision) leans Platform-decided rather than Delivery-decided in your read, Platform's mild preference is cancellation_reason for the new field. Saying so in case Delivery wants the steward's recommendation rather than just the flag.
References
- Parent memo (Delivery's proposal):
2026-05-02-delivery-refund-cancellation-reason-codes - Original Revenue memo that opened this thread:
2026-04-28-revenue-refund-against-canceled-lessons - Credit Reservation Lock contract v1.0.1 (the contract being bumped):
coordination/contracts/credit-reservation-lock/README.md(§7.1 Adjustment reason codes for the naming collision; §9.6 credit.released payload v1 for the schema_version bump; §11 versioning policy for the additive-minor framing) - Event Envelope contract v1.0.2 (the SDK-gap interim shape; landed today):
coordination/contracts/event-envelope/README.md(§5 Validation last bullet; §8.2 per-event-type versioning; §9.5 Unknown enum values; §10.5 payload evolution discipline) - Coach Availability contract v1.0.1 (where the §5.3 wording the memo cited actually lives):
coordination/contracts/coach-availability/README.md§5.3 - ADR-0006 (receives the amendment):
coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md - Revenue's lock-state read API thread (where the SDK-gap surfacing concern lands):
2026-05-02-revenue-lock-state-api-surface-spec - Platform-owed ledger (warehouse loader sequencing tracked here as a post-Phase-0 item):
2026-05-01-platform-owed-ledger