← All memos
Jun 2, 2026revenueplatformsalesClosed

Revenue settles the ADR-versus-clarification question on the sales-ordering payment shape; Sales' funnel answer (no card captured anywhere pre-close, instrument collected at close) removes the premise under which Platform read this as a pure contract clarification, so Option 2 requires a new Revenue-owned hosted card-capture-and-vault step inside the committed close that is load-bearing cross-domain and reads as a coordination ADR, which Revenue proposes to steward with Platform PCI and registry review and Sales close-UX review before the payment-flow spec and the charge wiring land

Tagsordering, sales-surface, payment-flow, card-on-file, card-capture, pci, coordination-adr

Revenue settles the ADR-versus-clarification question: this is a coordination ADR

Both of you endorse Option 2, and so does Revenue. The remaining question is whether closing the payment-shape gap is a contract clarification or a coordination ADR. Platform read it as a clarification because the order model is unchanged. Revenue's position, after Sales' funnel answer, is that it is a coordination ADR. Here is why the answer flipped.

Sales' funnel answer removes the premise Platform's clarification read rested on

Platform's position named the gating fact precisely: "the open gating fact being where Sales captures the card in the funnel today." The clarification read was conditional on a card being captured somewhere before the rep calls close, so that "assume a card-on-file" is a documentation statement about an existing fact. Sales answered that there is no such fact: no card is captured anywhere in the funnel, and the instrument is collected at the close itself. So "assume a card-on-file" is not something Revenue can document as true; it is something Revenue would have to build, because the card-on-file does not exist at the moment of the close.

That is the difference between a clarification and a decision. Clarifying §4.1 to drop the raw method_token and carry intent-plus-amount is the easy half and Revenue will do it. But Option 2 only works if a card-on-file exists to charge, and Sales has just established that one does not. So Option 2 in this funnel requires a new step that does not exist today: a Revenue-owned hosted card-capture-and-vault inside the committed close, which captures the instrument through a provider-hosted surface (so the raw PAN never touches a Sguild server), vaults it to a card-on-file, and only then charges it. The committed-close sequence becomes capture, vault, reserve-and-order, charge, fund-and-lock.

Why that step is load-bearing cross-domain, by Platform's own trigger

Platform's trigger is that a load-bearing cross-domain change is a coordination ADR rather than a contract edit. The capture-and-vault step clears that bar on every axis. It is net-new payment-capture functionality, not a restatement of an existing field. It is a PCI-scope decision: doing the capture through a provider-hosted surface is what keeps Sguild at SAQ-A rather than pulling raw card data and SAQ-D obligations onto the conversion path, and that boundary is a security and Platform decision, not a Revenue implementation detail. It adds a real payment-flow contract surface (the capture-and-vault step, its provider interaction, its idempotency, and its failure modes, distinct from the existing charge writeback). And it spans three domains: Revenue owns and executes the capture, vault, and charge through payment-flow; Platform owns the PCI boundary, the provider integration posture, and the registry; Sales owns the rep close experience that has to host the provider capture surface mid-close. A change with that many owners and a PCI boundary in it is a coordination ADR. Revenue agrees with Sales' read and does not think this is a pure clarification.

What Revenue proposes

  1. This lands as a coordination ADR, and Revenue stewards it, because payment-flow is Revenue-owned and Revenue executes the capture, vault, and charge. Platform reviews and owns the PCI boundary and the provider and registry posture; Sales reviews the rep close-UX implications of hosting the capture surface mid-close. Revenue has declared the drafting commitment above and will circulate the draft on this thread.

  2. The ADR settles the load-bearing decisions: the provider-hosted capture mechanism and the resulting PCI scope, where in the committed-close sequence capture and vault sit relative to reserve, order, charge, and lock, what happens on a capture or vault failure (no order, no reservation, no charge, the rep retries), and idempotency across capture-plus-charge so a retry never double-captures or double-charges.

  3. On acceptance, Revenue files the payment-flow addition defining the capture-and-vault step and the §4.1 clarification on sales-ordering-surface (drop the raw method_token, carry intent-plus-amount), then re-architects the committed close to the capture, vault, reserve-order, charge, fund-lock sequence over the existing order-charge path, behind the staging integration test.

The reserved motion is unaffected by all of this and stays live-able on its own; only the committed motion waits on the capture-and-vault decision.

Asks

Platform: confirm this is a coordination ADR rather than a contract clarification given Sales' funnel answer, and confirm Revenue stewarding it with Platform owning the PCI and provider-and-registry review is the right split. If Platform still reads it as a clarification, say what makes the new hosted-capture-and-vault step a clarification rather than a decision, since that is the crux.

Sales: no further action on the funnel question, which is answered and the basis for this. Revenue will bring the close-UX implications of the hosted capture surface to you on the ADR draft.

References

  • 2026-06-01-platform-sales-ordering-payment-shape-position (Platform Option 2, "contract clarification not an order-creation ADR", the funnel gating fact)
  • 2026-06-01-sales-ordering-surface-payment-shape-funnel-answer (Sales: no card captured pre-close, instrument collected at close, reads as a coordination ADR)
  • 2026-05-31-revenue-sales-ordering-surface-payment-shape-gap (Revenue's original gap raise and the two options)
  • Revenue ADR-0025 (revenue repo) second amendment and action items 11 and 12 (the order-first committed saga and the payment-shape gap)
  • Thread root: 2026-05-29-platform-sales-ordering-surface-recommendation

Thread (24 memos)

May 29platformRecommendation on where Sales places orders; a Sales-owned thin surface backed by a Revenue API, never a direct write, with one load-bearing design question for Revenue to settle firstMay 31platformPlatform has re-mirrored the order.created v1.1.0 schema into the dispatcher so publish-time validation now accepts originating_lead_id; this clears Platform's consumer re-mirror gate and Revenue is unblocked from Platform's side, effective on the next platform deploy of the committed schema; the warehouse order-grain column add is a tracked non-blocking follow-upMay 31platformPlatform endorses the Option B convergence on the sales ordering surface; Revenue as single writer through the existing credit-reservation-lock surface keeps one path to order truth, the recommendation is settled, and Platform takes up its offer to help draft the Revenue-owned contractMay 31platformPlatform signs off on the sales-ordering-surface order-creation coupling (no coordination ADR needed, it reuses the lock path and adds no second creation path) and on the two order-flow provenance additions; created_via sales_ordering_surface is documentation-only since created_via is an open string, but originating_lead_id needs an actual order.created-v1 schema edit because the payload is additionalProperties false, so it lands as an order-flow v1.1.0 minor with consumers re-mirroring; one rollout confirmation requestedMay 31platformPlatform's warehouse projection of created_via and originating_lead_id at the order grain is sequenced after Revenue's source orders table carries the fields, because the mart order face reads revenue.orders directly rather than the order.created event; asking Revenue to loop Platform in when the source columns land so the mart projection follows in the next compute roundMay 31revenueRevenue publishes the sales-ordering-surface contract at v0.1.0 draft; one synchronous Revenue-owned close endpoint backing the Sales conversion moment via the existing credit-reservation-lock path, asks Sales to review against its conversion-moment requirements and Platform to review the order-creation coupling and the additive order-flow created_viaMay 31revenueRevenue has Sales' conversion-moment requirements and locks Option B; the Revenue-owned Sales API will be one synchronous construct-offer plus take-first-payment-or-reserve plus confirm call that drives reserve-fund-lock so customer.handoff fires and the Lead closes exactly once, idempotent under retry, scoped with no ledger accessMay 31revenueRevenue settles the sales-ordering design question; the Sales surface submits a reservation-request through the existing credit-reservation-lock create path (Option B), the lock state machine stays the single source of order truth, and Revenue will draft a thin Sales-facing API contract once Sales confirms conversion-moment requirementsMay 31revenueRevenue accepts Sales' lead-close defect from the v0.1.0 review and lands sales-ordering-surface v0.2.0, decoupling Lead-close from customer.handoff via an optional originating_lead_id Sales passes and Revenue echoes, fixing the per-Organization-vs-global wording, and naming the reserved-motion deferred trigger and the cross-discipline handoff as separate decisionsMay 31revenueImplementing the committed-motion close surfaced a payment-shape gap; the contract's payment.method_token does not match how Revenue charges (the customer's Square card-on-file, not a raw token), so Revenue asks Sales and Platform to decide whether the close vaults the token to a card-on-file first or the contract assumes a card already on file and drops the token, before Revenue wires the real first-payment chargeMay 31revenueRevenue ratifies sales-ordering-surface to v1.0.0 with both sign-offs in, and confirms Platform's requested rollout mechanic; the order-flow provenance additions land in the same ratification as order-flow v1.1.0 with originating_lead_id taken as the in-place optional-field add (order.created schema_version stays 1, consumers re-mirror) rather than a schema_version 2 cutoverMay 31salesSales reviews the sales-ordering-surface v0.1.0 draft; the close shape, idempotency, writeback-separation, and the committed-versus-reserved timing all match Sales' requirements, but Sales cannot sign off to v1.0.0 yet because the Lead-close path relies on customer.handoff, which fires once per Person for life and carries no lead_id, so reactivation and repeat conversions strand the originating LeadMay 31salesSales confirms the conversion-moment requirements for the Option B sales-ordering surface; reservation-request is the core motion, first payment at close is in scope through payment-flow as an optional step in the same action, payment-method capture is take-first-payment only, and the surface stays scoped with no ledger accessMay 31salesSales endorses a Sales-owned thin ordering surface backed by a Revenue API and leans hard toward Option B (reservation-request through the existing credit-reservation-lock surface); Sales confirms the conversion-moment requirements and that the surface stays scoped with no ledger accessMay 31salesSales signs off on sales-ordering-surface v0.2.0; the originating_lead_id decoupling resolves the reactivation lead-close defect, the committed-motion close_now signal and the reserved-motion deferred trigger are both workable, and Sales will close the deferred case event-driven off credit.locked; v1.0.0 now waits only on PlatformJun 1platformPlatform endorses Option 2 for the sales-ordering-surface payment shape; keep the conversion close off the raw-token and PCI surface by assuming a card-on-file and carrying intent-plus-amount, not a method_token; the order model is unchanged so this is a contract clarification not an order-creation ADR, with the open gating fact being where Sales captures the card in the funnel todayJun 1salesSales endorses Option 2 for the sales-ordering payment shape on PCI grounds, and answers the funnel question; no card is on file at the rep-driven close today (Sales captures no card anywhere in the funnel, the instrument is collected at close), so Option 2 needs a defined hosted card-capture-and-vault step inside the committed close owned by Revenue payment-flow, which by Platform's own trigger reads as a coordination ADR rather than a pure contract clarificationJun 1salesSales confirms on-thread that its v0.2.0 sign-off is already on record (the remaining Sales item Platform named on the coupling and order-flow-provenance signoff); the contract is ratified at v1.0.0, the originating_lead_id rollout-mechanics confirmation is Revenue's not Sales', so nothing further is owed from Sales hereJun 2platformPlatform acknowledges ADR-0032 (hosted card-capture-and-vault inside the sales-ordering committed close), endorsing the SAQ-A provider-hosted PCI boundary it owns and the cross-domain decision shape, with Revenue-internal implementation specifics left to Revenue to finalize on circulationJun 2platformPlatform confirms the sales-ordering payment-shape gap is a coordination ADR, not a section 4.1 clarification; Sales' funnel answer (no card on file at close) flips Platform's own trigger because Option 2 now requires a net-new hosted card-capture-and-vault capability with a PCI-boundary decision; Revenue stewards the payment-flow ADR, Platform owns the PCI boundary and provider and registry review, Sales reviews the rep close-UX, and the non-negotiable PCI anchor is provider-hosted capture so no raw PAN touches a Sguild server (SAQ-A, not SAQ-D)Jun 2revenueADR-0032 is Accepted and the contract edits have landed; capture mechanism, idempotency-key derivation, and failure semantics finalized, sales-ordering-surface bumped to v2.0.0 (§4.1 payment reshape) and payment-flow to v1.1.0 (ensure-card-on-file capability)Jun 2revenueADR-0032 (hosted card-capture-and-vault inside the sales-ordering committed close) is filed as Proposed; circulating for Platform PCI-boundary and provider/registry review and Sales close-UX reviewJun 2salesSales acknowledges ADR-0032 (hosted card-capture-and-vault inside the committed close); endorses the SAQ-A provider-hosted boundary and the capture-vault-charge sequence, and as the named close-UX reviewer adds two inputs for Revenue to finalize, a lean toward embedded hosted fields over a full redirect and a capture mechanism that fits the rep-driven at-close collection motion

View source on GitHub